matriz-viralidad

Dile tu nicho. El agente descubre qué hace que un video rompa su mediana — y lo convierte en tus próximos guiones.

Mucha gente publica "a ver qué pega". Matriz Viralidad es un agente que corre dentro de Claude Code y hace el trabajo que casi nadie hace: trae los videos más virales de tu cuenta o de los creadores que admiras con Apify, los ve uno por uno, los ordena en una matriz de 10 columnas, encuentra el patrón que se repite, escribe cinco guiones nuevos con ese patrón y los simula contra lo que ya pasó. Sin interfaz, sin programar: le escribes en español y trabaja.

Cómo se ve · Inicio rápido · El ciclo · La matriz · Comandos · Ver videos · Costos · Reglas de oro · Seguridad · Familia tododeia · FAQ

Cómo se ve

Una sesión real de punta a punta toma entre 20 y 40 minutos (casi todo es espera de Apify y análisis de video). Así empieza, recortada
(los números son un ejemplo ilustrativo):

Agente   Hola, soy tu analista de contenido. Reviso tus llaves (sin leerlas)...
         ✓ APIFY_TOKEN presente · ✓ ffmpeg · ✓ skill watch · ✗ GEMINI_API_KEY (opcional)

Agente   ¿A quién estudiamos: tu cuenta, o 2–3 creadores de referencia?
Tú       Apenas empiezo. Sigo a @creadora_a y @creador_b, hacen finanzas para freelancers.

Agente   Costo estimado: 40 reels de cada una, 2 cuentas → ≈ $0.21. Tope duro: $1.00.
         ¿Corro?  →  Sí
Agente   Listo. Mediana de @creadora_a: 7,300 views (13 piezas). 3 piezas pasan 1.5x.
         ¿Cuáles analizo? Las 3 más virales cuestan ≈ $0.01 con audio, o $0 leyendo el subtítulo.

Agente   Matriz construida: 14 piezas, 3 patrones con evidencia suficiente (≥5 piezas).
         El que más se repite en lo que supera 1.5x: dato que sorprende + lista corta, 25–35 s.
         Lo que NO sé: hora de publicación, miniatura, edición y el humor del algoritmo.

Nada se descarga ni se gasta antes de que digas "sí".

Inicio rápido

Lo que necesitas antes: Claude Code (la app de escritorio, o la terminal), Node 20 o más nuevo
y una cuenta gratis de Apify (sin tarjeta; trae unos 5 USD de crédito al mes).
Opcionales: ffmpeg (leer videos por fotogramas), la skill watch (ver links de video) y una llave de Gemini (oír el audio).
Probado en macOS; en Linux debería funcionar igual; en Windows usa Git Bash o WSL (no lo he probado).

1. Clónalo y ábrelo en Claude Code (app de escritorio: Code → abrir carpeta; terminal: claude dentro de la carpeta):

git clone https://github.com/Hainrixz/matriz-viralidad && cd matriz-viralidad && claude

2. Confía en la carpeta. Claude Code te pregunta si confías en ella (la opción resaltada empieza en "No": elige "Sí, confío"). Eso activa el arranque automático
y los permisos del proyecto: bloquean leer tu .env, piden tu OK antes de cualquier corrida que cueste dinero y no dejan editar fuentes/.

3. Pega tu token de Apify, tú mismo. El agente nunca lee tus llaves: las pegas tú.

cp .env.example .env      # en Mac: open -e .env  (el Finder oculta los archivos con punto)
                          # pega tu token: APIFY_TOKEN=tu_token

El token sale de Apify → Settings → API & Integrations → Personal API token. .env está en .gitignore: no se sube.

4. El agente arranca solo y te hace cinco preguntas. Si no arrancó, escribe /matriz-start.

[!TIP]
¿Quieres ver cómo funciona antes de gastar o pegar nada? Con datos de ejemplo inventados (no son de ninguna cuenta real):
node scripts/mediana.mjs examples/demo/fuentes/instagram-reels-cuenta_demo-posts-demo.json

Como plugin, sin clonar. Desde cualquier carpeta, dentro de Claude Code:

/plugin marketplace add Hainrixz/matriz-viralidad
/plugin install matriz-viralidad@matriz-viralidad
/matriz-viralidad:matriz-start

En modo plugin los comandos llevan el prefijo matriz-viralidad:. Tus datos y tu .env viven en la carpeta donde abriste Claude Code, nunca dentro del plugin.

[!NOTE]
El modo plugin no arranca solo y no trae las reglas de permisos del proyecto (bloqueo del .env, confirmación de gasto en apify.mjs).
Lo que sí viaja con el plugin es un hook que bloquea que Claude lea tus llaves, y las reglas del agente siguen aplicando;
pero Claude Code te pedirá permiso en más pasos. Si puedes, clona el repo: es la experiencia completa.

El ciclo

El agente no te da un menú de cinco opciones: sigue un ciclo escrito y te dice en qué paso vas y por qué.

flowchart TD
    A["Abres el repo en Claude Code"] --> B["/matriz-start: revisa tus llaves y te entrevista (5 preguntas)"]
    B --> C{"¿Qué estudiamos?"}
    C -- "Mi cuenta" --> D["/matriz-analiticas: tu mediana y tus videos que sí rindieron"]
    C -- "Referencias" --> E["/matriz-espiar: la competencia con Apify, con costo y tope"]
    D --> F["Ve los videos: Gemini (audio) · watch · fotogramas"]
    E --> F
    F --> G["/matriz-construir: 10 columnas + patrones + un validador que la audita"]
    G --> H["/matriz-ganador: qué funciona y todavía no está saturado"]
    H --> I["/matriz-guion: 5 guiones nuevos + simulación"]
    I --> J["/matriz-calendario: el mes, cada día anclado a una pieza"]
    J --> K["/matriz-rutina cada semana: re-recolecta, actualiza, mide tus aciertos"]
    K --> E

La matriz

Cada video se vuelve una fila de una tabla con diez columnas. La que importa es RENDIMIENTO:

RENDIMIENTO = views de la pieza ÷ MEDIANA de views de ESA cuenta

Por qué la mediana y no el promedio: un solo video que explota sube el promedio y hace que todo lo demás parezca un fracaso. Y por qué por cuenta:
500k views en una cuenta de 10k seguidores valen más que 600k en una de 1M. Con el múltiplo (3.2x = el triple de lo normal ahí) puedes comparar cuentas de cualquier tamaño.

Junto a la tabla sale un segundo documento, patrones-de-viralidad.md, con cuatro secciones: qué funciona (patrones por encima de 1.5x, con las piezas citadas),
qué no funciona, el patrón de viralidad (un párrafo que junta hook, tema, formato, duración y emoción) y lo que no sabemos (hora de publicación, miniatura, edición
y el humor del algoritmo no están en los datos, y el documento lo dice).

Con menos de 5 piezas, un patrón se reporta pero no se recomienda: evidencia insuficiente. Antes de entregarla, un agente aparte (validador) audita la matriz:
que cada hook sea literal, que cada valor esté en las listas cerradas y que las medianas se recalculen desde los datos crudos.

Qué obtienes

Comandos

El orden natural: start → analiticas o espiar → construir → ganador → guion → calendario → rutina cada semana.

Cómo ve los videos

¹ Medido sobre 6 reels reales en agosto de 2026; el costo sube con la duración.

MATRIZ_ANALIZADOR en el .env (auto, gemini o local) decide el camino. En auto, si Gemini es inalcanzable el agente cae a fotogramas y te lo avisa
con lo que se pierde: el audio. Un video sin subtítulo quemado deja el hook en s/d: nunca usa el caption como si fuera el hook.

Para instalar watch (opcional): /plugin marketplace add bradautomates/claude-video y luego /plugin install watch@claude-video.

Cuánto cuesta

Poco, y lo ves antes de gastarlo. Precios del plan Free de Apify, consultados a su API pública el 2026-10-17 (los planes de pago son más baratos; cambian con el tiempo):

Cada corrida suma 0.001 USD de arranque. Un mes completo con 3 cuentas de Instagram (análisis inicial de 40 reels cada una + 4 rutinas semanales de 15) ronda 1 USD,
Gemini incluido si analizas una docena de videos. Tu crédito gratis de Apify es de unos 5 USD al mes.

• Las transcripciones de Apify son un add-on de pago (≈ 0.048 USD por minuto): este agente no las activa. El hook sale del análisis del video (Gemini, watch o fotogramas).
• Algunos actores cobran un mínimo por corrida; el número real sale al terminar (node scripts/revisar.mjs gasto suma el mes).
• Topes por defecto: análisis inicial --limite 40 --tope 1.00; rutina semanal --limite 15 --tope 0.50. El tope en dólares es duro: si Apify lo rechaza, el script se detiene en vez de correr sin freno.

Reglas de oro

1. Nunca copies frases literales. La matriz te da estructura y técnica (tipo de hook, formato, duración, emoción); las palabras son tuyas. scripts/similitud.mjs lo comprueba en cada guion.
2. Nunca dejes que Claude invente métricas. Lo que el scraper no da es s/d. Un s/d jamás se convierte en cero ni en promedio.
3. Publica también lo que puntúe bajo. La estimación ordena prioridades, no censura. Una simulación es una estimación basada en patrones pasados, no una predicción.

Seguridad

• Tus llaves no son de Claude. Las pegas tú en .env. Los scripts las leen por dentro; Claude solo puede preguntar "¿está o no está?" (node scripts/revisar.mjs llaves, que nunca muestra el valor).
  Un hook (scripts/guardia.mjs) bloquea cualquier intento de leer el .env o de imprimir una llave, también en modo plugin.
• El token viaja en un header (Authorization), no en la URL, y los scripts solo buscan el .env en la carpeta del proyecto.
• fuentes/ es de solo lectura: es el crudo tal cual salió del scraper. En modo clon, los permisos del proyecto impiden que Claude lo edite.
• Todo lo que gasta pide tu sí en el mismo turno, con el costo estimado a la vista.
• Solo contenido público. No entra a cuentas privadas, no usa tu sesión ni tus cookies, no baja mensajes directos.
• Nada se publica ni se programa desde aquí: el agente prepara; tú publicas.

Se conecta con el resto de la familia

Matriz Viralidad termina donde empieza la producción. Los guiones y la matriz son archivos de texto en tu carpeta, así que cualquier otro agente los puede leer:

Son sugerencias de flujo, no dependencias: Matriz Viralidad funciona sola.

Estructura del repo

matriz-viralidad/
├── CLAUDE.md                 reglas del modo clon (se carga solo al abrir el repo)
├── .claude/
│   ├── settings.json         agente de arranque, permisos y hook de seguridad
│   ├── agents/               matriz-viralidad (principal) + espia, analista-video, matricero,
│   │                         sentimiento, calendarista, simulador, validador
│   └── skills/               las 11 skills (los comandos) + matriz-metodologia (el método)
├── scripts/                  apify · mediana · gemini · fotogramas · descargar · revisar ·
│                             similitud · guardia · validar-repo   (Node, sin dependencias)
├── hooks/hooks.json          el mismo hook de seguridad para el modo plugin
├── examples/demo/            datos de ejemplo INVENTADOS para probar sin llaves
├── tests/                    pruebas offline (npm test)
└── assets/                   hero y vista previa

Tus datos se crean al usarlo y están en .gitignore: fuentes/ (crudo), videos/, transcripciones/, matriz/, guiones/, calendario/, perfil.json.

Preguntas frecuentes

¿Necesito saber programar? No. Escribes en español y el agente corre los scripts por ti.

¿Funciona en la app de escritorio de Claude Code? Sí, es la forma principal de uso: abre la carpeta clonada y habla. También funciona en la terminal. Si el arranque automático no se dispara en tu versión, escribe /matriz-start.

¿Y si apenas empiezo y no tengo contenido? Elige "creadores de referencia" en la primera pregunta: estudia a 2–3 cuentas de tu nicho y construye la matriz con ellas.

¿Por qué no usa las transcripciones de Apify? Hoy son un add-on de pago por minuto. Con Gemini, watch o fotogramas el hook sale igual y casi sin costo.

Me dice que un video no se descarga (403/404). Las direcciones de video de Instagram y TikTok caducan en minutos. Vuelve a correr /matriz-espiar y descarga enseguida.

¿Puedo usar el MCP de Apify en vez de los scripts? Puedes (claude mcp add --transport http apify https://mcp.apify.com), pero los scripts hacen cumplir los topes de gasto y guardan el crudo de forma determinista; por eso son el camino por defecto.

Algo no funciona. /matriz-doctor revisa tu instalación y te dice qué arreglar.

Aviso legal

Este sistema analiza únicamente contenido público: publicaciones y comentarios que cualquiera puede ver sin iniciar sesión. Lo que bajas se queda en tu computadora y es para estudiar patrones,
no para copiar ni republicar el trabajo de nadie. El contenido sigue siendo de sus autores. Respeta los términos de servicio de cada red y las leyes de datos personales de tu país: el uso es tu responsabilidad.
Las simulaciones son estimaciones sobre patrones pasados, no garantías de resultados. Los precios de Apify cambian: verifica en apify.com/pricing.

Acerca de

Basado en la guía Matriz de contenido viral de la comunidad tododeia. Construido por Enrique Rocha (@soyenriquerocha), con Claude Code.
Licencia MIT. ¿Quieres mejorarlo? Lee CONTRIBUTING.md. ¿Encontraste un problema de seguridad? Lee SECURITY.md.

_{Hecho por Enrique Rocha (@soyenriquerocha) · tododeia.com⁠​‌‌​​‌​‌​‌‌‌​​‌​​​‌​‌‌​‌​​‌‌​‌​‌​​‌‌​‌​​​​‌‌​​‌‌​​‌‌​‌​​​‌‌​​​‌​​​‌‌​​‌‌​​‌‌​‌‌‌​​‌‌​‌​‌⁠}