media-use: Antes de obter áudio/imagens, chame
/media-usepara resolver BGM/SFX/imagens do catálogo HeyGen. Execute--adoptprimeiro para registrar assets existentes. Veja a skill/media-use.
PR para HyperFrames
Use esta skill para ingerir um pull request do GitHub, entender a mudança, planejar um explicador de mudança de código e construí-lo quadro a quadro no HyperFrames. A entrada é uma mudança de código (lida via gh), não um site — não há etapa de captura e nenhum asset real além dos avatares dos contribuidores.
Confirme a rota antes do Passo 0. Você é o orquestrador. Execute cada passo, verifique sua porta e só então continue. Esta skill é para um pull request do GitHub (uma mudança de código). Roteie outras intenções para outro lugar: lançamento/promoção de produto →
/product-launch-video; tour geral de site →/website-to-video; explicador de tópico sem PR →/faceless-explainer; legendas em filmagem existente →/embedded-captions; motion graphic curto sem narração →/motion-graphics; walkthrough de release de repositório inteiro ou multi-PR →/general-video. Fora do escopo: dados ao vivo / em tempo de renderização — fatos do PR são lidos uma vez no momento da criação e incorporados. Se o usuário disser apenas "faça um vídeo" ou a rota for incerta, leia/hyperframesprimeiro.
Você é o orquestrador. Trabalhe em videos/<projeto>/. Execute os passos em ordem e passe cada porta antes de continuar. Passos com porta do usuário são Passo 0, Passo 3 e Passo 6. Faça cada passo você mesmo, exceto o Passo 5, onde você despacha um sub-agente por quadro. Não coloque regras de design ou movimento aqui; elas vivem no sub-agente de trabalhador de quadro, hyperframes-creative e hyperframes-animation.
Fluxo de trabalho: Passo 0 setup → hyperframes.json; Passo 1 ingestão → capture/extracted/ + assets/<login>.png; Passo 2 sistema de design → frame.md; Passo 3 storyboard/roteiro → STORYBOARD.md e SCRIPT.md; Passo 3.1 áudio → audio_meta.json; Passo 4 design visual → STORYBOARD.md enriquecido; Passo 5 quadros → compositions/frames/NN-*.html e index.html; Passo 6 renderização final → renders/video.mp4.
Passo 0: Setup e Brief
Objetivo: Fixar a referência do PR e o brief central do vídeo, e criar o projeto HyperFrames se necessário.
Obtenha a referência do PR (uma URL completa, uma referência <owner>/<repo>#<N> ou "este PR" em um repositório clonado) e, em uma mensagem, confirme o brief — lidere com um padrão recomendado para cada um e pré-preencha qualquer coisa que /hyperframes já definiu: ângulo (changelog / feature-reveal / fix-explainer / refactor-walkthrough — padrão: inferir do PR), público (padrão: desenvolvedores), duração (padrão: escala para o tamanho da mudança do PR — veja abaixo), aspecto (padrão 16:9), idioma. O estilo é sempre claude. Proceda apenas após o usuário responder; um "vai" aceita os padrões.
Recomende a duração com base no tamanho da mudança do PR, não um palpite fixo. Antes de confirmar o brief, dê uma olhada no PR uma vez — uma chamada somente leitura que também fundamenta o ângulo (o Passo 1 ainda faz a busca determinística completa):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
Escolha o nível de additions + deletions (ajustado por changedFiles) e lidere com ele como padrão (o usuário pode substituir; limite máximo ~3 min):
| Tamanho da mudança do PR | Duração recomendada |
|---|---|
| trivial (≲ 50 linhas alteradas) | ~20–40s |
| focado (~50–200 linhas) | ~40–70s |
| substancial (~200–600 linhas) | ~70–110s |
| grande (≳ 600 linhas, ou 25+ arquivos) | ~110–180s |
Indique a base em uma frase ao propor (ex.: "~40s — mudança pequena, +44/−13 em 12 arquivos"). Um PR enorme não significa um vídeo longo — se a história é uma mudança principal, mantenha-a concisa e diga isso.
Inicialize apenas se hyperframes.json estiver faltando. Nomeie <projeto> a partir do PR em kebab-case, como acme-sdk-pr-1842; nunca use o nome do workspace ou um timestamp.
npx hyperframes init "videos/<projeto>" --non-interactive --example=blank — init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
Mostre o status de login antes do brief — execute npx hyperframes auth status e relate sua saída literalmente (não parafraseie ou reescreva). Ele informa se voz/BGM usará motores HeyGen ou locais e, quando não estiver logado, como fazer login. Se não estiver logado, PARE e aguarde o usuário escolher — fazer login, ou dizer "vai"/"offline" para continuar com motores locais — antes de perguntar o brief ou qualquer outra coisa. Trate como um ponto de decisão real, não uma nota passageira; não incorpore a escolha na pergunta do brief, e não escreva chaves em um .env por repositório. (Em modo autônomo, note o status e continue offline.) Veja ../hyperframes-media → Preflight para a orientação canônica.
Porta: hyperframes.json existe; a referência do PR está capturada; ângulo, duração, proporção e idioma estão fixos; o status de login foi mostrado (logado, ou continuando offline).
Passo 1: Ingerir o PR (sem captura)
Objetivo: Buscar os fatos do PR e incorporá-los ao projeto como fonte de informação. Não há captura de site. fetch-pr.mjs executa gh deterministicamente — completando a lista de arquivos via gh api paginada para que um PR grande não seja truncado em ~100 arquivos, e escrevendo apenas capture/pr.json + capture/diff.patch (sem diretório temporário). Em seguida, ingest.mjs incorpora isso no pacote de captura sintético offline.
PR="<url | owner/repo#N | N>"
# Busca o PR deterministicamente: executa gh, completa a lista de arquivos via
# gh api paginada (para que um PR grande não seja truncado em ~100 arquivos),
# escreve apenas capture/pr.json + capture/diff.patch — sem diretório temporário.
# Erros de gh auth / não encontrado / privado saem com código 1 aqui.
(cd "videos/<projeto>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformação offline → capture/extracted/{tokens.json (colors:[] → paleta claude),
# visible-text.txt (o brief), people.json (contribuidores, filtrados por bot,
# avatarFile=assets/<login>.png)}.
(cd "videos/<projeto>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# A única etapa de rede do front de pessoas — baixa o avatar do GitHub de cada
# contribuidor para assets/<login>.png para um fechamento opcional de créditos.
# Melhor esforço; sempre sai com código 0.
(cd "videos/<projeto>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Se fetch-pr.mjs sair com código 1 (gh auth / não encontrado / privado), relate seu stderr e pare — não fabrique conteúdos do PR. Se ingest.mjs sair com código 1, leia seu stderr (geralmente um pr.json malformado), corrija e execute novamente (determinístico). fetch-people-avatars.mjs sempre sai com código 0; avatares faltantes apenas significam sem fechamento de créditos para o autor.
Porta: capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt e capture/extracted/people.json existem; você pode declarar a mudança do PR em uma frase clara. assets/<login>.png é melhor esforço — sua ausência não é uma falha.
Passo 2: Sistema de Design
Objetivo: Adotar o preset de quadro claude; um script o transforma no frame.md deste vídeo + skin de legenda.
O estilo é fixo — claude (editorial caloroso; uma superfície de código azul-marinho construída para diffs). Execute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
O script copia o FRAME.md do preset claude → frame.md, o remixa em quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a paleta própria do claude, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e se autovalida (sai com código 1 em um mapeamento quebrado). Prosseguir assim que sair com código 0 — sem edição manual.
Porta: build-frame.mjs saiu com código 0 — frame.md existe a partir do preset claude, e .hyperframes/caption-skin.html existe como fonte da skin de legenda.
Passo 3: Storyboard e Roteiro
Objetivo: Transformar o PR em um plano de explicação quadro a quadro aprovado.
Leia references/story-design.md, ../hyperframes-core/references/storyboard-format.md e ../hyperframes-core/references/script-format.md. Use-os para escrever STORYBOARD.md e, quando narração for necessária, SCRIPT.md.
Use story-design.md para o arquétipo do PR (changelog / feature-reveal / fix-explainer / refactor-walkthrough), os tipos de quadro nativos do PR, gancho, persuasão, batidas, o orçamento de palavras por quadro e o fechamento opcional de créditos. A sequência vem do design narrativo, não da ordem de arquivos do diff — explique a mudança, não leia o diff em voz alta. Apresente 2–4 trechos reais de diff (de capture/diff.patch), cada um um snippet pequeno legível; nomeie o bloco code-* que cada um quer na scene do quadro. Quadros não carregam asset_candidates exceto um fechamento opcional de credits (2–6 avatares assets/<login>.png). Use os campos exatos exigidos das referências de storyboard e roteiro.
Após rascunhar, mostre um resumo quadro a quadro. Nessa mesma mensagem, pergunte ao usuário (a) aprovar ou solicitar alterações e (b) se deseja uma prévia ao vivo do scaffold do storyboard (npx hyperframes preview) — abra apenas com um sim. Itere até a aprovação; leve a escolha de prévia para o Passo 6.
Porta: STORYBOARD.md existe, todo quadro tem os campos narrativos exigidos, SCRIPT.md existe quando narração é necessária e o usuário aprovou o plano.
Passo 3.1: Áudio
Objetivo: Gerar narração, temporizações de palavras, música e metadados de áudio a partir do roteiro aprovado.
Inicie o áudio após a aprovação do Passo 3. Execute em segundo plano e depois continue para o Passo 4.
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
O script de áudio lida com narração, temporizações de palavras, busca de BGM na biblioteca de música do HeyGen e metadados de temporização. O humor do BGM vem do campo music: do storyboard. Isso usa a API de Áudio do HeyGen para recuperação, não geração, e a mesma credencial ~/.heygen do TTS. Para detalhes do provedor, leia ../hyperframes-media/references/tts.md.
Se não houver narração e nenhum SCRIPT.md, pule a geração de voz. O BGM ainda pode ser executado se o storyboard tiver um humor de música.
Porta: trabalho de áudio iniciou, ou o projeto está marcado como silencioso.
Passo 4: Design Visual do Quadro
Objetivo: Adicionar direção visual, intenção de layout e escolhas de movimento a cada quadro do storyboard.
Edite STORYBOARD.md no lugar. Não crie outro storyboard. Use frame.md como fonte da verdade para cor, tipo, sensação de layout e estilo.
Leia references/visual-design.md, references/composition.md, references/motion-language.md, references/code-vocabulary.md e ../hyperframes-animation/. Use visual-design.md para campos de quadro exigidos e o bloco ## Video direction exigido, e para como uma batida de código nomeia um bloco code-* como seu focal. Use code-vocabulary.md para escolher o bloco certo por batida (diff = code-diff, refactor = code-morph, código novo = code-typing, …). Use composition.md para layout/hierarquia/pontos focais e motion-language.md + ../hyperframes-animation/ para IDs válidos de efeito e blueprint. Não invente nomes de efeitos ou IDs de bloco/blueprint.
Para cada quadro, adicione campos visuais e de movimento exigidos, incluindo effects e focal e/ou roles. Para uma batida de código, nomeie o bloco code-* como o focal e deixe effects coreografar a Superfície de Código Claude ao redor (não a animação de código, que o bloco possui). Adicione um bloco ## Video direction para todo o vídeo.
Não mude história, roteiro, transition_in, asset_candidates ou a fonte do PR. Não escreva HTML neste passo. Não há etapa de preparação de assets — os únicos assets reais são os avatares de créditos, já em assets/.
Porta: todo quadro tem effects mais focal e/ou roles; quadros de código nomeiam um bloco code-*; ## Video direction existe.
Passo 5: Construir Quadros
Objetivo: Construir cada quadro do storyboard como uma composição HTML e montar o vídeo reproduzível.
Aguarde o áudio do Passo 3.1 terminar se o áudio foi iniciado. Em seguida, sincronize durações e busque SFX; pule ambos se silencioso.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
A sincronização de duração é mecânica: duração real da voz vence; quadros silenciosos mantêm estimativas; nunca edite manualmente durações sincronizadas.
Pré-instale os blocos de registro nomeados em STORYBOARD.md uma vez, antes do despacho, para que trabalhadores paralelos não concorram no registro:
for b in <cada bloco de registro nomeado no storyboard>; do npx hyperframes add "$b"; done
Antes do despacho, leia sub-agents/frame-worker.md e ../hyperframes-core/references/subagent-dispatch.md. Despache um sub-agente por quadro, em paralelo se possível; caso contrário, execute trabalhadores em ondas. Cada trabalhador recebe exatamente um quadro. O contexto de cada trabalhador deve incluir PROJECT_DIR, frame_id, tamanho da tela, status de legenda e faixa de exclusão se legendas estiverem ativadas, ANIM_DIR (caminho absoluto para ../hyperframes-animation/) e o caminho absoluto para references/code-vocabulary.md. Cada trabalhador lê frame.md, seu próprio bloco ## Frame N, o corpo da receita para cada ID de efeito/blueprint citado e — para uma batida de código — code-vocabulary.md para as entradas do bloco nomeado. Cada trabalhador escreve apenas compositions/frames/NN-*.html; trabalhadores nunca editam STORYBOARD.md.
À medida que cada trabalhador retorna, marque esse quadro como animated em STORYBOARD.md.
Após as temporizações de áudio existirem, construa legendas em segundo plano e monte o índice:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs usa o .hyperframes/caption-skin.html do projeto (o do claude, copiado no Passo 2), injetando tokens de marca de frame.md; captions: skipped (<motivo>) se as legendas forem puladas.
Porta: todas as saídas dos trabalhadores de quadro (compositions/frames/NN-*.html) existem; compositions/index.html existe; caption_groups.json (ou confirmação de skipped) existe; cada quadro marcado animated em STORYBOARD.md.
Passo 6: Renderizar e Revisar
Objetivo: Renderizar o vídeo final, mostrá-lo e, se aprovado, commitá-lo.
Se uma prévia não foi aberta no Passo 3, abra-a agora com:
npx hyperframes preview
. Peça revisão ao usuário.
Se o áudio ainda estiver rodando, aguarde. Em seguida, renderize:
npx hyperframes render
Estruture a saída como renders/video.mp4.
Depois que aparecer, compartilhe o caminho do arquivo e pergunte se o usuário gostaria de commitá-lo. Se sim:
git add renders/video.mp4 && git commit -m "adiciona vídeo explicativo do PR"
Porta: renders/video.mp4 existe; o usuário revisou ou aprovou; commitado opcionalmente.
Notas Gerais
- Todo caminho de arquivo é relativo à raiz do projeto (diretório de trabalho), a menos que absoluto seja explicitamente declarado.
- Mantenha a pasta
videos/<projeto>/limpa — remova quaisquer diretórios temporários não listados acima. - O fluxo de sub-agente do Passo 5 é o único ponto de paralelismo; todos os outros passos são sequenciais.
- Se um script falhar, leia seu stderr, corrija a entrada e reexecute; nunca pule uma falha.
- A skill depende de
ghautenticado, Node.js enpx hyperframes. Verifique pré-requisitos no Passo 0.