Módulo 3.1 — Estrutura do skill

📂 A pasta `video-explicativo/`

Tudo que o Claude precisa para criar um vídeo explicativo vive dentro de uma única pasta bem organizada. Nem mais, nem menos.

💡 Conceito Principal

A pasta video-explicativo/ é o skill completo: ela contém o arquivo de entrada (SKILL.md), os scripts executáveis (scripts/) e as referências de apoio (references/). O Claude acessa cada camada apenas quando precisa — nunca tudo de uma vez.

árvore completa do skill

video-explicativo/
├── SKILL.md                          ← entrada principal
├── scripts/
│   ├── composition-template.mjs      ← gerador de composição
│   ├── fetch-fonts.mjs               ← baixa .woff2 subset latin
│   └── narration-template.sh         ← gera WAVs com Kokoro
└── references/
    ├── pipeline.md                   ← passo a passo completo
    ├── house-style.md                ← identidade visual dark premium
    └── gotchas.md                    ← armadilhas e correções

✓FAZER

✓Manter todos os 7 arquivos na estrutura exata
✓Copiar scripts para o projeto de vídeo antes de editar
✓Usar SKILL.md como porta de entrada sempre
✓Consultar references/ sob demanda via links

✗NÃO FAZER

✗Editar os scripts diretamente na pasta do skill
✗Ignorar os arquivos de referência achando que são opcionais
✗Criar arquivos extras na raiz do projeto (index-vertical.html, backups)
✗Renomear SKILL.md ou mudar sua localização

📄

SKILL.md

Porta de entrada

📁

scripts/

3 executáveis

📚

references/

3 guias de apoio

🗂️

7 arquivos

Estrutura mínima

📚 As 3 referências

Cada arquivo em references/ tem um propósito único e carregado apenas quando aquele conhecimento específico é necessário.

pipeline.md Passo a passo

O guia operacional completo. Explica em detalhe cada um dos 7 passos do fluxo: estrutura de projeto, como escrever o roteiro, gerar narrações com Kokoro, medir durações com ffprobe, montar a composição e renderizar em dois formatos.

house-style.md Identidade visual

Define o dark premium que Nei usa em todos os vídeos: paleta (#0D1321 bg, âmbar como acento, ciano como destaque), tipografia Sora 700–800 para títulos e Inter para corpo, JetBrains Mono para código. Formatos: 16:9 → 1920×1080 e 9:16 → 1080×1920. CTA final obrigatória: INEMA.CLUB.

gotchas.md Armadilhas

Problemas reais já enfrentados: overlapping_clips_same_track (alternar data-track-index 1/3 para cenas, 2/4 para captions), gsap_exit_missing_hard_kill (adicionar tl.set após fade-out), elementos decorativos off-canvas marcados com data-layout-ignore, e uso de ffmpeg -nostdin no git-bash.

📊

Dados do design de divulgação progressiva

O SKILL.md aponta para os 3 arquivos de referência via links Markdown relativos. O Claude nunca carrega todas as referências de uma vez — ele abre apenas o arquivo que é linkado quando aquele contexto específico é necessário. Isso mantém a janela de contexto leve.

⚡

Dica prática

Antes de iniciar qualquer vídeo, leia o pipeline.md completo. Ele documenta casos reais já vividos e evita que você repita erros que tomam horas para diagnosticar — especialmente o erro do ffmpeg -nostdin no Windows/git-bash.

🔀

pipeline.md

7 passos detalhados

🎨

house-style.md

Dark premium âmbar

⚠️

gotchas.md

Erros reais evitados

🔧 Os 3 scripts

Cada script em scripts/ é um template que você copia para o projeto de vídeo e adapta — nunca edita diretamente no skill.

⚡

Regra de ouro dos scripts

Scripts são templates — não executáveis diretos. Você copia para o seu projeto de vídeo (renomeando conforme necessário) e então adapta. O original no skill permanece intocado para o próximo vídeo.

⚙️

composition-template.mjs

Gerador principal da composição HyperFrames. Define AUDIO[] com durações reais, CAPTIONS[], função sceneN() por cena HTML e anim(i,t) para tweens GSAP.

Copiar como build-index.mjs

🔤

fetch-fonts.mjs

Baixa as fontes Sora, Inter e JetBrains Mono do Google Fonts como arquivos .woff2 subset latin, gerando assets/fonts/fonts.css com @font-face locais.

Execute: node fetch-fonts.mjs

🎙️

narration-template.sh

Shell script que escreve os arquivos assets/txt/sN.txt e chama o HyperFrames TTS com voz pf_dora --speed 0.98 para gerar assets/audio/sN.wav.

Copiar como assets/narration.sh

narration-template.sh — trecho

# Gera cada cena via HyperFrames TTS
for i in 1 2 3 4 5 6 7 8; do
  npx -y hyperframes tts "txt/s$i.txt" \
    --voice pf_dora \
    --speed 0.98 \
    --output "audio/s$i.wav"
done

# Mede durações com ffprobe
for i in 1 2 3 4 5 6 7 8; do
  d=$(ffprobe -v error \
    -show_entries format=duration \
    -of default=noprint_wrappers=1:nokey=1 \
    "audio/s$i.wav" 2>/dev/null)
  echo "s$i: ${d}s"
done

✓ FAZER com os scripts

✓Copiar para o projeto antes de editar
✓Rodar node fetch-fonts.mjs antes do primeiro render
✓Preencher AUDIO[] com durações REAIS do ffprobe

✗ NÃO FAZER com os scripts

✗Usar Google Fonts via CDN (lint falha: google_fonts_import)
✗Usar durações estimadas em vez das medidas com ffprobe
✗Esquecer ffmpeg -nostdin no Windows (arquivo não gerado)

⚙️

composition

Gerador principal

🔤

fetch-fonts

Woff2 local

🎙️

narration

pf_dora 0.98

📋

Templates

Copiar, adaptar

🔢 O fluxo de 7 passos do SKILL.md

O SKILL.md define uma sequência obrigatória. Seguir nessa ordem evita retrabalho — cada passo depende do anterior.

1 Roteiro — escreve SCRIPT.md

6–9 cenas, do primeiro princípio ao avançado. Narração curta por cena (≈100s de voz ≈ 1:50 de vídeo). Expandir siglas na fala: "SKILL.md" → "SKILL ponto M D".

2 Projeto — init HyperFrames

npx hyperframes init <nome> --example blank --non-interactive. Copiar design.md (house style) para a raiz.

3 Fontes — baixa .woff2 subset latin

node fetch-fonts.mjs → gera assets/fonts/fonts.css. Obrigatório: lint falha se usar CDN de fontes.

4 Narração — gera WAVs Kokoro

Voz pf_dora --speed 0.98. Medir durações com ffprobe. Template em scripts/narration-template.sh.

5 Composição — adapta o template

Copiar como build-index.mjs. Preencher AUDIO[] com durações REAIS. Rodar: node build-index.mjs (16:9) e node build-index.mjs --vertical (9:16).

6 Validar — lint + inspect

npx hyperframes lint (0 erros) e npx hyperframes inspect --samples 16 (0 problemas). Corrigir seguindo references/gotchas.md.

7 Render — draft → high

Draft primeiro para conferir, depois --quality high. Gera renders/<nome>-16x9.mp4 e renders/<nome>-9x16.mp4.

🚨

Ordem obrigatória

O passo 3 (fontes) DEVE vir antes do passo 5 (composição), pois o template importa assets/fonts/fonts.css que só existe após o fetch. Pular essa ordem gera erro de arquivo não encontrado em tempo de execução.

📝

Roteiro → Render

7 passos fixos

⏱️

ffprobe

Durações reais

✅

lint + inspect

0 erros antes render

🎬

16:9 + 9:16

Sempre os dois

🧠 Divulgação progressiva na prática

O design de divulgação progressiva é o que torna o skill eficiente: o Claude carrega só o que precisa, quando precisa.

💡 Como funciona na memória do Claude

Nível 1 — Sempre na memória: só o name e description do skill. O Claude sabe que o skill existe e quando usá-lo.

Nível 2 — Carregado na tarefa: o SKILL.md completo, com os 7 passos e os links para referências.

Nível 3 — Carregado sob demanda: cada arquivo em references/ só quando aquele passo específico está sendo executado.

📊

Por que isso importa (números reais)

~2KB

SKILL.md base

+15KB

references/ total

3×

contexto mais leve

⚡

Padrão replicável

Esse design funciona para qualquer skill complexo: SKILL.md enxuto com links explícitos para referências especializadas. Quando o Claude executa o passo 6 (validar), ele acessa gotchas.md. Quando monta a composição, acessa pipeline.md. Nunca os dois ao mesmo tempo sem necessidade.

✓ Design correto de SKILL.md

✓Description clara e específica (o gatilho de quando usar)
✓Fluxo enxuto com links para referências detalhadas
✓Referências organizadas por assunto (pipeline / style / gotchas)

✗ Design incorreto de SKILL.md

✗Colocar todo o conteúdo de references/ dentro do SKILL.md
✗Description vaga como "cria vídeos" sem especificidade
✗Misturar regras de identidade visual com regras de execução

🧠

Nível 1

name + description

📄

Nível 2

SKILL.md completo

📚

Nível 3

references/ sob demanda

⚡

Contexto leve

Resposta mais rápida

🎯 O padrão do usuário Nei

Toda produção de vídeo de Nei segue convenções firmes — não são preferências opcionais, são a assinatura de identidade do canal.

💡 Convenções não-negociáveis

→ PT-BR obrigatório: todo texto, narração e legenda em português brasileiro. Siglas expandidas na voz ("SKILL ponto M D").

→ Dark premium âmbar: paleta #0D1321 fundo, âmbar como acento principal, ciano para destaques secundários.

→ Dois formatos sempre: 16:9 (1920×1080) para YouTube e 9:16 (1080×1920) para Shorts. Ambos em cada projeto.

→ CTA INEMA.CLUB sempre: última cena de todo vídeo é "CONTINUA EM INEMA.CLUB" — já incluída no template.

narração padrão CTA final

# Cena s9 — CTA INEMA.CLUB (incluída no template, não remover)
write s9 "Isso é conteúdo do INEMA ponto CLUB. Acesse: inema ponto club."

# Render — sempre os dois formatos
node build-index.mjs && npx hyperframes render \
  --quality high \
  --output renders/<nome>-16x9.mp4

node build-index.mjs --vertical && npx hyperframes render \
  --quality high \
  --output renders/<nome>-9x16.mp4

⚡

A voz de Nei: pf_dora

A voz pf_dora com velocidade --speed 0.98 é a voz padrão de todos os vídeos. Alternativas PT-BR disponíveis: pm_alex (masculina) e pm_santa (masculina formal). A primeira execução do TTS baixa ~340MB de modelo — sem chave de API, sem espeak-ng.

🚨

CTA INEMA.CLUB é inegociável

A cena 9 (CTA INEMA.CLUB) já está pré-construída no composition-template.mjs. Ela NUNCA deve ser removida. É a assinatura de canal e parte da identidade da marca. Adicionar mais cenas? Insira antes da cena 9, não depois.

🇧🇷

PT-BR

Sempre, sem exceção

🌑

Dark premium

#0D1321 + âmbar

📐

16:9 + 9:16

Ambos obrigatórios

🌐

INEMA.CLUB CTA

Última cena sempre

📋 Resumo do Módulo 3.1

O que você aprendeu

✓A estrutura exata dos 7 arquivos do skill video-explicativo/
✓O propósito de cada um dos 3 arquivos em references/
✓Como cada script funciona e como deve ser usado
✓Os 7 passos obrigatórios do fluxo e sua ordem
✓Como a divulgação progressiva mantém o contexto leve
✓As convenções não-negociáveis de Nei (PT-BR, dark premium, 16:9+9:16, CTA)

Fatos para lembrar

→Voz padrão: pf_dora --speed 0.98
→LEAD = 0.5s · TAIL = 0.9s · FADE = 0.45s
→Fontes: Sora 700–800 / Inter 400–600 / JetBrains Mono
→Fundo: #0D1321 · Acento âmbar · Ciano destaque
→7 arquivos totais: 1 SKILL.md + 3 scripts + 3 references

Próximo módulo:

3.2 🎨 House style dark premium

Mergulhe na identidade visual: paleta #0D1321, tipografia Sora, animações GSAP, e como o âmbar e o ciano criam o mood premium nos vídeos do INEMA.CLUB.

←Voltar para Trilha 3 Próximo Módulo→

📂 A pasta video-explicativo/