kkarpushin/reels-trends

Pesquisa de tendências do Reels

Encontra o que viralizou no Instagram Reels para um nicho em um período escolhido e explica por quê, com um relatório que o usuário pode usar.

A métrica principal é o × em relação à mediana do autor: visualizações do reel divididas pela mediana de visualizações dos vídeos recentes do autor (mínimo de 1.000). Ela separa reels que bombaram por causa do formato de reels que são grandes apenas porque a conta é grande.

Os scripts ficam em ${CLAUDE_SKILL_DIR}/scripts/, e as notas de referência em ${CLAUDE_SKILL_DIR}/references/. Cada script recebe a pasta de execução (RUN abaixo) como primeiro argumento e imprime o que fez e quanto custou.

Antes de começar

1. Token Apify. Verifique echo ${APIFY_TOKEN:+set} ou o arquivo ~/.config/reels-trends/apify_token. Se nenhum existir, peça ao usuário para criar um token em https://console.apify.com/settings/integrations e salvá-lo com mkdir -p ~/.config/reels-trends && read -s T && echo "$T" > ~/.config/reels-trends/apify_token && chmod 600 ~/.config/reels-trends/apify_token. No Windows: setx APIFY_TOKEN "<token>" e reinicie o terminal. Nunca imprima, registre ou envie o token.
2. Pacotes Python. python3 -c "import lingua, PIL"; se falhar: pip install lingua-language-detector pillow (adicione --user ou use um venv se o pip recusar). ffmpeg é opcional, mas fortemente recomendado: sem ele, os agentes rotulam líderes apenas a partir das capas. No Windows, use python onde este arquivo diz python3.
3. Briefing. Pergunte apenas o que não puder ser inferido, em uma única mensagem, com padrões:
   • nicho, nas palavras do usuário (e o que excluir, por exemplo, "odontologia, não estudantes de odontologia");
   • mercados: países ou idiomas, ou "o mundo inteiro";
   • período: padrão: últimos 30 dias; uma janela que termina hoje é aceitável, os reels mais novos simplesmente têm menos visualizações;
   • orçamento em USD: padrão: $5 em um plano Apify gratuito, $10-15 em um plano pago;
   • idioma do relatório: padrão: o idioma em que o usuário escreve (as strings de interface existem para ru e en).

Fluxo de trabalho

1. Pasta de execução e configuração

Crie reels-research/<slug-curto>/ no projeto atual (ou onde o usuário quiser; se o projeto for um repositório git, adicione reels-research/ ao .gitignore) e escreva config.json. Leia ${CLAUDE_SKILL_DIR}/references/config.md primeiro: ele explica cada campo e como escrever boas consultas. O essencial:

• segments: um por idioma ou mercado, com 8-30 consultas nativas para mercados grandes (frases reais que as pessoas digitam, nomes de serviços, gírias) e 3-6 para mercados pequenos, além de min_views dimensionado para o mercado. Consultas em inglês puxam conteúdo do mundo inteiro; escreva as consultas de cada mercado no seu próprio idioma.
• relevance_regex: radicais de palavras do nicho em cada idioma que você pesquisa (um reel deve corresponder para ser mantido).
• exclude_regex: o que nunca deve contar (serviços adultos, spam, significados não relacionados da palavra do nicho).
• topics: 8-12 subtópicos com regex multilíngues, ordenados do mais específico ao mais genérico, mais fallback_topic.
• focus_topics: tópicos que você espera comparar entre idiomas. ${CLAUDE_SKILL_DIR}/references/examples/ tem uma configuração mundial completa (massagem, 19 idiomas) e uma configuração pequena para o plano gratuito.

2. Verificação de conta e custo

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

check.py lê o plano e escolhe o mecanismo: memo23 em planos Apify pagos (filtros de data e visualizações no servidor, erros são gratuitos) ou hashtag no plano gratuito (o memo23 atende contas gratuitas apenas com uma consulta e poucos resultados). Informe ao usuário o plano, o mecanismo, o custo no pior caso e o orçamento em uma ou duas linhas. Os scripts nunca iniciam execuções acima do budget_usd restante; aumente-o apenas com o consentimento do usuário.

3. Busca e merge

python3 ${CLAUDE_SKILL_DIR}/scripts/search.py RUN          # 5-25 min, execute em segundo plano
python3 ${CLAUDE_SKILL_DIR}/scripts/merge.py RUN

Leia o resumo do merge antes de pagar por qualquer outra coisa:

• muitos not_in_niche: a regex é muito restrita ou as consultas estão desviando; muitos reels mantidos fora do tópico: a regex é muito ampla;
• um idioma com muito poucos reels: adicione consultas nesse idioma e execute search.py RUN --only SEG --tag extra2, depois faça o merge novamente (os arquivos brutos se acumulam);
• no mecanismo hashtag, outside_dates costuma ser 70-90%: use uma janela de 30 a 60 dias, mais hashtags e mais específicas, um search.hashtag_results maior, ou sugira um plano pago.

4. Autores, multiplicador, líderes

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

Os perfis são buscados apenas para autores com um reel acima de profiles.floor_by_lang; ajuste os pisos ou --max para caber no orçamento. Líderes = top global por × (com um piso de visualizações) + top por visualizações + top por × dentro de cada idioma. Mire em 100-250 líderes em uma execução mundial, 30-80 em um único mercado.

5. Enriqueça os líderes (execute os três em paralelo)

python3 ${CLAUDE_SKILL_DIR}/scripts/transcripts.py RUN
python3 ${CLAUDE_SKILL_DIR}/scripts/about.py RUN        # país de cada conta líder, apenas em planos pagos
python3 ${CLAUDE_SKILL_DIR}/scripts/media.py RUN        # tiras de 4 quadros + capas; links CDN expiram em dias, então faça logo após a busca

6. Rotule os líderes a partir dos quadros

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

Ele escreve work/label_prompt.md (as instruções, já preenchidas com a taxonomia deste nicho) e um arquivo de lote para cada grupo de 20 líderes, e imprime os caminhos BATCH e OUT. Lance um subagente por lote, todos em uma única mensagem para que sejam executados em paralelo, com este prompt:

Leia as instruções de rotulagem em RUN/work/label_prompt.md e siga-as exatamente. Nessas instruções, {BATCH} = e {OUT} = <caminho de saída>.

Se subagentes não estiverem disponíveis, rotule os lotes você mesmo com as mesmas instruções. Os rótulos devem vir da observação dos quadros: muitos reels em nichos visuais não têm fala, e a legenda muitas vezes não descreve o que está na tela. Verifique a cobertura com python3 ${CLAUDE_SKILL_DIR}/scripts/labels.py RUN.

7. Revise antes de contar

Abra os quadros dos 20 principais líderes por × e de cada reel que um agente sinalizou ou marcou como irrelevante. Torne as regras consistentes entre lotes em work/overrides.json (formato em ${CLAUDE_SKILL_DIR}/references/content.md): por exemplo, reels apenas de exercício não são massagem; fazendas de conteúdo que vendem o corpo de uma modelo em vez do serviço vão para "flagged": {"<código do reel>": "sexualised"}; republicações de vídeo de outra pessoa recebem "repost". Reels sinalizados permanecem nos dados e na grade do relatório (ocultos por padrão), mas não na tabela de formatos nem nas ideias.

8. Números e a história

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

Leia o resumo e encontre 6-7 descobertas que um empresário possa usar. Verifique cada alegação com os dados antes de escrevê-la:

• uma alegação de que algo está faltando em um idioma precisa de prova de que você pesquisou nesse idioma com as palavras certas (adicione consultas e execute novamente se não);
• formatos com menos de 5 líderes recebem uma ressalva de "poucos reels";
• calcule qualquer número extra com um pequeno trecho Python sobre work/scored.json e work/cls/, nunca de memória. Em seguida, escreva RUN/content.json seguindo ${CLAUDE_SKILL_DIR}/references/content.md: descobertas, notas para formatos, tópicos e idiomas, 8-10 ideias (título, um gancho que o usuário possa dizer na câmera, por que funciona com números, 2-3 códigos de reel de exemplo) e 12-16 ganchos para a seção de "primeiros segundos".

9. Relatório

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

Gera report/index.html (abra em um navegador), report/artifact.html (versão apenas do corpo para publicação como artefato Claude, se o ambiente tiver uma ferramenta de artefato) e report/reels.json (todos os reels com pontuações e rótulos). Informe ao usuário onde está o relatório, quanto custou a execução no total (work/spend.jsonl) e as 3-5 descobertas mais úteis em palavras simples.

Lendo os números com honestidade

• A busca retorna reels notáveis, não todos os reels, portanto as medianas são mais altas do que as de uma conta típica. Compare grupos entre si, não com os números do próprio usuário.
• × é relativo ao autor: contas pequenas produzem os maiores multiplicadores. Essa é a questão (alcance não precisa de seguidores), mas diga isso.
• A tabela de formatos descreve os líderes, não o nicho inteiro. As tabelas de tópico, duração e seguidores usam todos os reels.
• Reels dos últimos dias da janela ainda estão acumulando visualizações.
• Idioma não é país. Use about.py para países.

Mais lições de execuções reais estão em ${CLAUDE_SKILL_DIR}/references/gotchas.md. Leia-o antes de uma execução mundial ou multilíngue.