assafkip/claude-video-editor

Criar um Vídeo — A Skill do Iniciante ao MP4 Final

Duas fases, oito portões sequenciais. Cada portão produz um artefato concreto que o próximo portão consome. Não pule portões.

Quando usar esta skill — e quando delegar

Use esta skill quando:

• O usuário é novo no HyperFrames e está começando com um conceito, roteiro ou esboço
• Ele quer um passo a passo completo, não material de referência do framework
• Ele ainda não decidiu o formato

Delegue quando:

• O usuário cola uma URL e quer um vídeo a partir desse site → invocar /website-to-hyperframes
• O usuário explicitamente quer um vídeo vertical 9:16 com rosto + sobreposições de cena → execute os Portões 1–4 aqui, depois invoque /short-form-video a partir do Portão 5
• O usuário pergunta sobre regras do framework, não sobre um vídeo → invocar /hyperframes

As duas fases

• Fase 1 — ENTREVISTA (Portões 1–4): uma passagem conversacional para coletar tudo antes de tocar em código. Intenção, formato, roteiro, voz, estilo, assets, ritmo. Sintetize em um BRIEF.md e aguarde aprovação explícita.
• Fase 2 — CONSTRUÇÃO (Portões 5–8): scaffold → storyboard → composições → lint → preview Studio → render rascunho → verificação visual → preview MP4 → render final.

---

Portão 1 · Intenção e formato

Faça uma pergunta de cada vez via AskUserQuestion, de múltipla escolha quando possível.

1. Para que é este vídeo? (promo · anúncio de mídia social · teaser de lançamento · demonstração de produto · tutorial · explicador · cartão de introdução/encerramento · outro)
2. Quem é o público? (aberta)
3. Duração alvo? (curto 10–20s · promo 20–45s · explicador 45–90s · aula 1,5–3 min · personalizado)
4. Proporção de tela? (16:9 1920×1080 · 9:16 1080×1920 · 1:1 1080×1080)
5. Taxa de quadros? (30 padrão · 60 para interface nítida · 24 cinematográfica)
6. Restrições de plataforma/entrega? (tamanho do arquivo · prazo · onde será reproduzido)

Portão: todos os seis capturados. Se a resposta for 9:16 + rosto, planeje delegar para /short-form-video no Portão 5.

Banco de perguntas completo: Read: references/interview-questions.md

---

Portão 2 · Roteiro e voz

1. Fonte do roteiro? (colar · esboço → redigirei · gravarei · TTS a partir de texto · sem narração)
2. Se TTS: preferência de voz. Ofereça opções de npx hyperframes tts --help. Capture também o ritmo.
3. Se rosto: caminho da gravação · tela cheia ou canto · precisa de transcrição? (npx hyperframes transcribe <file> --model small.en --json)
4. Legendas? (desligadas · hype · corporativo · karaokê palavra-por-palavra · minimalista)

Portão: roteiro capturado (ou redigido), plano de áudio capturado, plano de legendas capturado.

---

Portão 3 · Captura de estilo

Antes de perguntar qualquer coisa ao usuário, faça um inventário dos assets existentes. Verifique <workspace-root>/assets/ e qualquer pasta assets/ do projeto. Não pergunte pelo que já está lá.

Em seguida, pergunte progressivamente — eles não precisam responder a tudo:

1. Guia de estilo ou documento de marca? (colar/caminho · não)
2. Paleta de cores? (códigos hex · nenhuma — usar padrões MOTION_PHILOSOPHY)
3. Fontes? (nomes de fontes Google Fonts · caminhos de arquivo · nenhuma — usar padrões Inter + JetBrains Mono)
4. Arquivo de logotipo? (caminho · nenhum — usar marca de texto)
5. Vídeos de referência para estilo? (URLs/caminhos · nenhum)
6. Outros assets? (capturas de tela · fotos do produto · b-roll · música — liste os caminhos)
7. Estética MOTION_PHILOSOPHY (tela preta · texto cromado · grade de perspectiva · transições whip) ou um estilo diferente?
8. Ritmo? (cinético 1–2s · equilibrado 2–3s · relaxado 3–5s)
9. Música? (nenhuma · ambiente suave 0.15 · base musical 0.4 · completo 0.8 — caminho do arquivo se tiver)
10. Texto de encerramento / chamada para ação?

Nunca imponha uma marca ao usuário. Use os padrões MOTION_PHILOSOPHY apenas quando ele recusar explicitamente fornecer um estilo.

Fluxo de estilo completo + padrões MOTION_PHILOSOPHY: Read: references/style-intake.md

---

Portão 4 · Síntese do briefing (PORTÃO DURO antes da construção)

1. Leia MOTION_PHILOSOPHY.md se existir na raiz do workspace — obrigatório se presente. Se faltar, prossiga com os padrões em references/style-intake.md e anote a ausência no briefing.
2. Pergunte onde os projetos ficam se não for óbvio:
   • Se video-projects/ existir → use video-projects/<slug>/
   • Caso contrário → pergunte ao usuário
3. Escreva <project-folder>/BRIEF.md:
   • slug · intenção · público · dimensões · fps · duração
   • roteiro (completo ou esboço)
   • escolha de voz · plano de legendas · plano de rosto
   • perfil de estilo: paleta (hex), fontes, caminho do logotipo, vídeos de referência
   • ritmo
   • inventário de assets com caminhos
   • texto de encerramento / CTA
4. Mostre o briefing. AGUARDE aprovação explícita. Não prossiga para o Portão 5 sem um "sim, construa" claro.

---

Portão 5 · Scaffold e storyboard

Verificação de delegação primeiro

Se o briefing descreve um vídeo vertical 9:16 com rosto + sobreposições de cena, invoque /short-form-video AGORA e passe o briefing. O scaffold de 4 camadas é feito sob medida para esse formato.

Caso contrário, continue:

Scaffold

1. mkdir <project-folder>
2. Se um projeto irmão com formato semelhante existir, ofereça copiar seus hyperframes.json + meta.json como modelo. Caso contrário, dentro da pasta: npx hyperframes init
3. Edite meta.json com o slug, dimensões e fps do usuário.
4. Copie os assets fornecidos para <project-folder>/assets/.
5. Crie <project-folder>/assets/style-profile.md a partir do Portão 3 — fonte única da verdade para paleta/fontes/logotipo.

Storyboard

Gere <project-folder>/STORYBOARD.md usando o modelo em references/storyboard-template.md. Cada batida recebe:

Batida N — TÍTULO (início–fim, duração) — Conceito em uma frase
Elementos visuais: [cada elemento, tamanho, animação, temporização]
Linguagem de movimento: [tipo de movimento]
Eases usados: [3–4 eases GSAP distintos]
Saída: [transição para a próxima batida]
Áudio: [linha de VO / SFX / camada musical]

No topo do arquivo: uma tabela de temporização com cena · início · duração · arquivo de composição.

Proponha uma estrutura de três atos:

• Ato 1 (gancho) ≈ 20% da duração
• Ato 2 (corpo) ≈ 55%
• Ato 3 (recompensa + encerramento com pausa de 4–6 segundos) ≈ 25%

(MOTION_PHILOSOPHY §0 Lei 9, §1.)

Mapeie intenções do usuário → blocos de catálogo: Read: references/catalog-intent-map.md

Portão: mostre storyboard + tabela de temporização. Itere até o usuário aprovar.

---

Portão 6 · Construir composições

Invoque /hyperframes para regras do framework. Esta skill possui o scaffold e a disciplina; /hyperframes aplica as regras.

Scaffold de cada sub-composição

<div data-composition-id="scene-name" data-start="..." data-duration="...">
  <style>[data-composition-id="scene-name"] { /* escopado */ }</style>
  <!-- DOM -->
  <script>
    (function(){
      const SLOT_DURATION = ...;
      const tl = gsap.timeline({ paused: true });
      // ... tweens ...
      tl.to({}, { duration: SLOT_DURATION }, 0);   // âncora — MOTION_PHILOSOPHY Lei 11
      window.__timelines["scene-name"] = tl;
    })();
  </script>
</div>

Boilerplate completo + padrão de legendas + padrão de fundo ambiente: Read: references/composition-scaffold.md

Regras de construção

• Fundo ambiente em data-track-index="0" pela duração total da composição.
• Aberturas com texto cinético: espaçamento por palavra de 0.06–0.10s.
• Legendas como irmãs em nível de corpo da composição raiz em index.html, cada uma com data-track-index ≥ 20. Nunca dentro das timelines de cena (MOTION_PHILOSOPHY §3.13).
• Blocos de catálogo instalados via npx hyperframes add <name>. Imediatamente escope o CSS do bloco para [data-composition-id="..."] — blocos de catálogo vêm com regras html, body { ... } que vazam para o documento pai quando carregados como sub-composições.
• Vertical + rosto: envolva o rosto nativo 1920×1080 em uma transformação (translate + scale) para modo metade inferior ou tela cheia. (Se você chegar aqui em vez de /short-form-video, considere fortemente a delegação.)
• Aplique APENAS o que o usuário forneceu. Sua paleta, suas fontes, seu logotipo. Não injete nada além. Se eles escolheram os padrões MOTION_PHILOSOPHY, use a paleta + par de fontes de references/style-intake.md.

Determinismo

Sem Math.random(), sem Date.now(), sem fetch() em tempo de renderização. Use PRNGs baseadas em sementes ou hashes harmônicos de seno (MOTION_PHILOSOPHY §3.10).

---

Portão 7 · Lint → Preview Studio (PORTÃO DE PREVIEW 1 — OBRIGATÓRIO)

1. npx hyperframes lint — corrija todos os erros, trie os avisos.
2. npx hyperframes preview em segundo plano.
3. Aguarde "Studio running" em http://localhost:3002.
4. Entregue ao usuário a URL mais as URLs individuais de composição (http://localhost:3002/?comp=<id>). Se o projeto tiver blocos de shader WebGL, comece com as URLs individuais — a queda de software WebGL pode travar a composição mestra.
5. AGUARDE um "parece bom, renderize um rascunho" explícito antes de prosseguir. Silêncio não é aprovação.

Hot reload está ativo — as edições aparecem ao vivo.

---

Portão 8 · Render rascunho → verificação visual → preview MP4 → final

Render rascunho

npx hyperframes render --quality draft --output renders/<slug>-draft.mp4

Verificação visual (OBRIGATÓRIA antes da entrega)

Lint passar ≠ design funcionando. Extraia quadros e visualize-os.

1. mkdir -p renders/frames
2. Para cada momento herói de batida E cada transição:

   ffmpeg -y -ss <t> -i renders/<slug>-draft.mp4 -frames:v 1 -q:v 2 renders/frames/t<t>.png
   

3. Chame a ferramenta Read em cada PNG. A ferramenta Read carrega a imagem no contexto — não apenas liste nomes de arquivos.
4. Confirme por quadro: sem rostos cortados, modo facial correto por cena, texto legível e na paleta, sem overflow, transições aterrissam nas palavras pretendidas, sem quadros em branco.
5. Se algo estiver errado: corrija → re-renderize → re-verifique. Nunca entregue um rascunho quebrado.

Preview MP4 (PORTÃO DE PREVIEW 2 — OBRIGATÓRIO)

npx serve renders -p 8080 -n

Não use o http.server do Python — ele não suporta requisições HTTP Range, então a navegação por trechos quebra.

Entregue ao usuário http://localhost:8080/<slug>-draft.mp4. AGUARDE autorização explícita sobre reprodução e sincronia de áudio.

Render final

npx hyperframes render --quality standard --output renders/<slug>-final.mp4

Relate o caminho de saída. Pronto.

Lista de verificação completa de pré-voo e pré-entrega: Read: references/build-checklist.md

---

Inegociáveis (estruturais — não amenize)

• NÃO pule o PORTÃO DE PREVIEW 1 (Studio) nem o PORTÃO DE PREVIEW 2 (MP4 renderizado). Dois portões por construção, sempre.
• NÃO diga que uma renderização está concluída até que os quadros tenham sido extraídos E lidos via ferramenta Read.
• NÃO construa fora de uma pasta de projeto dedicada. Nunca coloque index.html na raiz do workspace.
• NÃO peça assets ao usuário antes de inventariar o workspace dele.
• NÃO pule a âncora tl.to({}, { duration: SLOT_DURATION }, 0) ao final de cada timeline de sub-composição. MOTION_PHILOSOPHY Lei 11.
• NÃO use Math.random() / Date.now() dentro da lógica de renderização. Apenas hashes baseados em semente.
• NÃO adicione class="clip" a tags <video>. Isso as quebra.
• NÃO imponha uma marca ao usuário. Pergunte primeiro; recorra aos padrões MOTION_PHILOSOPHY apenas quando ele recusar explicitamente.

---

Referências

• references/interview-questions.md — banco de perguntas completo por Portão
• references/style-intake.md — entrevista de estilo + padrões MOTION_PHILOSOPHY
• references/catalog-intent-map.md — "usuário diz X → instale Y"
• references/storyboard-template.md — modelo batida por batida + exemplo prático
• references/composition-scaffold.md — estilos escopados + boilerplate IIFE GSAP
• references/build-checklist.md — portões de pré-voo e pré-entrega

Externos (nível de workspace):

• MOTION_PHILOSOPHY.md — a única referência externa que esta skill assume existir. Linha de base estética. A queda está em references/style-intake.md se o arquivo estiver faltando.

Skills relacionadas

• /hyperframes — regras do framework, invocar no Portão 6
• /hyperframes-cli — init · lint · preview · render · transcribe · tts
• /hyperframes-registry — instalação de blocos de catálogo
• /gsap — referência de animação GSAP
• /short-form-video — delegar no Portão 5 para formato vertical 9:16 com rosto
• /website-to-hyperframes — delegar no Portão 1 se a entrada inicial for uma URL