kkarpushin/reels-trends

Investigación de tendencias en Reels

Encuentra qué se volvió viral en Instagram Reels para un nicho en un período elegido y explica por qué, con un informe sobre el que el usuario puede actuar.

La métrica central es × respecto a la mediana del autor: vistas del reel divididas entre la mediana de vistas de los videos recientes del autor (mínimo 1.000). Esto separa los reels que volaron por el formato de aquellos que son grandes solo porque la cuenta es grande.

Los scripts se encuentran en ${CLAUDE_SKILL_DIR}/scripts/, las notas de referencia en ${CLAUDE_SKILL_DIR}/references/. Cada script recibe la carpeta de ejecución (RUN abajo) como primer argumento e imprime lo que hizo y lo que costó.

Antes de empezar

1. Token de Apify. Verifica echo ${APIFY_TOKEN:+set} o el archivo ~/.config/reels-trends/apify_token. Si ninguno existe, pide al usuario que cree un token en https://console.apify.com/settings/integrations y lo guarde con mkdir -p ~/.config/reels-trends && read -s T && echo "$T" > ~/.config/reels-trends/apify_token && chmod 600 ~/.config/reels-trends/apify_token. En Windows: setx APIFY_TOKEN "<token>" y reinicia la terminal. Nunca imprimas, registres ni confirmes el token.
2. Paquetes de Python. python3 -c "import lingua, PIL"; si falla: pip install lingua-language-detector pillow (añade --user o usa un entorno virtual si pip se niega). ffmpeg es opcional pero muy recomendado: sin él, los agentes etiquetan a los líderes solo desde las portadas. En Windows usa python donde este archivo dice python3.
3. Briefing. Pregunta solo lo que no puedas inferir, en un mensaje, con valores por defecto:
   • nicho, en palabras del usuario (y qué excluir, ej. "odontología, no estudiantes de odontología");
   • mercados: países o idiomas, o "todo el mundo";
   • período: por defecto los últimos 30 días; una ventana que termine hoy está bien, los reels más nuevos simplemente tienen menos vistas;
   • presupuesto en USD: por defecto $5 en un plan gratuito de Apify, $10-15 en uno de pago;
   • idioma del informe: por defecto el idioma en que escribe el usuario (las cadenas de la UI existen para ru y en).

Flujo de trabajo

1. Carpeta de ejecución y configuración

Crea reels-research/<slug-corto>/ en el proyecto actual (o donde el usuario quiera; si el proyecto es un repositorio git, añade reels-research/ a su .gitignore) y escribe config.json. Lee primero ${CLAUDE_SKILL_DIR}/references/config.md: explica cada campo y cómo escribir buenas consultas. Lo esencial:

• segments: uno por idioma o mercado, con 8-30 consultas nativas para mercados grandes (frases reales que la gente escribe, nombres de servicios, jerga) y 3-6 para pequeños, además de min_views escalado al mercado. Las consultas en inglés obtienen contenido de todo el mundo; escribe las consultas de cada mercado en su propio idioma.
• relevance_regex: raíces de palabras del nicho en cada idioma que busques (un reel debe coincidir para ser conservado).
• exclude_regex: lo que nunca debe contar (servicios para adultos, spam, significados no relacionados de la palabra del nicho).
• topics: 8-12 subtemas con expresiones regulares multilingües, ordenados del más específico al más genérico, más fallback_topic.
• focus_topics: temas que esperas comparar entre idiomas. ${CLAUDE_SKILL_DIR}/references/examples/ tiene una configuración mundial completa (masaje, 19 idiomas) y una configuración pequeña para plan gratuito.

2. Verificación de cuenta y costos

python3 ${CLAUDE_SKILL_DIR}/scripts/check.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/search.py RUN --dry

check.py lee el plan y elige el motor: memo23 en planes de pago de Apify (filtros de fecha y vistas en el servidor, los fallos son gratis) o hashtag en el plan gratuito (memo23 solo da una consulta con pocos resultados a cuentas gratuitas). Informa al usuario del plan, el motor, el costo máximo y el presupuesto en una o dos líneas. Los scripts nunca inician ejecuciones por encima del budget_usd restante; auméntalo solo con el consentimiento del usuario.

3. Búsqueda y fusión

python3 ${CLAUDE_SKILL_DIR}/scripts/search.py RUN          # 5-25 min, ejecútalo en segundo plano
python3 ${CLAUDE_SKILL_DIR}/scripts/merge.py RUN

Lee el resumen de la fusión antes de pagar por nada más:

• muchos not_in_niche: la expresión regular es demasiado restrictiva o las consultas se desvían; muchos reels conservados fuera de tema: la expresión regular es demasiado amplia;
• un idioma con muy pocos reels: añade consultas en ese idioma y ejecuta search.py RUN --only SEG --tag extra2, luego fusiona de nuevo (los archivos crudos se acumulan);
• en el motor de hashtag, outside_dates suele ser 70-90%: usa una ventana de 30-60 días, más hashtags específicos y variados, un search.hashtag_results mayor, o sugiere un plan de pago.

4. Autores, multiplicador, líderes

python3 ${CLAUDE_SKILL_DIR}/scripts/profiles.py RUN --dry   # luego sin --dry
python3 ${CLAUDE_SKILL_DIR}/scripts/score.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/leaders.py RUN

Los perfiles se obtienen solo para autores con un reel por encima de profiles.floor_by_lang; ajusta los pisos o --max para que quepa en el presupuesto. Líderes = mejores globales por × (con un piso de vistas) + mejores por vistas + mejores por × dentro de cada idioma. Apunta a 100-250 líderes en una ejecución mundial, 30-80 en un solo mercado.

5. Enriquecer los líderes (ejecuta los tres en paralelo)

python3 ${CLAUDE_SKILL_DIR}/scripts/transcripts.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/about.py RUN        # país de cada cuenta líder, solo planes de pago
python3 ${CLAUDE_SKILL_DIR}/scripts/media.py RUN        # tiras de 4 fotogramas + portadas; los enlaces CDN caducan en días, así que hazlo pronto después de la búsqueda

6. Etiquetar a los líderes desde los fotogramas

python3 ${CLAUDE_SKILL_DIR}/scripts/batches.py RUN --size 20

Escribe work/label_prompt.md (las instrucciones, ya rellenadas con la taxonomía de este nicho) y un archivo de lote por cada 20 líderes, e imprime las rutas BATCH y OUT. Inicia un sub-agente por lote, todos en un solo mensaje para que se ejecuten en paralelo, con este prompt:

Lee las instrucciones de etiquetado en RUN/work/label_prompt.md y síguelas exactamente. En esas instrucciones, {BATCH} = y {OUT} = .

Si los sub-agentes no están disponibles, etiqueta los lotes tú mismo con las mismas instrucciones. Las etiquetas deben provenir de observar los fotogramas: muchos reels en nichos visuales no tienen voz, y el pie de foto a menudo no describe lo que aparece en pantalla. Verifica la cobertura con python3 ${CLAUDE_SKILL_DIR}/scripts/labels.py RUN.

7. Revisión antes de contar

Abre los fotogramas de los 20 mejores líderes por × y de cada reel que un agente haya marcado o considerado irrelevante. Haz que las reglas sean consistentes entre lotes en work/overrides.json (formato en ${CLAUDE_SKILL_DIR}/references/content.md): por ejemplo, los reels solo de ejercicio no son masaje; las granjas de contenido que venden el cuerpo de una modelo en lugar del servicio van a "flagged": {"<código del reel>": "sexualizado"}; las republicaciones del video de otra persona reciben "repost". Los reels marcados permanecen en los datos y en la cuadrícula del informe (ocultos por defecto), pero no en la tabla de formatos ni en las ideas.

8. Números y la historia

python3 ${CLAUDE_SKILL_DIR}/scripts/stats.py RUN

Lee el resumen y encuentra 6-7 hallazgos sobre los que un dueño de negocio pueda actuar. Verifica cada afirmación con los datos antes de escribirla:

• una afirmación de que algo falta en un idioma necesita prueba de que buscaste en ese idioma con las palabras adecuadas (añade consultas y vuelve a ejecutar si no);
• los formatos con menos de 5 líderes reciben una advertencia de "pocos reels";
• calcula cualquier número extra con un breve fragmento de Python sobre work/scored.json y work/cls/, nunca de memoria. Luego escribe RUN/content.json siguiendo ${CLAUDE_SKILL_DIR}/references/content.md: hallazgos, notas para formatos, temas e idiomas, 8-10 ideas (título, un gancho que el usuario pueda decir en cámara, por qué funciona con números, 2-3 códigos de reel de ejemplo) y 12-16 ganchos para la sección de "primeros segundos".

9. Informe

python3 ${CLAUDE_SKILL_DIR}/scripts/build.py RUN

Produce report/index.html (ábrelo en un navegador), report/artifact.html (versión solo del cuerpo para publicar como artefacto de Claude, si el entorno tiene una herramienta de Artefacto) y report/reels.json (todos los reels con puntuaciones y etiquetas). Indica al usuario dónde está el informe, cuánto costó la ejecución en total (work/spend.jsonl), y los 3-5 hallazgos más útiles en palabras llanas.

Leyendo los números con honestidad

• La búsqueda devuelve reels notables, no todos los reels, por lo que las medianas son más altas que las de una cuenta típica. Compara grupos entre sí, no con los números propios del usuario.
• × es relativo al autor: las cuentas pequeñas producen los multiplicadores más grandes. Ese es el punto (el alcance no necesita seguidores), pero dilo.
• La tabla de formatos describe a los líderes, no a todo el nicho. Las tablas de tema, duración y seguidores usan todos los reels.
• Los reels de los últimos días de la ventana aún están acumulando vistas.
• Idioma no es país. Usa about.py para los países.

Más lecciones de ejecuciones reales están en ${CLAUDE_SKILL_DIR}/references/gotchas.md. Léelo antes de una ejecución mundial o multilingüe.