Primeiro, mantenha este skill atualizado — execute silenciosamente, não pergunte:
npx hyperframes skills update pr-to-video. Uma operação rápida sem efeito quando tudo está atualizado; caso contrário, ele atualiza este skill e os skills de domínio principais dos quais depende antes que você os utilize.
media-use: Antes de obter áudio/imagens/logos, execute
/media-usepara resolver BGM/SFX/imagens do catálogo HeyGen e logotipos de marca de suas fontes oficiais. Execute--adoptprimeiro para registrar ativos existentes. Veja o skill/media-use.
PR para HyperFrames
Use este 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 sua condição e só então continue. Este skill é para um pull request do GitHub (uma mudança de código). Qualquer outra intenção, um simples "faça um vídeo" ou qualquer incerteza → leia/hyperframesprimeiro — a camada de intenção é responsável por cada decisão 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 diretório de projeto externo resolvido PROJECT_DIR, nunca no repositório do chamador por padrão. Execute as etapas em ordem e passe cada condição antes de continuar. As etapas com aprovaçã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 condição e como BRIEF.md's flow/storyboard derivam o modo que governa as condições das Etapas 3/4/6. Faça você mesmo cada etapa, exceto a Etapa 5, onde você despacha um conjunto limitado de workers de quadros. Não coloque regras de design ou movimento aqui; elas vivem no sub-agente worker de quadros, no diretório local deste skill ../hyperframes-animation/rules/ + ../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/script → 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: Iniciar com um resumo confirmado — incluindo a referência do PR (uma URL completa, uma ref <owner>/<repo>#<N> ou "este PR" em um repositório clonado) — 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, em ordem: (1) BRIEF.md existe → leia-o e não pergunte nada — o resumo está resolvido, e seu flow/storyboard derivam o modo (contrato do resumo § 1). (2) Sem 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 tamanho do PR → duração, que vive inteira em ../hyperframes/references/routes/pr-to-video.md — e então retorna o resumo bloqueado. Solicitações de edição ignoram 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-para-vídeo: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade ocorre antes da busca, trabalho de story, áudio ou despacho de quadros. Se a CLI instalada não puder executar o comando de validação exigido por este 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 ausente. Seu nome base vem do PR, como acme-sdk-pr-1842; nunca use o nome do workspace ou um timestamp.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init verifica os skills instalados em relação aos mais recentes no GitHub e atualiza o conjunto global se algum estiver desatualizado.
Cada comando com 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 do skill /media-use instalado. Em seguida, registre cada resposta baseada em 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 <name>; ela copia seu frame.md no projeto (a Etapa 2 é então pulada) e retorna os esboços a partir dos quais a Etapa 3 elabora. Uma receita preenche respostas, não aprovações; as condições de revisão ainda são executadas.
Mostre o status de login antes de prosseguir com a Configuração — execute npx hyperframes auth status e transmita sua saída literalmente. Ele informa se a voz/BGM usará HeyGen ou motores locais e, quando desconectado, como fazer login. Aplique um ramo:
- Colaborativo: aguarde o usuário fazer login ou escolher explicitamente
offline/go. - Autônomo: informe o status e continue através dos motores locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando nenhum provedor offline existir; exponha o bloqueador. Não incorpore esta decisão em outra pergunta ou escreva chaves em um .env por repositório. Propriedade do auth e fallbacks offline: /media-use references/setup-providers.md § Providers.
Condição: hyperframes.json e BRIEF.md existem; a ref do PR está capturada no resumo; as respostas baseadas em preferência foram registradas (contrato do resumo § 2); o status de login foi mostrado (conectado ou continuando offline).
Etapa 1: Ingerir o PR (sem captura)
Objetivo: Buscar os fatos do PR e integrá-los ao projeto como fonte de informações. 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). Para PRs MERGED, ele 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 transforma 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 "$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,
# name+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 parte de pessoas — baixa o avatar GitHub de cada contribuidor
# para assets/<login>.png para o encerramento de créditos. 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 código 1 (gh auth / não encontrado / privado), relate seu stderr e pare — não fabrique conteúdo 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 apenas significam que não há encerramento de créditos para o autor.
people.json carrega um name para os contribuidores que gh já nomeou (autor do PR, autores de commit, mergedBy) — null para o restante (revisores/comentadores/designados, que gh pr view sempre fornece apenas um login simples). Antes de escrever o encerramento de créditos 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 criar script para isso). Se o GitHub também não tiver um nome público para esse usuário, recorra ao login na tela e remova essa pessoa da linha falada (veja a seção de créditos em story-design.md — a narração ainda deve dizer nomes, nunca handles brutos).
Condiçã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 neste frame.md do vídeo + skin de legenda.
O estilo é fixo — editorial de código (editorial caloroso; 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 FRAME.md do preset editorial de código → frame.md, o remixa sobre quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta do editorial de código, 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.
Condiçã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 Script
Objetivo: Transformar o PR em um plano de explicação quadro a quadro aprovado.
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 duration: do frontmatter a partir do length do resumo — uma expectativa aproximada; a montagem relata onde o corte final se alinha 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 o encerramento 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. Como um guia suave, consulte o menu função→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração no formato que seu blueprint candidato implica e marque esse candidato com o id blueprint: quando um se encaixar (a história ainda decide quais batidas existem — nunca force uma batida a se encaixar em um formato). Apresente 2–4 hunks de diff reais (de capture/diff.patch), cada um um pequeno trecho 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–6 avatares assets/<login>.png). Use os campos obrigatórios exatos das referências de storyboard e script.
Após redigir, execute a passagem de plano do loop de revisão — ../hyperframes-core/references/review-loop.md § 1: abra o quadro (não pergunte se deve — execute a prévia 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 quadro até ser aprovado. Esta é uma condição de checkpoint (contrato do resumo § 1): no modo autônomo, não há quadro e nada a perguntar — publique o mesmo resumo como um aviso e prossiga; os esboços são incorporados à construção, e a única pergunta de prévia vem na Etapa 6.
Condiçã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, temporizações de palavras, música e metadados de áudio a partir do script 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 com --voice <id>. O padrão do pipeline é Marcia (feminina) 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 em relação ao provedor que o status de login da Etapa 0 selecionou: HeyGen (conectado) 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, recorra à voz lembrada (contrato do resumo § 2) antes do padrão do pipeline e diga qual você usou; omita --voice apenas quando nenhum nomear uma. Quando o usuário escolheu explicitamente uma voz nesta execução, registre-a.