jackyuyz/repo-demo-video-skill

Repo Demo Video

Use este skill para transformar um repositório em um plano de demonstração de produto polido e, quando informações de tempo de execução suficientes estiverem disponíveis, em um vídeo de demonstração gravado no navegador.

Princípio Central

Prefira evidências do repositório em vez de configurações perfeitas do usuário:

1. Use demo.config.json ou demo.config.yaml quando presente.
2. Use DEMO_GUIDE.md quando presente.
3. Use README.md.
4. Use package.json, arquivos de framework, pastas de rotas, nomes de componentes, títulos de página e estrutura do código-fonte.
5. Explore um aplicativo implantado ou local no navegador quando uma URL segura existir.
6. Gere suposições alternativas com pontuações de confiança.

Trate README.md mais código-fonte como a fonte primária, DEMO_GUIDE.md como o guia amigável recomendado e demo.config.* como uma substituição opcional amigável para máquinas.

Fluxo de Trabalho

1. Resolva o caminho ou URL do repositório alvo. Para a CLI MVP, use um caminho de repositório local; se for fornecida uma URL do GitHub, peça ao usuário para fornecer um clone local, a menos que um fluxo de clonagem futuro esteja explicitamente disponível.

2. Execute o analisador:

   npm run demo -- --repo ./caminho-para-o-repositorio
   

   Entradas opcionais:

   npm run demo -- --repo ./caminho-para-o-repositorio --config ./demo.config.json
   npm run demo -- --repo ./caminho-para-o-repositorio --url https://exemplo.com
   npm run demo -- --repo ./caminho-para-o-repositorio --mode draft
   npm run demo -- --repo ./caminho-para-o-repositorio --mode full
   

3. Revise os artefatos gerados em uma pasta de saída com timestamp, como demoOutput-2026-05-10-143012/:

   • project_summary.md
   • demo_plan.draft.json
   • demo_plan.json quando a confiança for alta o suficiente
   • narration_script.draft.md
   • narration_script.md
   • script_quality_report.json
   • timing_plan.json
   • demo_storyboard.md
   • manual_recording_guide.md
   • recordings/ quando a captura do navegador for bem-sucedida
   • screenshots/ quando a exploração do navegador for bem-sucedida
   • voiceover.mp3 quando TTS_PROVIDER=openai e OPENAI_API_KEY estiverem disponíveis
   • demo_video.html como fallback de visualização local quando a composição MP4 estiver incompleta
   • demo_video.mp4 apenas quando gravação, áudio real e ffmpeg estiverem disponíveis

Regras de Confiança

• Marque alegações explícitas de documentação e configuração como alta.
• Trate listas de recursos do README como evidência suficiente para gerar um plano final quando o nome do projeto, resumo e pelo menos um recurso estiverem claros.
• Marque nomes de rotas, nomes de componentes, metadados de pacote e estrutura de código clara como média.
• Marque alegações especulativas de produto e ações adivinhadas como baixa.
• Se alegações importantes forem de baixa confiança, gere demo_plan.draft.json, explique o que está faltando e evite apresentar o plano de vídeo final como certo.

Análise do README

• Ignore badges, imagens de escudo, linhas de imagens decorativas, URLs brutas e metadados de licença/status ao extrair resumos de produto.
• Prefira a apresentação do DEMO_GUIDE.md, o resumo do blockquote do README, as seções de visão geral/sobre/descrição do README e, em seguida, a descrição do pacote.
• Reconheça cabeçalhos decorados como ## Features com emoji ou símbolos normalizando os cabeçalhos antes da correspondência.
• Extraia listas com marcadores sob cabeçalhos de funcionalidade/capacidade/destaque como recursos de alta confiança.
• Extraia fluxos de trabalho numerados sob cabeçalhos de uso/como-usar/demo/início-rápido como dicas de fluxo de demonstração de confiança média.
• Sanitize as entradas de narração antes de escrever roteiros; não carregue badges do Markdown, sintaxe de imagem ou URLs brutas para o texto da narração.

Segurança

• Mantenha a análise do repositório somente leitura.
• Escreva artefatos gerados apenas em uma nova pasta demoOutput-YYYY-MM-DD-HHMMSS/ com timestamp no repositório alvo.
• Não exclua arquivos recursivamente nem execute comandos destrutivos.
• Não execute comandos de implantação.
• Chamadas externas de LLM/TTS são permitidas quando o usuário solicita saída narrada ou configura variáveis de ambiente do provedor. Envie apenas resumos de projeto sanitizados, planos de demonstração, observações do navegador e texto do roteiro de narração.
• Não envie arquivos .env brutos, chaves de API, tokens privados, dados de usuário privados, credenciais reais ou arquivos de código-fonte desnecessários para provedores externos de LLM/TTS.
• Não exponha segredos, chaves de API, tokens privados, valores .env, dados de usuário privados ou credenciais reais em narração, capturas de tela, vídeo, logs ou artefatos gerados.
• Se uma conta de teste estiver documentada, mencione apenas que uma conta de demonstração é usada, a menos que o usuário peça explicitamente o contrário.

Comportamento do Navegador e Vídeo

• Prefira um demoUrl implantado do config, DEMO_GUIDE.md, README ou do argumento --url.
• Use Playwright quando disponível para inspecionar cabeçalhos visíveis, botões, links, formulários e capturar capturas de tela ou gravações.
• Use heurísticas conservadoras de DOM para preencher amostras de entrada seguras, escolher opções de seleção não vazias e clicar em controles de demonstração comuns como Adicionar, Calcular, Método, Recursos, Novo ou Criar.
• Mantenha cada cena planejada na tela por tempo suficiente para o ritmo da narração e pause brevemente após ações heurísticas para que a gravação não seja apenas cliques rápidos.
• Registre o caminho de gravação .webm canônico em run_report.json.
• Não force a inicialização do projeto local quando as instruções de execução forem incertas.
• Se Playwright, TTS, ffmpeg ou o tempo de execução do aplicativo não estiverem disponíveis, ainda produza os artefatos escritos, entregas parciais, demo_video.html e um guia de gravação manual.
• Componha o MP4 final com base na duração da narração. Não use truncamento de fluxo mais curto. Se a gravação do navegador for mais curta que a narração, estenda o quadro final do vídeo com ffmpeg tpad e relate a duração da extensão.

Escrita Profissional de Roteiro

• Use o rascunho determinístico como fallback, mas prefira o escritor de roteiro OpenAI quando SCRIPT_PROVIDER=openai e OPENAI_API_KEY estiverem definidos.
• Gere timing_plan.json antes de escrever o roteiro final. Baseie-o nos recursos disponíveis, cenas do navegador, duração do vídeo configurada e avisos de ritmo.
• Use a mesma OPENAI_API_KEY para escrita de roteiro e TTS da OpenAI.
• Controle o prompt de escrita de demonstração de produto em src/prompts/demoNarrationPrompt.ts.
• Controle o modelo da API Responses da OpenAI com OPENAI_SCRIPT_MODEL; se não definido, use OPENAI_MODEL e depois gpt-5.4-mini.
• Escreva narration_script.draft.md para o rascunho do modelo e narration_script.md para o roteiro final do LLM ou fallback.
• Escreva script_quality_report.json com provedor, modelo, motivo do fallback e avisos de portão de qualidade.
• O prompt deve fazer o escritor de roteiro primeiro entender o produto, evitar badges e metadados brutos do README, focar no público/problema/valor, usar linguagem conservadora para alegações incertas e respeitar a contagem de cenas e orçamento de palavras do plano de tempo.

Orientação Visual da Demonstração

Para gravações polidas do navegador, injete sobreposições temporárias de orientação visual não persistentes através do Playwright em vez de editar o código-fonte do aplicativo.

Use:

• Uma legenda sutil de callout para a batida atual da narração.
• Um anel de destaque ao redor do elemento de UI ativo ou área de resultado.
• Alto z-index, pointer-events: none e posicionamento fixo.
• Estilo neutro que não obscurece a UI do produto.

Não use sobreposições para fabricar funcionalidade. Use-as apenas para guiar a atenção do espectador para mudanças reais no estado da UI. As sobreposições devem existir apenas na sessão de gravação do navegador e desaparecer quando a sessão for fechada.

Narração

• Padrão: usar TTS da OpenAI no modo completo quando OPENAI_API_KEY estiver definido.
• Para gerar áudio real explicitamente, defina TTS_PROVIDER=openai e OPENAI_API_KEY.
• Se TTS_PROVIDER não estiver definido, mas OPENAI_API_KEY existir, use TTS da OpenAI.
• Para forçar o modo mock local, defina TTS_PROVIDER=mock.
• OPENAI_API_KEY pode ser a mesma chave usada pelo escritor profissional de roteiro.
• Variáveis opcionais: OPENAI_TTS_MODEL, OPENAI_TTS_VOICE, OPENAI_TTS_INSTRUCTIONS, TTS_VOICE.
• Escreva o áudio real na pasta da execução atual, por exemplo demoOutput-2026-05-10-143012/voiceover.mp3.
• Enviar o texto sanitizado voiceover_script.txt para o provedor de TTS configurado é necessário para criar o áudio da narração.
• Nunca escreva chaves de API em arquivos gerados.
• Divulgue que a narração gerada é gerada por IA ao publicar a demonstração.

Estendendo o Skill

Mantenha a arquitetura modular. Adicione suporte futuro para clonagem de URL do GitHub, interação mais profunda com a UI, provedores reais de TTS, legendas, estilos de vídeo, inicialização local e revisão humana estendendo o módulo src/*.ts correspondente em vez de transformar a CLI em um script grande.