Communitygithub.com

brief-e-história

Início de qualquer trabalho de vídeo. Transforme um pedido ("faça um promo para meu site", "um vídeo de produto", "um filme de apresentação como este") em um briefing, uma referência estudada, uma estrutura de história, um roteiro e um plano de filmagem. Use antes de buscar material ou construir qualquer coisa, e novamente quando o feedback alterar a história.

O que é brief-e-história?

O skill `brief-e-história` é a primeira etapa no fluxo de produção de vídeo para agentes de IA como Claude Code, Cursor e Codex. Ele orienta o agente a transformar um pedido genérico em um conjunto completo de especificações: briefing, análise de referência, escolha de estrutura narrativa, roteiro e plano de filmagem. Primeiro, o agente extrai informações essenciais sobre o público-alvo, objetivo, duração e produto, usando perguntas estruturadas. Em seguida, se uma referência for fornecida, o skill instrui o agente a analisar cortes e palavras por meio de comandos como `npx hyperframes measure cuts` e `npx hyperframes transcribe`. Ele oferece cinco estruturas de história (filme narrativo, promo de site, demonstração de produto, corte social) com adaptações para diferentes tipos de produto (aplicativo de consumo, SaaS, site, loja, serviço). Finalmente, o skill define a criação de personagens (com nomes, idades, cargos, desejos), regras de roteiro (linhas curtas, IDs, chamadas) e verificação do plano de filmagem. Funciona em plataformas que suportam execução de comandos shell e leitura de arquivos, garantindo que o vídeo resultante seja coerente, focado e acionável.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shubhamnshukla/video-agent-kit/tree/main/skills/video-brief-and-story

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Brief e história

1. O briefing: o que você precisa saber

Descubra estas informações antes de qualquer outra coisa. Leia primeiro o que foi fornecido (o site, o aplicativo, um deck, um filme de referência); pergunte apenas pelo que ainda está faltando, em uma única mensagem.

PerguntaPor que isso muda o filme
Quem assiste, e onde?Investidores em uma sala, visitantes em uma landing page e uma rede social sem áudio precisam de aberturas, durações e tamanhos de texto diferentes
O que eles devem fazer depois?Torna-se o último quadro: um endereço, um QR code, um botão
Quanto tempo?Define a contagem de palavras: cerca de 2,5 palavras faladas por segundo, menos para um filme com pausas
Qual é o produto, realmente?Você precisa usá-lo, ou vê-lo sendo usado, para mostrá-lo com verdade
Existe um filme de que eles gostem?Uma referência define ritmo e visual mais rápido do que qualquer descrição
O que deve estar incluído, o que não deve?Recursos ainda não lançados, concorrentes, alegações que o departamento jurídico não aprovou

Padrões quando não especificarem: 16:9 em 1920 × 1080 de autoria, 30 fps, 60 a 100 segundos, um narrador, as fontes e cores da própria marca, fundo claro se o produto for claro.

2. Estude a referência

Se fornecerem um filme de referência, analise-o antes de escrever.

  • Cortes: npx hyperframes measure cuts ref.mp4 ou detecção de cena com ffmpeg. Faça uma folha de contato com um quadro por cena (scripts/sheet.sh).
  • Palavras: npx hyperframes transcribe ref.wav --json.
  • Escreva uma ficha de cenas: tempo, duração, o que está na tela, o que é dito. Depois, as proporções: quantos segundos de problema, produto, final. Observe a duração dos planos, onde o texto aparece, quando a música muda.

O que se tira de uma referência é sua estrutura e ritmo, nunca seu material de arquivo, música, texto ou personagens.

3. Estruturas de história

Escolha uma e diga qual. Funcionam para qualquer produto; o que muda é quem são as pessoas e como são as telas do produto (seção 4 e video-footage-and-screens).

Filme narrativo (pitch, lançamento, marca). Gancho → conheça as pessoas → o problema atinge todas elas → a preocupação de cada uma → o que tentaram → uma linha que resume tudo → o produto responde → as pessoas novamente, em melhor situação → quadro final. O problema ocupa de 45 a 55 por cento da duração. Esta é a estrutura a usar quando o público precisa primeiro se importar.

Promo de site (30 a 60 s). Gancho declarando o resultado → o produto fazendo sua única coisa principal, em grande → três comprovações (um recurso cada, na tela por dois a quatro segundos) → um momento humano → quadro final. O valor é declarado no segundo comprovação; tudo depois disso é evidência.

Demonstração de produto (60 a 120 s). Uma pessoa com uma tarefa, do início ao fim no produto real. Cada etapa é uma tela mais a única parte dela que importa, ampliada. Diga o que a pessoa ganha em cada etapa, não como o botão se chama.

Corte social (10 a 30 s). Uma ideia. O texto a carrega sem som. O primeiro quadro já diz algo.

Adaptando ao produto.

ProdutoQuem são as pessoasO que significa "o produto, em grande"
Aplicativo de consumopessoas em suas próprias vidas, em casa, em movimentoo telefone, com um pedaço de uma tela ampliado ao lado
Ferramenta SaaS ou B2Bpessoas em funções: um líder de operações, um fundador, um agente de suporte, cada um com um prazouma janela do navegador, com o único painel ou número que importa ampliado
Site ou marketplaceum visitante com uma necessidadeo próprio site: o hero, uma pesquisa, um resultado, um checkout, conforme a rolagem captura
Loja online ou produto físicoo comprador e o momento do usoas próprias fotos e filmagens do produto da empresa, mais a página onde você o compra
Serviçoo cliente antes e depoiso fluxo de reserva ou inscrição, e o resultado que o serviço entrega

4. Pessoas

Quando o filme tiver pessoas, torne-as específicas. Para cada uma: um nome, uma idade, um cargo, uma cidade e a única coisa que desejam do tipo de problema que este produto resolve. Dê a diferentes pessoas desejos diferentes: um público de estranhos se identifica com pelo menos um deles. Em um filme para um aplicativo de finanças pessoais, isso foi uma bicicleta, uma casa, um casamento e uma viagem; para uma ferramenta de contratação, podem ser quatro gerentes com quatro papéis diferentes a preencher. Mostre o desejo como uma imagem, e mostre todo desejo da mesma maneira.

Os nomes devem combinar com o material de arquivo que você realmente pode obter, então, elenco e nomeie juntos (veja video-footage-and-screens). Mantenha os números de uma pessoa iguais aos da conta mostrada no produto, para que história e telas concordem.

Essas pessoas são exemplos inventados interpretados por modelos de material de arquivo. Diga isso em SCRIPT.md e nunca as apresente como clientes.

5. Escrevendo o roteiro

Escreva falas para serem ditas em voz alta, em frases curtas. Os exemplos abaixo são de um filme para um aplicativo de finanças pessoais; escreva o equivalente para o produto à sua frente. O que funciona:

  • Um gancho que é um contraste ou uma pequena piada com verdade: "Dia de pagamento. O melhor dia do mês. Por cerca de quatro horas."
  • Uma referência cruzada: estabeleça "quatro horas", retome com "Nove da manhã... Na hora do almoço, já está comprometido."
  • Fragmentos para introduções: "Kabir. Designer. Ele quer uma bicicleta há três anos."
  • A própria pergunta da pessoa em suas próprias palavras, uma cada: "Posso comprar a bicicleta e ainda dormir tranquilo?"
  • Uma linha que nomeia o problema tão bem que poderia ser o título do filme: "Eles não são ruins com dinheiro. Eles estão sozinhos com ele."
  • Uma linha que entrega para o produto: "Todo mundo tem conselhos. Ninguém tem os números reais." e então "Dê a ele seus números reais."

Regras:

  • Uma ideia por linha. Linhas de dois a cinco segundos. Um ID para cada linha (n-01, p-01, e-01): o ID nomeia o arquivo de áudio e o clipe.
  • Escreva números e datas como são falados: "vinte e vinte e oito", "mil novecentos e noventa e nove por mês".
  • Use a moeda, unidades e nomes de lugares do público, e as palavras que eles usam para o problema.
  • Retire as alegações do produto das próprias palavras do produto. Mantenha uma tabela em SCRIPT.md: linha, de onde vem.
  • Deixe palavras de fora onde a imagem diz. Um crachá na tela não precisa de "conheça Kabir".
  • Após a primeira passagem completa, corte um décimo. Sempre está longo demais.

Palavras que a própria empresa evita, evite também. Se o texto da empresa nunca diz "empréstimo", o narrador também não diz.

6. O plano de filmagem

Para cada linha, decida o que está na tela e o que muda em qual palavra. Escreva como a tabela em SCRIPT.md (tempo, imagem, voz) e, uma vez que os tempos existam, como a lista de planos numerada por quadro em SPEC.md.

Verifique o plano em relação a estes pontos antes de construir:

  • O quadro 0 já mostra uma pessoa ou um título? É a miniatura.
  • Cada linha importante também está na tela como texto? Salas são barulhentas e feeds estão sem áudio.
  • Algo dura mais de três segundos sem que nada mude?
  • Cada tipo de coisa (crachás, desejos, planos, conselhos) é feito de uma maneira consistente ao longo de todo o filme?
  • O final retoma o que o início estabeleceu?
  • O último quadro diz para onde ir, e dura pelo menos seis segundos se tiver um QR code?

templates/SCRIPT.md tem este formulário pronto para preencher.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Habilidades Relacionadas