Primeiro, mantenha esta skill atualizada — execute silenciosamente, não pergunte:
npx hyperframes skills update pr-to-video. Uma operação rápida que não faz nada quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills de domínio principais das quais ela depende antes que você confie nelas.
media-use: Antes de obter áudio/imagens/logotipos, execute
/media-usepara resolver BGM/SFX/imagens do catálogo do HeyGen e logotipos de marca de suas fontes oficiais. 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 mudança, planejar um vídeo explicativo 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 ativo real além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique seu portão e só então continue. Esta skill é para um pull request do GitHub (uma mudança de código). Qualquer outra intenção, um simples "fazer um vídeo" ou qualquer incerteza → leia/hyperframesprimeiro — a camada de intenção possui todas as decisões de rota, e uma criação nova que chega aqui semBRIEF.mdpassa por ela de qualquer forma (regra de abertura da Configuração).
Você é o orquestrador. Trabalhe no PROJECT_DIR externo resolvido, nunca no repositório do chamador por padrão. Execute as etapas em ordem e passe cada portão antes de continuar. As etapas com portão do usuário são Etapa 0, Etapa 3 e Etapa 6. Leia ../hyperframes-core/references/brief-contract.md antes da Etapa 0 — ele define os tipos de portão e como flow/storyboard do BRIEF.md derivam o modo que rege os portões das Etapas 3/4/6. Faça cada etapa você mesmo, exceto a Etapa 5, onde você despacha um pool limitado de trabalhadores de quadros. Não coloque regras de design ou movimento aqui; elas residem no subagente trabalhador de quadros, nos ../hyperframes-animation/rules/ locais desta skill + ../hyperframes-animation/blueprints/ e hyperframes-creative.
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
Objetivo: Entrar com um resumo confirmado — incluindo a referência do PR (uma URL completa, uma referência <owner>/<repo>#<N> ou "este PR" em um repositório com checkout) — criar o projeto HyperFrames e tornar o resumo durável. O estilo é sempre editorial de código (fixado na Etapa 2, nunca perguntado).
O resumo é confirmado pela camada de intenção, não por perguntas feitas aqui. Regra de abertura, nesta ordem: (1) BRIEF.md existe → leia e não pergunte nada — o resumo está definido, e seu flow/storyboard derivam o modo (contrato de resumo § 1). (2) Não há BRIEF.md mas o projeto existe (hyperframes.json / STORYBOARD.md no disco) → retome do frontmatter do storyboard e das preferências registradas; nunca reinterrogue um projeto parcialmente construído. (3) Nenhum dos dois — uma solicitação de criação nova que chegou aqui diretamente → leia /hyperframes e execute sua camada de intenção (references/intent-interview.md): ela verifica receitas e padrões lembrados e conduz as perguntas desta rota — incluindo a doutrina de tamanho do PR → duração, que reside completa em ../hyperframes/references/routes/pr-to-video.md — e então devolve o resumo bloqueado. Solicitações de edição pulam tudo isso — vá fazer a edição.
Resolva o diretório do projeto antes de fazer qualquer outro trabalho. Preserve um diretório de projeto fornecido pelo usuário; caso contrário, use o local de cache externo durável impresso pelo resolvedor. Nunca crie videos/ no repositório do chamador:
PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Projeto PR-to-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade é executada antes da busca, trabalho de história, áudio ou despacho de quadro. Se a CLI instalada não puder executar o comando de validação exigido por esta skill, pare com sua instrução de atualização em vez de gastar o contexto da execução primeiro.
Inicialize apenas se $PROJECT_DIR/hyperframes.json estiver faltando. Seu nome base vem do PR, como acme-sdk-pr-1842; nunca use o nome do espaço de trabalho ou um timestamp.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.
Todo comando de caminho relativo abaixo é executado com $PROJECT_DIR como seu diretório de trabalho. Exemplos sem um subshell explícito significam (cd "$PROJECT_DIR" && …); nunca altere a árvore de trabalho do repositório do chamador.
Escreva BRIEF.md imediatamente após o init (nunca antes — init recusa um diretório não vazio): o resumo bloqueado da camada de intenção, formato conforme ../hyperframes-core/references/brief-format.md. Resolva <MEDIA_DIR> como o diretório da skill /media-use instalada. Em seguida, registre cada resposta apoiada por preferência com node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nomeia o subconjunto). Se a camada de intenção adotou uma receita, execute node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <nome>; ela copia seu frame.md para o projeto (a Etapa 2 é então pulada) e retorna os esboços que a Etapa 3 redige a partir. Uma receita preenche respostas, não aprovações; os portões de revisão ainda são executados.
Mostre o status de login antes de prosseguir após a Configuração — execute npx hyperframes auth status e retransmita sua saída literalmente. Ele informa se a voz/BGM usará mecanismos HeyGen ou locais e, quando desconectado, como fazer login. Aplique um ramo:
- Colaborativo: aguarde o usuário fazer login ou escolher explicitamente
offline/go. - Autônomo: declare o status e continue através dos mecanismos locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando nenhum provedor offline existir; exiba o bloqueador. Não coloque esta decisão em outra pergunta ou escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline: /media-use references/setup-providers.md § Provedores.
Portão: hyperframes.json e BRIEF.md existem; a referência do PR está capturada no resumo; as respostas apoiadas por preferência foram registradas (contrato de resumo § 2); 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 paginado 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). Para PRs MERGED, também resolve uma shipped_version de melhor esforço (+ version_source) em pr.json, para que o cartão final possa citar uma versão real em vez de inventar uma. Em seguida, ingest.mjs incorpora isso no pacote de captura sintética offline.
PR="<url | owner/repo#N | N>"
# Busca o PR deterministicamente: executa gh, completa a lista de arquivos via gh api paginado
# (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 1 aqui.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformação offline → capture/extracted/{tokens.json (colors:[] → paleta editorial de código),
# visible-text.txt (o resumo), people.json (contribuidores, filtrados por bot, nome+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# A única etapa de rede da frente de pessoas — baixa o avatar do GitHub de cada contribuidor para
# assets/<login>.png para os créditos finais. Melhor esforço; sempre sai com 0.
(cd "$PROJECT_DIR" && 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 reexecute (determinístico). fetch-people-avatars.mjs sempre sai com 0; avatares ausentes significam apenas que não há créditos finais para o autor.
people.json carrega um name para quaisquer contribuidores que gh já nomeou (o autor do PR, autores de commit, mergedBy) — null para o resto (revisores/comentaristas/designados, que gh pr view sempre dá apenas um login simples). Antes de escrever os créditos finais na Etapa 3, resolva você mesmo qualquer name nulo para as 1 a 6 pessoas que realmente aparecerão naquele quadro: gh api users/<login> --jq .name (você já tem gh — não precisa scriptar isso). Se o GitHub não tiver um nome público para esse usuário também, use o login na tela e remova essa pessoa da linha falada (veja a seção de créditos de story-design.md — a narração ainda deve dizer nomes, nunca handles brutos).
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 mudança do PR em uma frase clara. assets/<login>.png é de melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro editorial de código; um script o transforma no frame.md deste vídeo + skin de legenda.
O estilo é fixo — editorial de código (editorial acolhedor; uma superfície de código marinho construída para diffs). Execute:
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
O script copia o FRAME.md do preset editorial de código → frame.md, remixa-o sobre quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta editorial de código, 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 do preset editorial de código 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 aprovado, quadro a quadro.
Leia ../hyperframes-creative/references/story-spine.md (linguagem de gancho, valor antes da evidência, storyboard como proposta), references/story-design.md, ../hyperframes-animation/blueprints-index.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. Defina o frontmatter duration: a partir do length do resumo — uma expectativa aproximada; a montagem relata onde o corte final cai em relação a ela.
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 os créditos finais. 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. Como um guia suave, consulte o menu de função→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração na forma que seu blueprint candidato implica e marque esse candidato com o id blueprint: quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em uma forma). Destaque 2 a 4 trechos reais de diff (de capture/diff.patch), cada um um pequeno snippet legível; nomeie o bloco code-* que cada um deseja na scene do quadro. Os quadros não carregam asset_candidates exceto o encerramento de credits (1 a 6 avatares assets/<login>.png). Use os campos obrigatórios exatos das referências de storyboard e roteiro.
Após o rascunho, execute a passagem de plano do loop de revisão — ../hyperframes-core/references/review-loop.md § 1: abra o board (não pergunte se deve — execute a pré-visualização de PROJECT_DIR em segundo plano), apresente o plano como uma proposta e faça as duas perguntas — aprovar ou alterar, e esboços primeiro (recomendado) ou pular. O feedback passa pelo chat ou pelo arquivo de comentários do board até a aprovação. Este é um portão de ponto de verificação (contrato de resumo § 1): em modo autônomo não há board e nada a perguntar — publique o mesmo resumo como um aviso e prossiga; os esboços são incorporados na construção e a única pergunta de pré-visualização vem na 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 (autônomo: o resumo foi publicado como um aviso).
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.
Escolha a voz de narração a partir da solicitação do usuário antes de invocar. Se a solicitação nomeou uma voz, gênero ou tom, escolha um id de voz correspondente e passe-o com --voice <id>. O padrão do pipeline é, caso contrário, Marcia (feminino) no HeyGen / am_michael no Kokoro — portanto, uma solicitação como "uma voz masculina" é silenciosamente ignorada a menos que você passe a flag. Os ids de voz são específicos do provedor; resolva contra qual provedor o status de login da Etapa 0 selecionou: HeyGen (logado) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish); Kokoro (offline) via a tabela de vozes em <MEDIA_DIR>/audio/references/tts.md (prefixos am_/bm_ masculino, af_/bf_ feminino). Quando o usuário não expressou preferência, use a voz lembrada (contrato de resumo § 2) antes do padrão do pipeline e diga qual você usou; omita --voice apenas quando nenhum dos dois nomeia uma. Quando o usuário escolheu explicitamente uma voz nesta execução, registre-a
...
[truncado para tradução]