Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de execução do plugin 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 e sem efeitos 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ê possa usá-las.
media-use: Antes de obter áudio/imagens/logos, chame
/media-usepara resolver BGM/SFX/images do catálogo HeyGen e logotipos de marcas 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 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 nem ativos reais além dos avatares dos contribuidores.
A porta de entrada é
/hyperframes. Você é o orquestrador. Execute cada etapa, verifique sua condição de validaçã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 "faça um vídeo" genérico, ou qualquer incerteza → leia/hyperframesprimeiro — a camada de intenção é a dona de toda 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 PROJECT_DIR externo resolvido, nunca no repositório do chamador por padrão. Execute as etapas em ordem e passe cada condição de validação antes de continuar. As etapas com validação do usuário são a Etapa 0, a Etapa 3 e a Etapa 6. Leia ../hyperframes/references/brief-contract.md antes da Etapa 0 — ela define os tipos de condição de validação e como o flow/storyboard do BRIEF.md derivam o modo que rege as condições de validação da Etapa 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 residem no sub-agente trabalhador de quadro, no ../hyperframes-animation/rules/ local + ../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 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 e não pergunte nada — o briefing está resolvido, e seu flow/storyboard derivam o modo (contrato do 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 meio 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 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-to-video: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
A verificação de capacidade é executada antes da busca, do trabalho de história, do áudio ou do 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 apenas se $PROJECT_DIR/hyperframes.json estiver faltando. 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 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 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 <name>; ela copia seu frame.md para o projeto (a Etapa 2 é então pulada) e retorna os esqueletos a partir dos quais a Etapa 3 esboça. Uma receita preenche respostas, não aprovações; as etapas 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 repita 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: informe o status e continue através dos mecanismos locais disponíveis.
Não omita silenciosamente uma capacidade necessária quando não existir provedor offline; exponha o bloqueador. Não incorpore 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.
Condição de validação: hyperframes.json e BRIEF.md existem; a referência do PR está capturada no briefing; as respostas apoiadas por preferência foram registradas (contrato do 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 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 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 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 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 para pessoas — baixa 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), reporte seu stderr e pare — não invente 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 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 criar script para 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 fala (consulte a seção de créditos do story-design.md — a narração deve ainda dizer nomes, nunca handles brutos).
Condição de validaçã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 código-editorial; um script o transforma no frame.md + skin de legenda deste vídeo.
O estilo é fixo — código-editorial (editorial acolhedor; 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 paleta própria do código-editorial, um design completo), copia a skin de legenda do preset para .hyperframes/caption-skin.html e autovalida (sai com código 1 em um mapeamento quebrado). Prossiga assim que sair com código 0 — sem edição manual.
Condição de validação: 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-da-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; 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 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 blueprint: id 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 de 2 a 4 trechos de diff reais (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 fechamento de credits (1–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 ciclo 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; repita até aprovação. Esta é uma condição de validação de checkpoint (contrato do 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 única pergunta de visualização vem na Etapa 6.
Condição de validaçã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 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 (feminino) no HeyGen / am_michael no Kokoro — portanto, uma solicitação como "uma voz masculina" é ignorada silenciosamente 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 (contrato do briefing § 2) antes do padrão do pipeline,
…
[trucado para tradução]