TheMattBerman/shortform-idea-engine

Motor de Ideias para Vídeos Curtos (Short-Form Idea Engine)

Pipeline de pesquisa a roteiro que transforma vídeos de concorrentes fora da curva em ideias ranqueadas e roteiros prontos.

Quando usar

Use este skill quando o usuário quiser um pipeline de ideias para vídeos curtos: descobrir o que está vencendo em um nicho, entender o porquê, gerar ideias remixadas e receber roteiros prontos para gravar.

Não use para:

• Um único vídeo conhecido que o usuário quer decodificar: encaminhe para video-decoder.
• Uma ideia que o usuário já tem e quer roteirizada: encaminhe para script-writer.

Dependências

Este é um plugin autocontido. Ele agrupa todos os sub-skills e o script auxiliar Gemini. Nenhum ambiente de skills compartilhado é necessário. Os requisitos externos obrigatórios são três chaves de API (veja a próxima seção).

Dependência	Função neste skill
Skill virlo (agregado)	Estágio 1 modo palavra-chave: descobre vídeos curtos fora da curva por palavra-chave de nicho no Instagram, TikTok e YouTube
Skill scrape (agregado)	Estágio 1 modo handles, Estágio 2 e resolução de URL CDN no Estágio 4: obtém posts recentes, transcrições, frames de capa e URLs de mídia direta via API ScrapeCreators
Skill video-decoder	Estágio 3 e Estágio 4: decodifica cada vídeo fora da curva em um Registro de Decodificação preenchido (gancho visual, gancho escrito, gancho falado, raiz, VV, IT, Formato)
Skill script-writer	Estágio 7: escreve um roteiro pronto para produção por ideia aprovada
Skill brand-profiler (agregado)	Estágio 0: constrói um novo perfil de marca quando nenhum existe, coletando todos os campos do esquema, incluindo voice_tone
scripts/gemini-video-analyze.js (agregado)	Estágio 4 passagem profunda: executa análise visual (ritmo, cadência de cortes, estilo visual, dispositivos de retenção, cadência de texto na tela) via OpenRouter Gemini

Chaves de API e degradação graciosa

Chaves necessárias: VIRLO_API_KEY, SCRAPECREATORS_API_KEY, OPENROUTER_API_KEY.

Carregue-as no Estágio 0 antes de qualquer gasto:

source .env

Regras de degradação:

Chave ausente	Efeito
VIRLO_API_KEY	O modo palavra-chave é desabilitado. O modo handles ainda funciona. Relate isso claramente no Estágio 0.
OPENROUTER_API_KEY	O Estágio 4 (passagem profunda) é totalmente ignorado. Todas as decodificações permanecem shallow. As ideias derivadas de decodificações rasas são sinalizadas como "shallow-decoded" na tabela ranqueada.
SCRAPECREATORS_API_KEY	O mecanismo não pode funcionar. ScrapeCreators é necessário para transcrições e frames de capa em todos os modos. Pare no Estágio 0 e informe o usuário claramente.

Pipeline

Estágio 0: Entrada

Pergunte ao usuário:

1. Modo: modo palavra-chave (descobrir vídeos por palavra-chave de nicho) ou modo handles (analisar handles de concorrentes específicos).
2. Caminho do perfil de marca: o caminho para um perfil de marca preenchido seguindo references/brand-profile-template.md. Se não existir, ofereça-se para construir um encadeando ao skill brand-profiler agregado, que coleta todos os campos do esquema (voice_tone, audience, positioning, content_pillars, anti_topics, forbidden_constructions, proof_credibility, format_preferences, on_camera_talent) interativamente ou a partir de um documento de marca existente.
3. Slug da execução: um rótulo curto em minúsculas para esta sessão (ex.: ai-tools-keyword ou techcreator-handles). Usado para nomear a pasta da execução.
4. Caminho base da execução: onde a pasta da execução deve ser criada. O padrão é ./shortform-runs/ relativo ao diretório de trabalho atual, produzindo ./shortform-runs/YYYY-MM-DD-<slug>/. Se a sessão estiver rodando dentro de um projeto estruturado que tem sua própria área de pesquisa ou saída, pergunte ao usuário se deseja colocar a execução lá. Confirme o caminho base resolvido com o usuário antes de escrever qualquer arquivo.

Verifique todas as três chaves de API. Relate quais modos estão disponíveis antes de gastar créditos. Crie a pasta da execução no caminho base confirmado (ex.: <base>/YYYY-MM-DD-<slug>/) e escreva 00-intake.md com modo, consulta ou lista de handles, nome do arquivo de perfil de marca usado, caminho base da execução, chaves disponíveis e quaisquer substituições.

Estágio 1: Descoberta

Modo palavra-chave. Invoque o skill virlo para descobrir vídeos curtos fora da curva para a palavra-chave de nicho. Execute a descoberta em todos os três anéis concorrentes definidos em video-decoder/references/decode-framework.md:

• Anel direto: a palavra-chave de nicho exata como está.
• Anel indireto: frases de palavra-chave adjacentes ao público (mesmo público, ângulo de tópico diferente).
• Anel adjacente: frases de palavra-chave adjacentes ao formato (mesmo formato ou estilo de produção, tópico diferente).

Invoque o skill virlo um anel de cada vez, passando o rótulo do anel e a frase de palavra-chave para aquele anel. Não invoque o virlo para vários anéis simultaneamente. O skill virlo gerencia toda a mecânica de órbita: primeiro verifica se existe um Cometa que cubra a palavra-chave do anel e reutiliza seus dados acumulados (gratuito) quando disponível, e só dispara uma Órbita nova (custo: $0,50) para anéis sem Cometa correspondente. A responsabilidade do orquestrador é o sequenciamento: aguardar o virlo retornar a lista ranqueada de outliers para um anel antes de invocar o virlo para o próximo anel.

Após o virlo retornar resultados para um anel, compute a magnitude de outlier por vídeo. Os resultados do virlo incluem uma taxa de outlier em nível de criador, mas o orquestrador precisa de uma taxa por vídeo para o Estágio 4 e a rubrica de classificação do Estágio 6. Para cada criador único que aparece nos resultados do anel, invoque o skill scrape para buscar os posts recentes desse criador (aproximadamente os últimos 20) na plataforma relevante. Use os posts retornados para calcular uma contagem mediana de visualizações de linha de base para aquele criador. Em seguida, calcule a taxa de outlier de cada vídeo como visualizacoes_do_video / mediana_de_visualizacoes_do_criador. Salve as respostas JSON brutas em raw/ para cada anel e para cada busca de linha de base.

Modo handles. Invoque o skill scrape para buscar os posts recentes (aproximadamente os últimos 20) para cada handle na plataforma relevante. Para cada handle, calcule a contagem mediana de visualizações entre os posts retornados. Mantenha apenas os posts que superem a própria mediana do criador em 2x ou mais (limiar de outlier). Salve o JSON bruto em raw/.

Se um handle produzir zero posts acima do limiar de 2x (criador de baixa variância), inclua mesmo assim o único post recente de melhor desempenho desse criador. Anote em 00-intake.md que o handle não tinha outlier claro e que o melhor post foi incluído como fallback.

Em ambos os modos, a saída do Estágio 1 é uma lista desduplicada de vídeos outliers com sua URL de origem, plataforma, handle do criador e contagem de visualizações.

Estágio 2: Comprovantes

Para cada vídeo outlier, invoque o skill scrape para coletar:

• Transcrição: para YouTube, invoque o skill scrape para buscar a transcrição pela URL do vídeo. Para TikTok e Instagram, tente extrair o texto da transcrição do payload de posts já obtido no Estágio 1. Se o payload de posts não contiver transcrição para um vídeo, invoque a função de transcrição do skill scrape para essa URL de vídeo como fallback antes de passar o vídeo para o Estágio 3.
• Frame de capa: a URL da miniatura retornada no payload de posts. Para YouTube, derive o frame de capa como https://img.youtube.com/vi/[VIDEO_ID]/hqdefault.jpg.

Salve todas as respostas brutas em raw/ nomeadas por origem e timestamp (ex.: scrapecreators-transcript-[video_id]-[timestamp].json). Toda contagem de visualizações e dado de engajamento usado downstream deve ter rastreabilidade até um arquivo em raw/.

Estágio 3: Decodificação

Execute o skill video-decoder em cada outlier. Passe: o texto da transcrição (se disponível), a URL do frame de capa (se disponível), o handle do criador, a plataforma, a magnitude de outlier (taxa computada no Estágio 1) e a atribuição do anel concorrente (classifique o anel de cada vídeo em relação à marca usando as definições de anel em video-decoder/references/decode-framework.md).

O skill video-decoder retorna um Registro de Decodificação preenchido por vídeo, incluindo o gancho visual (derivado do frame de capa e qualquer texto visível na tela), gancho escrito e gancho falado. Escreva cada registro em 01-decodes/[video_id].md. Neste ponto, todas as decodificações têm decode_depth: shallow.

Uma transcrição ausente por si só NÃO é motivo para pular um vídeo. Muitos dos vídeos com maior outlier são vídeos com sobreposição de texto ou estilo POV sem conteúdo falado. Se o vídeo tiver um frame de capa ou uma legenda, decodifique-o como raso com spoken_hook: n/a. Pule um vídeo apenas quando não houver genuinamente nada para decodificar: sem transcrição, sem frame de capa, sem legenda E nenhum outro sinal significativo (ex.: uma falha de busca com nada recuperável). Registre qualquer vídeo pulado como decode-failed em 00-intake.md com a URL do vídeo e a razão exata. Continue processando os vídeos restantes.

Estágio 4: Passagem profunda

Selecione os 5 a 8 melhores outliers classificados por magnitude de outlier (maior taxa primeiro).

Antes de chamar o helper Gemini para qualquer vídeo, resolva a URL de mídia CDN direta para aquele vídeo usando o skill scrape. Uma URL de página social (ex.: uma URL de página do TikTok ou Instagram) é rejeitada pelo Gemini. Passe a URL de mídia CDN para o helper, nunca a URL de página social. O método de resolução difere por plataforma: consulte scrape/references/reading-scrape.md em "Resolving a Direct Media URL for Video" para a abordagem por plataforma (TikTok requer uma consulta de video-info; URLs de mídia do Instagram estão no payload de posts já obtido; URLs de watch do YouTube passam diretamente). Resolva e use URLs CDN prontamente dentro da execução, pois URLs CDN expiram.

Para cada vídeo selecionado, chame o helper Gemini e redirecione o stdout diretamente para o arquivo bruto em um comando.

O caminho do helper deve ser resolvido como um caminho absoluto a partir do diretório que contém este SKILL.md (o diretório do skill shortform-idea-engine dentro do plugin instalado). Determine esse diretório em tempo de execução e construa o caminho absoluto para scripts/gemini-video-analyze.js dentro dele. O redirecionamento de saída visa a pasta da execução sob o caminho base confirmado no Estágio 0. Esses dois caminhos são resolvidos independentemente: o helper a partir do diretório do skill, a saída a partir do caminho base da execução.

OPENROUTER_API_KEY=<key> node <skill-dir>/scripts/gemini-video-analyze.js <cdnMediaUrl> "Analyze this short-form video for: pacing (average cut frequency, notable slow or fast segments), cut rhythm (pattern of cuts: cut-on-beat, reaction cuts, b-roll intercuts), visual style (color grading, background, camera movement, on-screen graphic density), text-on-screen cadence (how often captions or callouts appear relative to spoken content), and retention devices (specific hooks, pattern interrupts, cliffhangers, or loops used mid-video). Return structured notes for each dimension." > <run-base>/YYYY-MM-DD-<slug>/raw/gemini-<video_id>-<timestamp>.json

Onde <skill-dir> é o caminho absoluto para o diretório do skill shortform-idea-engine (o diretório que contém este SKILL.md) e <run-base>/YYYY-MM-DD-<slug>/ é a pasta da execução confirmada no Estágio 0.

O redirecionamento salva a resposta Gemini bruta em raw/gemini-<video_id>-<timestamp>.json dentro da pasta da execução para que a rastreabilidade do Estágio 8 possa ser satisfeita.

Reexecute o skill video-decoder para cada um desses vídeos, passando o bloco Gemini como entrada opcional de análise profunda. A reexecução retorna um Registro de Decodificação atualizado com decode_depth: deep e deep_notes preenchido. Substitua o 01-decodes/[video_id].md existente pelo registro profundo.

Pule o Estágio 4 inteiramente se OPENROUTER_API_KEY não estiver definida. Todas as decodificações permanecem shallow e a bandeira "shallow-decoded" é anotada por ideia no Estágio 6.

Estágio 5: Ideação

Agrupe todos os Vetores Virais (VV), Tópicos de Interesse (IT) e Formatos de cada Registro de Decodificação em 01-decodes/. Gere de 10 a 15 ideias remixadas. Cada ideia deve:

• Nomear qual Vetor Viral toma emprestado (rótulo exato do Registro de Decodificação).
• Nomear qual Tópico de Interesse toma emprestado ou adapta.
• Nomear qual Formato usa.
• Declarar o ângulo da marca: como o VV, IT e Formato emprestados são remixados para se adequar a esta marca específica (use os campos content_pillars, audience e proof_credibility do perfil de marca para ancorar o ângulo).
• Registrar a linhagem de origem para cada elemento emprestado: o creator_handle, source_url e video_id do(s) Registro(s) de Decodificação do qual o elemento foi extraído. Se um elemento aparecer em mais de um Registro de Decodificação, liste todos eles. Esta linhagem viaja com a ideia através da classificação e para o roteiro.

Os pesos de sinal de extração por anel se aplicam aqui (de video-decoder/references/decode-framework.md): VVs são válidos de todos os quatro anéis; ITs têm o maior sinal de concorrentes indiretos; Formatos têm o maior sinal de concorrentes adjacentes. Pese sua remixagem de acordo, mas não exclua ideias mecanicamente apenas com base no anel.

Se o pool de decodificação for muito pequeno para suportar 10 ideias distintas sem fabricar combinações de VV, IT ou Formato não presentes no pool, gere apenas quantas ideias genuínas o pool suportar. Anote a deficiência e a contagem real no topo de 02-ideas.md. Nunca invente elementos extraíveis que não foram decodificados.

Estágio 6: Classificação

Pontue cada ideia usando references/ranking-rubric.md:

1. Verifique cada ideia contra a lista anti_topics do perfil de marca. Qualquer correspondência é uma desqualificação imediata (DQ: anti-topic). Remova as ideias desqualificadas da tabela classificada. Adicione cada ideia desqualificada a uma seção claramente rotulada "Desqualificadas (anti-tópico)" no final de 02-ideas.md, abaixo da tabela classificada, listando a ideia e o anti-tópico específico que ela acionou.
2. Pontue as ideias sobreviventes em dois eixos: potencial_viral (média de cinco subfatores: força do VV, magnitude de outlier, repetibilidade do formato, frescor do tópico, força do gancho) e adequacao_a_marca (média de quatro subfatores: correspondência de voz, correspondência de público, correspondência de pilar de conteúdo, credibilidade autêntica). Ambas as pontuações usam uma escala de 1 a 10.
3. Compute combinado = potencial_viral * (adequacao_a_marca / 10). Arredonde para uma casa decimal.
4. Ordene decrescente por combinado. Quando duas ideias empatarem, aquela com maior potencial_viral classifica primeiro.
5. Escreva a tabela classificada em 02-ideas.md nesta ordem de colunas: # | ideia | raiz | VV/IT/Formato emprestado | vídeo de origem | viral | adequação à marca | combinado | justificativa de uma linha. A célula vídeo de origem mostra o vídeo de origem principal ao qual a ideia remonta como @creator_handle / video_id. Se a ideia pegar emprestado de vários vídeos, liste o de maior magnitude primeiro e em itálico, depois os outros separados por vírgula.

Estágio 7: Roteiro

Para cada uma das 2 a 3 melhores ideias classificadas, invoque o skill script-writer, passando:

• O perfil de marca (para voz e limitações).
• O VV, IT e Formato exatos da ideia.
• A linhagem de origem (para que o roteiro possa referenciar o vídeo de origem se útil).
• Quaisquer notas de decodificação profunda do Gemini (se disponíveis) como sugestões de estilo.

Cada invocação retorna um roteiro completo. Escreva cada um em 03-scripts/ nomeado pelo slug da ideia (ex.: 03-scripts/ai-hook-reveal.md). O roteiro deve estar pronto para produção: incluir marcadores de tempo ou contagem de cenas, orientação de talento em cena, instruções de b-roll e texto na tela.

Estágio 8: Verificação e resumo

Leia todos os arquivos em 01-decodes/, 02-ideas.md e 03-scripts/. Escreva README.md no nível da pasta da execução que vincule a cada saída com uma breve descrição do que ela contém. Inclua uma tabela de resumo no topo:

Estágio	Arquivo de saída	Conteúdo
0 (Entrada)	00-intake.md	Modo, consulta, perfil de marca, chaves disponíveis
1 (Descoberta)	(bruto em raw/)	Lista de vídeos outliers com URLs
2 (Comprovantes)	(bruto em raw/)	Transcrições e frames de capa
3 (Decodificação)	01-decodes/*.md	Registros de Decodificação rasos por vídeo
4 (Passagem profunda)	(bruto em raw/) e 01-decodes/*.md atualizados	Decodificações profundas para os 5-8 melhores
5 (Ideação)	02-ideas.md	10-15 ideias remixadas com linhagem
6 (Classificação)	02-ideas.md (atualizado)	Tabela classificada e desqualificações
7 (Roteiro)	03-scripts/*.md	Roteiros prontos para produção

Verifique que cada arquivo de saída existe e não está vazio. Se um arquivo esperado estiver faltando (ex.: porque um estágio foi pulado devido a chave de API ausente), anote isso na tabela. A tabela de resumo é o artefato de entrega final.

Referências

• references/brand-profile-template.md — esquema do perfil de marca
• references/ranking-rubric.md — definições de pontuação de viral e adequação à marca
• video-decoder/references/decode-framework.md — definições de anel, extração de VV/IT/Formato
• scrape/references/reading-scrape.md — resolução de URL de mídia CDN direta por plataforma
• scripts/gemini-video-analyze.js — script de análise visual profunda

Nota: os caminhos das referências são relativos ao diretório das skills video-decoder e scrape, que estão no mesmo plugin que este skill.

Limitações conhecidas

• Vídeos do TikTok sem transcrição: muitos vídeos virais não têm fala e são decodificados como rasos. A bandeira shallow é aplicada corretamente.
• Criadores de baixa variância (todas as visualizações próximas do mesmo valor): o melhor post ainda é incluído, mas as taxas de outlier podem ser subestimadas.
• Chave API OpenRouter ausente: nenhuma análise profunda Gemini. As classificações usam apenas decodificações rasas.
• URLs CDN expiram: devem ser resolvidas e usadas no mesmo ciclo de execução.
• O modo palavra-chave depende do skill virlo ter cobertura para a palavra-chave. Palavras-chave muito específicas ou de nicho podem não ter dados de Cometa.