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 autônomas 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 alterações quando tudo está atualizado; caso contrário, 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/logos, chame
/media-usepara resolver BGM/SFX/imagens do catálogo HeyGen e logotipos de marcas de suas fontes oficiais. Execute--adoptprimeiro para registrar assets 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 nem assets reais 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 "faça um vídeo", ou qualquer incerteza → leia/hyperframesprimeiro — a camada de intenção é dona de toda decisão de rota, e uma criação nova chegando 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/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 governa 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 quadro. Não coloque regras de design ou movimento aqui; elas vivem no subagente trabalhador de quadro, nas regras locais desta skill ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/, 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 brief 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 brief durável. O estilo é sempre code-editorial (fixado na Etapa 2, nunca perguntado).
O brief é 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 brief está definido, e seu flow/storyboard deriva o modo (brief contract § 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 diretamente aqui → 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 vive inteira em ../hyperframes/references/routes/pr-to-video.md — então devolve o brief 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 do 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 pré-voo é 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 brief 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 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 para dentro do projeto (a Etapa 2 é então pulada) e retorna os esboços que a Etapa 3 redige. 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 repita sua saída literalmente. Ele informa se voz/BGM usará HeyGen ou mecanismos 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 pelos mecanismos locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando nenhum provedor offline existir; mostre o bloqueador. Não junte esta decisão a outra pergunta ou escreva chaves em um .env por repositório. Propriedade de autenticação e fallbacks offline: /media-use references/setup-providers.md § Providers.
Portão: hyperframes.json e BRIEF.md existem; a referência do PR está capturada no brief; as respostas baseadas em preferência foram registradas (brief contract § 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 a 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
# code-editorial), visible-text.txt (o brief), people.json (contribuidores, filtrados
# por bots, 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 do front de pessoas — baixa o avatar de cada contribuidor do
# GitHub 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), reporte seu stderr e pare — não fabrique conteúdos de 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 null para as 1-6 pessoas que realmente aparecerão naquele quadro: gh api users/<login> --jq .name (você já tem gh — não precisa criar um script para isso). Se o GitHub também não tiver um nome público para aquele usuário, use o login na tela e remova essa pessoa da linha falada (consulte a seção de créditos do 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 é melhor esforço — sua ausência não é uma falha.
Etapa 2: Sistema de Design
Objetivo: Adotar o preset de quadro code-editorial; um script o transforma no frame.md + skin de legenda deste vídeo.
O estilo é fixo — code-editorial (editorial quente; 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 code-editorial → frame.md, o remixa em quaisquer tokens de marca em capture/extracted/tokens.json (um PR não tem nenhum → colors:[]/fonts:[] mantém a própria paleta do code-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 ele sair com código 0 — sem edição manual.
Portão: build-frame.mjs saiu com código 0 — frame.md existe a partir do preset code-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-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 brief — uma expectativa aproximada; a montagem relata onde o corte final fica 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 de 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 papel→blueprint em ../hyperframes-animation/blueprints-index.md: para cada batida, escreva a narração no formato que seu blueprint candidato implica e marque esse id blueprint: candidato quando um se encaixar (a verdade da história ainda decide quais batidas existem — nunca force uma batida a se encaixar em um formato). 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 rascunhar, 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 no chat; faça loop até aprovação. Este é um portão de checkpoint (brief contract § 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 vem na Etapa 6.
Portão: 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 (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 roteiro aprovado.
Inicie o áudio após a aprovação da Etapa 3. Execute-o em segundo plano e então 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 (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 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 o usuário não expressou preferência, recorra à voz lembrada (brief contract § 2) antes do pipeline padrão.
A documentação completa foi truncada para fins de tradução, mas a tradução cobre o conteúdo fornecido.