Instalação de plugins: Antes dos comandos de configuração ou atualização, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar:
npx hyperframes skills update pr-to-video. Uma operação rápida sem efeito 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, chame
/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. Quando o aplicativo host fornecer suas próprias ferramentas de música ou efeitos sonoros, use-as para música e efeitos sonoros.
PR para HyperFrames
Use esta skill para ingerir um pull request do GitHub, entender a mudança, planejar um vídeo explicativo da 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 nem ativos reais além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique sua porta 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 chegando aqui semBRIEF.mdpassa por ela de qualquer maneira (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 porta antes de continuar. As etapas portadas pelo usuário são Etapa 0, Etapa 3 e Etapa 6. Leia ../hyperframes/references/brief-contract.md antes da Etapa 0 — ela define os tipos de porta e como flow/storyboard do BRIEF.md derivam o modo que rege as portas 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/ + ../hyperframes-animation/blueprints/ locais desta skill e em 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 briefing confirmado — incluindo a referência do PR (uma URL completa, uma referência <owner>/<repo>#<N> ou "este PR" em um repositório clonado) — criar o projeto HyperFrames e tornar o briefing durável. O estilo é sempre código-editorial (fixado na Etapa 2, nunca perguntado).
O briefing é 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 briefing está resolvido, e seu flow/storyboard derivam o modo (contrato de briefing § 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) Nem um nem outro — 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 PR → duração, que reside inteiramente em ../hyperframes/references/routes/pr-to-video.md — e então devolve o briefing 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-para-vídeo: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
O preflight de capacidade é executado antes da busca, trabalho de história, áudio ou despacho de quadros. 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 somente se $PROJECT_DIR/hyperframes.json estiver faltando. Seu nome base vem do PR, por exemplo 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 briefing bloqueado da camada de intenção, formato conforme ../hyperframes/references/brief-format.md. Resolva <MEDIA_DIR> como o diretório da skill /media-use instalada. Em seguida, registre cada resposta com base 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 <nome>; ela copia seu frame.md para o 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 portas de revisão ainda são executadas.
Mostre o status de login antes de prosseguir além da Configuração — execute npx hyperframes auth status e retransmita sua saída literalmente. Ele informa se a narração/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 dobre esta decisão em outra pergunta nem escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline: /media-use references/setup-providers.md § Provedores.
Porta: hyperframes.json e BRIEF.md existem; a referência do PR está capturada no briefing; as respostas com base em preferência foram registradas (contrato de briefing § 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, ele também resolve um 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ético 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 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 código-editorial),
# visible-text.txt (o briefing), 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 — baixar o avatar do GitHub de cada contribuidor para
# assets/<login>.png para os créditos finais. Melhor esforço; sempre sai com código 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ú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 ausentes apenas significam 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/comentadores/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-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, 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).
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.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro código-editorial; um script o transforma no frame.md + skin de legenda deste vídeo.
O estilo é fixo — código-editorial (editorial caloroso; uma superfície de código azul 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 código-editorial → 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 código-editorial, 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). Prossiga 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 código-editorial, e .hyperframes/caption-skin.html existe como a 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 ../hyperframes-creative/references/story-spine.md (linguagem de gancho, valor-antes-de-evidência, storyboard-como-proposta, visuais rastreáveis por fonte), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md e ../hyperframes/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 briefing — uma expectativa aproximada; o relatório de montagem informa onde o corte final se encontra 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 função→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração na forma que seu blueprint candidato implica e taggeie esse blueprint: id candidato quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em uma forma). 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 quer na scene do quadro. Os quadros não carregam asset_candidates exceto o close de credits (1–6 avatares assets/<login>.png). Use os campos exatos exigidos das referências de storyboard e roteiro.
Após o rascunho, execute a passagem de plano do loop de revisão — ../hyperframes/references/review-loop.md § 1: apresente o plano como uma proposta e faça as duas perguntas — aprovar ou alterar, e esboços primeiro (recomendado) ou pular. O feedback chega como uma resposta de chat; faça loop até aprovação. Esta é uma porta de ponto de verificação (contrato de briefing § 1): no modo autônomo não há nada a perguntar — publique o mesmo resumo como um aviso e prossiga; os esboços são incorporados na construção, e a prévia final com sua única pergunta chega na Etapa 6.
Porta: STORYBOARD.md existe, todo quadro tem os campos narrativos exigidos, 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 é Marcia (feminina) no HeyGen / am_michael no Kokoro — então 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 o provedor que 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