media-use: Antes de buscar áudio/imagens, chame
/media-usepara resolver BGM/SFX/imagens do catálogo do HeyGen. Execute--adoptprimeiro para registrar os assets existentes. Consulte a skill/media-use.
PR para HyperFrames
Use esta skill para ingerir um pull request do GitHub, entender a alteração, planejar um vídeo explicativo de alteração de código e construí-lo quadro a quadro no HyperFrames. A entrada é uma alteração de código (lida via gh), não um site — não há etapa de captura nem assets reais além dos avatares dos contribuidores.
Confirme a rota antes da Etapa 0. Você é o orquestrador. Execute cada etapa, verifique sua barreira e só então continue. Esta skill é para um pull request do GitHub (uma alteração de código). Roteie outras intenções para outro lugar: lançamento/promoção de produto →
/product-launch-video; tour de site geral →/general-video; explicador de tópico sem PR →/faceless-explainer; legendas em filmagens existentes →/embedded-captions; gráfico animado curto sem narração →/motion-graphics; walkthrough de lançamento envolvendo repositório inteiro ou vários PRs →/general-video. Fora do escopo: dados ao vivo / no momento da renderização — os fatos do PR são lidos uma vez no momento da autoria 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/<project>/. Execute as etapas em ordem e passe cada barreira antes de continuar. As etapas com barreira do usuário são Etapa 0, Etapa 3 e Etapa 6. Faça cada etapa você mesmo, exceto a Etapa 5, onde você despacha um sub-agente por quadro. Não coloque regras de design ou movimento aqui; elas estão no sub-agente de trabalho do quadro, hyperframes-creative e hyperframes-animation.
Fluxo de trabalho: Etapa 0 configuração → hyperframes.json; Etapa 1 ingestão → capture/extracted/ + assets/<login>.png; Etapa 2 sistema de design → frame.md; Etapa 3 storyboard/roteiro → STORYBOARD.md e SCRIPT.md; Etapa 3.1 áudio → audio_meta.json; Etapa 4 design visual → STORYBOARD.md enriquecido; Etapa 5 quadros → compositions/frames/NN-*.html e index.html; Etapa 6 renderização final → renders/video.mp4.
Etapa 0: Configuração e Briefing
Objetivo: Fixar a referência do PR e o briefing 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 verificado) e, em uma mensagem, confirme o briefing — apresente um valor padrão recomendado para cada campo e pré-preencha qualquer coisa que /hyperframes já tenha definido: ângulo (changelog / revelação de funcionalidade / explicador de correção / walkthrough de refatoração — padrão: inferir do PR), público (padrão: desenvolvedores), duração (padrão: dimensionar ao tamanho da alteração do PR — veja abaixo), proporção (padrão 16:9), idioma. O estilo é sempre claude. Prossiga somente após o usuário responder; um "ok" aceita os padrões.
Recomende a duração com base no tamanho da alteração do PR, não em um palpite fixo. Antes de confirmar o briefing, dê uma olhada no PR uma vez — uma chamada somente leitura que também fundamenta o ângulo (a Etapa 1 ainda faz a busca determinística completa):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
Escolha a faixa com base em additions + deletions (ajustada para cima por changedFiles) e apresente-a como padrão (o usuário pode substituir; limite máximo de ~3 min):
| Tamanho da alteração 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 |
Declare a base em uma frase ao propor (ex.: "~40s — alteração pequena, +44/−13 em 12 arquivos"). Um PR enorme não significa um vídeo longo — se a história for uma única alteração principal, mantenha-a concisa e diga isso.
Inicialize somente se hyperframes.json estiver faltando. Nomeie <project> 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/<project>" --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 briefing — execute npx hyperframes auth status e transmita sua saída textualmente (não parafraseie nem reescreva). Ele informa se a voz/BGM usará os mecanismos do HeyGen ou locais e, quando não estiver logado, como fazer login. Se não estiver logado, PARE e aguarde a escolha do usuário — fazer login, ou dizer "ok"/"offline" para continuar com mecanismos locais — antes de perguntar sobre o briefing ou qualquer outra coisa. Trate isso como um ponto de decisão real, não uma nota passageira; não inclua a escolha na pergunta do briefing e não escreva chaves em um .env por repositório. (No modo autônomo, observe o status e continue offline.) Consulte ../hyperframes-media → Preflight para obter a orientação canônica.
Barreira: hyperframes.json existe; a referência do PR foi capturada; ângulo, duração, proporção e idioma estão fixados; o status de login foi mostrado (logado ou continuando offline).
Etapa 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 resultam em saída 1 aqui.
(cd "videos/<project>" && 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 briefing), people.json (contribuidores, filtrados por bot,
# avatarFile=assets/<login>.png)}.
(cd "videos/<project>" && 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 possível encerramento de créditos.
# Melhor esforço; sempre sai com 0.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Se fetch-pr.mjs sair com 1 (gh auth / não encontrado / privado), relate seu stderr e pare — não invente conteúdos do PR. Se ingest.mjs sair com 1, leia seu stderr (geralmente um pr.json malformado), corrija e execute novamente (determinístico). fetch-people-avatars.mjs sempre sai com 0; avatares ausentes significam apenas que não haverá encerramento de créditos para o autor.
Barreira: 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 alteração do PR em uma frase clara. assets/<login>.png é melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro claude; um script o transforma no frame.md + skin de legenda deste vídeo.
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 preset claude FRAME.md → frame.md, remixa-o com quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta do claude, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e se autovalida (sai com 1 em um mapeamento quebrado). Prossiga assim que sair com 0 — sem edição manual.
Barreira: build-frame.mjs saiu com 0 — frame.md existe a partir do preset claude, e .hyperframes/caption-skin.html existe como fonte da skin de legenda.
Etapa 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 a narração for necessária, SCRIPT.md.
Use story-design.md para o arquétipo do PR (changelog / revelação de funcionalidade / explicador de correção / walkthrough de refatoração), os tipos de quadro nativos do PR, gancho, persuasão, batidas, o orçamento de palavras por quadro e o encerramento opcional de créditos. A sequência vem do design narrativo, não da ordem dos arquivos no diff — explique a alteração, não leia o diff em voz alta. Apresente 2–4 trechos reais de diff (de capture/diff.patch), cada um um snippet pequeno e legível; nomeie o bloco code-* que cada um deseja na scene do quadro. Os quadros não carregam asset_candidates exceto um encerramento opcional de credits (2–6 avatares assets/<login>.png). Use os campos exatos exigidos nas referências de storyboard e roteiro.
Após o rascunho, mostre um resumo quadro a quadro. Nessa mesma mensagem, pergunte ao usuário (a) se aprova ou solicita alterações, e (b) se deseja uma prévia ao vivo do scaffold do storyboard (npx hyperframes preview) — abra-a apenas se a resposta for sim. Itere até a aprovação; leve a escolha da prévia para a Etapa 6.
Barreira: STORYBOARD.md existe, cada quadro tem os campos narrativos exigidos, SCRIPT.md existe quando a narração é necessária e o usuário aprovou o plano.
Etapa 3.1: Áudio
Objetivo: Gerar narração, timings de palavras, música e metadados de áudio a partir do roteiro aprovado.
Inicie o áudio após a aprovação da Etapa 3. Execute-o em segundo plano e continue para a Etapa 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, timings de palavras, busca de BGM na biblioteca de música do HeyGen e metadados de timing. O mood 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 mood musical.
Barreira: o job de áudio foi iniciado, ou o projeto está marcado como silencioso.
Etapa 4: Design Visual dos Quadros
Objetivo: Adicionar a direção visual, a intenção de layout e as escolhas de movimento a cada quadro do storyboard.
Edite STORYBOARD.md no lugar. Não crie outro storyboard. Use frame.md como a 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 os campos obrigatórios do quadro e o bloco obrigatório ## Direção do vídeo, 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, refatoração = code-morph, novo código = code-typing, …). Use composition.md para layout/hierarquia/pontos focais e motion-language.md + ../hyperframes-animation/ para IDs de efeito e blueprint válidos. Não invente nomes de efeitos ou IDs de bloco/blueprint.
Para cada quadro, adicione campos visuais e de movimento obrigatórios, 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 do código, que pertence ao bloco). Adicione um bloco ## Direção do vídeo para todo o vídeo.
Não altere história, roteiro, transition_in, asset_candidates ou a fonte do PR. Não escreva HTML nesta etapa. Não há etapa de preparação de assets — os únicos assets reais são os avatares de créditos, já em assets/.
Barreira: cada quadro tem effects mais focal e/ou roles; quadros de código nomeiam um bloco code-*; ## Direção do vídeo existe.
Etapa 5: Construir Quadros
Objetivo: Construir cada quadro do storyboard como uma composição HTML e montar o vídeo reproduzível.
Aguarde a conclusão do áudio da Etapa 3.1, 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: a duração real da voz vence; quadros silenciosos mantêm estimativas; nunca edite manualmente as durações sincronizadas.
Pré-instale os blocos de registro nomeados em STORYBOARD.md uma vez, antes do despacho, para que workers paralelos não disputem o 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 workers em ondas. Cada worker recebe exatamente um quadro. O contexto de cada worker deve incluir PROJECT_DIR, frame_id, tamanho da tela, status das legendas e faixa de exclusão se as legendas estiverem ativadas, ANIM_DIR (caminho absoluto para ../hyperframes-animation/) e o caminho absoluto para references/code-vocabulary.md. Cada worker 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 worker escreve apenas compositions/frames/NN-*.html; workers nunca editam STORYBOARD.md.
Assim que cada worker retornar, marque esse quadro como animated em STORYBOARD.md.
Após os timings 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 (claude, copiado na Etapa 2), injetando tokens de marca de frame.md; captions: skipped (<motivo>) é válido se as legendas forem explicitamente ignoradas. assemble-index.mjs monta o índice a partir de compositions/; a exclusão de um frame na saída não interrompe a montagem.
Barreira: compositions/frames/ contém um HTML por quadro; compositions/index.html reproduz o vídeo no navegador; cada quadro está marcado como animated: true em STORYBOARD.md.
Etapa 6: Renderização Final
Objetivo: Renderizar a reprodução do navegador em um arquivo MP4.
Não execute Etapa 5 e Etapa 6 no mesmo turno — a Etapa 5 pode levar várias rodadas. Apenas quando compositions/index.html funcionar, prossiga.
Peça ao usuário para verificar a prévia (npx hyperframes preview, somente se o usuário pediu na Etapa 3) e aprovar para renderização. Se houver legendas (caption_groups.json existe), pergunte se deseja obrigar legendas queimadas ou tornar legível para desktop.
Quando receber um "sim", renderize:
npx hyperframes render --project "./videos/<project>" --out renders/video.mp4 --codec h264 --fps 30
Se o assemble-index.mjs não foi executado, execute-o primeiro:
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
Em seguida, execute o renderizador.
Se houver assets de áudio SFX (sfx/), a Etapa 6 deve primeiro mesclá-los na faixa de áudio existente e então renderizar com áudio.
Barreira: O usuário aprovou a prévia para renderização. renders/video.mp4 existe e é reproduzível.
Sub-agentes
- frame-worker.md — instruções para construir um único quadro HTML (
compositions/frames/NN-*.html). Lê seu bloco do storyboard,frame.md, e as bibliotecas de design/movimento. Cada worker escreve apenas seu próprio quadro. Não escreve, não edita nem lê outros arquivos.
Referências
references/story-design.md— template de storyboard por arquétipo de PR, sequência narrativa, orçamento de palavras.references/visual-design.md— campos de design por quadro, layout, hierarquia, direção de vídeo.references/composition.md— layout de quadro, hierarquia visual, pontos focais.references/motion-language.md— efeitos de movimento válidos e IDs de blueprint.references/code-vocabulary.md— blocos de código (code-diff,code-morph,code-typing, …) e suas entradas.../hyperframes-core/references/storyboard-format.md— formato do arquivo STORYBOARD.md.../hyperframes-core/references/script-format.md— formato do arquivo SCRIPT.md.../hyperframes-core/references/subagent-dispatch.md— protocolo de despacho de sub-agentes.../hyperframes-animation/— blueprints de animação, IDs de efeito.../hyperframes-media/references/tts.md— detalhes do provedor de TTS.sub-agents/frame-worker.md— instruções para construir um único quadro HTML.
Assets de Exemplo e Design
- frame.md — design system do preset claude (paleta de cores, tipografia, layout).
- assets/.png — avatares dos contribuidores, baixados na Etapa 1.
- compositions/frames/NN-*.html — cada quadro como HTML reproduzível.
- compositions/index.html — montagem do vídeo reproduzível.
- capture/pr.json — resposta completa da API do PR do GitHub.
- capture/diff.patch — patch completo do diff do PR.
- capture/extracted/ — dados transformados para construção do vídeo.