media-use: Antes de obter áudio/imagens, chame
/media-usepara resolver BGM/SFX/imagens do catálogo HeyGen. Execute--adoptprimeiro para registrar ativos 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 e nenhum ativo real além dos avatares dos contribuidores.
Confirme a rota antes da Etapa 0. Você é o orquestrador. Execute cada etapa, verifique seu portão 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 geral de site →/website-to-video; explicador de tópico sem PR →/faceless-explainer; legendas em filmagens existentes →/embedded-captions; motion graphic curto sem narração →/motion-graphics; walkthrough de lançamento de repositório inteiro ou multi-PR →/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 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/<project>/. Execute as etapas em ordem e passe por cada portão antes de continuar. As etapas com portão de 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 subagente por quadro. Não coloque regras de design ou movimento aqui; elas residem no subagente de trabalho de quadro, hyperframes-creative e hyperframes-animation.
Workflow: 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: Bloquear 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 clonado) e, em uma única mensagem, confirme o briefing — apresente 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: dimensionar de acordo com o tamanho da alteração do PR — veja abaixo), aspecto (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 espiada 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 categoria de additions + deletions (ajustada para cima por changedFiles) e apresente-a como padrão (o usuário pode substituir; limite máximo ~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 |
Indique 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 mudança principal, mantenha-a concisa e diga isso.
Inicialize apenas se hyperframes.json estiver ausente. 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 literalmente (não parafraseie ou reescreva). Ele informa se a voz/BGM usará HeyGen ou mecanismos 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 "ok"/"offline" para continuar com mecanismos locais — antes de perguntar o briefing ou qualquer outra coisa. Trate 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, anote o status e continue offline.) Consulte ../hyperframes-media → Preflight para obter a orientação canônica.
Portão: hyperframes.json existe; a referência do PR foi capturada; ângulo, duração, proporção e idioma estão bloqueados; o status de login foi mostrado (logado, ou continuando offline).
Etapa 1: Ingestão do 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 gh auth / não encontrado / privado saem com 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 encerramento de créditos opcional. 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 de 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 apenas significam que não há encerramento de créditos para o autor.
Portão: 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 neste frame.md do vídeo + skin de legenda.
O estilo é fixo — claude (editorial caloroso; 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, 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 autovalida (sai com 1 em um mapeamento quebrado). Prossiga assim que sair com 0 — sem edição manual.
Portão: 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 / 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 encerramento de créditos opcional. A sequência vem do design narrativo, não da ordem de arquivos do 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 pequeno snippet legível; nomeie o bloco code-* que cada um deseja no scene do quadro. Os quadros não carregam asset_candidates, exceto um encerramento de credits opcional (2–6 avatares assets/<login>.png). Use os campos obrigatórios exatos das referências de storyboard e roteiro.
Após o rascunho, 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 esboço do storyboard (npx hyperframes preview) — abra-o apenas se for sim. Itere até a aprovação; leve a escolha de prévia para a Etapa 6.
Portão: STORYBOARD.md existe, cada quadro tem os campos narrativos obrigatórios, SCRIPT.md existe quando a narração é necessária e o usuário aprovou o plano.
Etapa 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 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, temporizações de palavras, consulta 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 musical.
Portão: o trabalho de áudio foi iniciado ou o projeto está marcado como silencioso.
Etapa 4: Design Visual do Quadro
Objetivo: Adicionar a direção visual, intenção de layout e escolhas de movimento a cada quadro do storyboard.
Edite STORYBOARD.md no local. 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 obrigatórios e o bloco ## Video direction obrigatório, 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, código novo = 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 de código, que pertence ao bloco). Adicione um bloco ## Video direction para todo o vídeo.
Não altere a 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 ativos — os únicos ativos reais são os avatares de créditos, já em assets/.
Portão: cada quadro tem effects mais focal e/ou roles; quadros de código nomeiam um bloco code-*; ## Video direction existe.
Etapa 5: Construir Quadros
Objetivo: Construir cada quadro do storyboard como uma composição HTML e montar o vídeo reproduzível.
Aguarde o término do áudio da Etapa 3.1, se o áudio foi iniciado. Em seguida, sincronize as durações e busque SFX; pule ambos se for 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 durações sincronizadas.
Pré-instale os blocos de registro nomeados em STORYBOARD.md de uma vez, antes do despacho, para que os trabalhadores 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 subagente 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 as 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; os trabalhadores nunca editam STORYBOARD.md.
À medida que cada trabalhador retorna, marque esse quadro como animated em STORYBOARD.md.
Depois que 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 (do claude, copiado na Etapa 2), injetando tokens de marca de frame.md; captions: skipped (<reason>)
...
[Nota: O conteúdo original foi truncado; a tradução segue o trecho fornecido.]