🔧 Por dentro do skill

A raiz da skill contém SKILL.md (o orquestrador), a subpasta scripts/ com 3 arquivos executáveis e a subpasta references/ com 3 arquivos de especificação. Nada mais.

Conhecer o mapa da pasta é o primeiro passo para entender o que o skill faz, modificar sem quebrar e criar novos skills no mesmo padrão.

Raiz = SKILL.md; especialização em subpastas; separação orquestrador/referência/scripts.

pipeline.md descreve os 7 passos do fluxo de produção; house-style.md define paleta, tipografia e regras visuais; gotchas.md lista os erros mais comuns e suas correções específicas.

Saber qual referência consultar em cada dúvida evita leitura desnecessária — cada arquivo tem escopo preciso e não se sobrepõe.

Especialização por domínio; carregadas sob demanda; sem redundância entre arquivos.

fetch-fonts.mjs baixa as fontes .woff2 locais; narration-template.sh gera o roteiro TTS com voz pf_dora --speed 0.98; composition-template.mjs é o gerador central que produz o index.html final com todas as cenas.

Cada script resolve um problema específico de automação — juntos, eliminam trabalho manual repetitivo e garantem determinismo na saída.

Automação por script; fontes locais; TTS; geração de HTML determinística.

O SKILL.md define 7 etapas numeradas: (1) confirmar tema, (2) escrever roteiro, (3) gerar áudio TTS, (4) baixar fontes, (5) rodar o gerador, (6) validar output, (7) entregar arquivos. Cada passo aponta para a referência certa.

O fluxo numerado é o que o Claude executa na ordem — entendê-lo permite depurar em qual passo um erro ocorreu.

Fluxo numerado; responsabilidade por etapa; referências apontadas por passo.

O SKILL.md instrui o Claude a ler house-style.md apenas antes de construir as cenas visuais, e gotchas.md apenas antes de validar o output — nunca tudo de uma vez.

Preserva contexto para a tarefa real em vez de gastar tokens carregando especificações que podem não ser necessárias.

On demand; economia de contexto; leitura condicional.

O SKILL.md embutiu preferências fixas do autor: narração em PT-BR, paleta dark premium âmbar, saída dupla (16:9 para YouTube e 9:16 para Shorts), e CTA final sempre apontando para INEMA.CLUB.

Esses defaults evitam que o usuário precise repetir preferências a cada pedido — estão codificados no skill para consistência de marca.

Defaults de marca; PT-BR; saída dupla; CTA consistente.

Seis variáveis fixas: fundo #0D1321, painel #1D2D44, borda #3E5C76, texto principal #F0EBD8, acento âmbar #FFC300 e destaque de código #2EC4B6. Nenhuma outra cor de destaque é permitida.

A paleta é a identidade visual do canal. Desviar dela quebra a consistência de marca — o âmbar deve ser o único ponto quente em tela.

Sistema fechado de cores; âmbar = único acento; código em ciano.

Sora para títulos e headlines (impacto visual forte), Inter para corpo de texto (legibilidade alta), JetBrains Mono para código e dados. As três famílias cobrem todos os casos de uso do vídeo.

Misturar fontes fora do sistema cria ruído visual. A regra é simples: título → Sora, texto → Inter, código → JetBrains.

Sora display; Inter corpo; JetBrains código; nunca Google Fonts CDN em runtime.

Toda cena tem uma camada de fundo composta de 4 elementos: (1) brilho radial âmbar (glow), (2) texto fantasma em baixa opacidade (ghost text), (3) grade de pontos (grid) e (4) textura de grão SVG (grain). Essa camada nunca é animada — fica estática.

A camada cria profundidade sem distração. Entender que ela é estática evita o erro de tentar animá-la (o que causa conflito com o framework).

Camada estática; 4 elementos; profundidade sem distração.

As fontes são baixadas pelo script fetch-fonts.mjs em formato .woff2 e referenciadas via @font-face local. O CDN do Google Fonts é proibido porque o renderizador pode não ter acesso à internet.

Um vídeo renderizado sem acesso ao CDN vai exibir fontes fallback — quebrando o visual. Fontes locais garantem consistência offline.

woff2 local; @font-face; fetch-fonts.mjs; offline-safe.

Vídeo não é web: cada cena deve ter no máximo 8-10 elementos visuais para não sobrecarregar o espectador. Headlines vão de 64px (subtítulo) a 172px (destaque máximo) — tamanhos impossíveis num site, mas necessários para leitura em TV ou mobile.

Designers vindos da web tendem a colocar informação demais por cena. A regra 8-10 elementos é o antídoto.

Máximo 10 elementos; fontes grandes; respiração visual; foco do espectador.

Todo vídeo termina com a cena scene9() (CTA), que exibe o logo âmbar e o endereço INEMA.CLUB em destaque máximo. Essa cena é gerada automaticamente pelo composition-template e não deve ser omitida.

A CTA é o ponto de conversão do canal. Incluída por padrão, ela garante que nenhum vídeo seja entregue sem a chamada para ação de marca.

scene9() automática; INEMA.CLUB; conversão de canal; nunca omitir.

AUDIO[] é o único array que o autor edita: cada entrada tem o arquivo MP3 e a duração em segundos. Dali o gerador deriva tudo — timing das cenas, duração das transições, posição dos audio tracks no HTML e as marcas de tempo da timeline GSAP.

Ter uma fonte única elimina dessincronias: não há como o áudio e a timeline discordarem porque ambos leem o mesmo dado.

Single source of truth; array AUDIO[]; derivação automática.

O gerador calcula o array S[] somando LEAD=0.5s (silêncio antes do áudio), TAIL=0.9s (silêncio depois) e FADE=0.45s (sobreposição de entrada/saída). Para cada cena: start = soma das durações anteriores, dur = audio.dur + LEAD + TAIL, audioStart = LEAD.

Entender o cálculo permite ajustar os parâmetros para vídeos com ritmo diferente sem quebrar a sincronização.

LEAD 0.5s; TAIL 0.9s; FADE 0.45s; S[] derivado de AUDIO[].

Cada cena é uma função sceneN(s) que retorna a string HTML da cena usando o objeto de timing s. As animações são declaradas com anim(element, props, delay), que acumula uma lista de tweens GSAP — nunca CSS direto.

Separar a estrutura visual (HTML) da animação (GSAP via anim()) facilita editar um sem tocar no outro.

sceneN() retorna HTML; anim() declara tweens; separação estrutura/movimento.

O gerador monta o HTML em 4 blocos: (1) .scene divs com o conteúdo visual, (2) .caption divs com legendas sincronizadas, (3) <audio> tracks alternados (cenas 1/3 no track A, 2/4 no track B), e (4) o bloco <script> com a timeline GSAP iniciada pausada.

Conhecer a estrutura dos 4 blocos permite editar o output manualmente quando necessário sem perder a lógica de sincronização.

4 blocos; timeline pausada; playback controlado por audio events.

Rodando o gerador com a flag --vertical, ele adiciona a classe .v ao <body> e aplica overrides CSS que reposicionam elementos para o formato 9:16 (1080×1920px). O arquivo gerado é sempre index.html, sobrescrevendo a versão 16:9.

Entender o mecanismo de override evita confusão entre os dois formatos e explica por que ambos compartilham o mesmo arquivo base.

body.v; CSS overrides; --vertical flag; um arquivo, dois formatos.

O composition-template define scene9() como a cena final hard-coded de CTA. Ela é sempre injetada após as cenas de conteúdo independente de quantas cenas o vídeo tenha — se o vídeo tem 7 cenas, a última é sempre a scene9 de CTA.

Saber que ela é automática evita duplicar a CTA manualmente, e saber que não pode ser omitida garante consistência de marca em todo output.

scene9() hard-coded; sempre última; INEMA.CLUB; nunca duplicar.

O framework do HyperFrames seta opacity:1 em todos os .clip durante a captura de frame — animações de opacidade neles são ignoradas. O alvo correto para fade-in/out é sempre .scene-inner, o container interno da cena.

Esse é o gotcha #1 mais frequente. O vídeo parece correto no browser mas o rendered final exibe cenas piscando ou sem transição.

Alvo correto = .scene-inner; .clip = proibido para opacity; framework override.

Cenas ímpares (1, 3, 5…) usam o <audio> track A; cenas pares (2, 4, 6…) usam o track B. Isso permite que um track termine naturalmente enquanto o outro já carrega o próximo áudio — eliminando o problema de overlapping clips onde dois áudios tocam ao mesmo tempo.

Se você colocar todos os áudios no mesmo track, haverá sobreposição inevitável nas transições com FADE. O padrão alternado resolve isso estruturalmente.

Track A = ímpares; Track B = pares; sobreposição eliminada; preload no track inativo.

Elementos puramente decorativos posicionados fora da área visível (ex.: glows que transbordam, ghost texts negativados) devem ter o atributo data-layout-ignore. Sem ele, o motor de layout do Remotion os contabiliza na bounding box e pode cortar ou deslocar a cena.

Decorativos off-canvas sem o atributo são a causa #1 de composições com crop inesperado no render.

data-layout-ignore; off-canvas; bounding box; decorativos invisíveis.

O gotchas.md proíbe qualquer @import url(fonts.googleapis.com) no HTML gerado. A variável sentinela google_fonts_import é usada nos templates para garantir que o gerador lance erro se detectar a string no output — forçando sempre o uso de @font-face local.

O ambiente de render não tem acesso à internet. Um import externo causa fontes faltando, texto em fallback sans-serif e visual completamente quebrado.

Proibido Google Fonts CDN; @font-face local; sentinela google_fonts_import.

No Windows e no git-bash, o ffmpeg tenta ler stdin interativo mesmo em chamadas não-interativas — travando o processo indefinidamente. A flag -nostdin desativa esse comportamento. Todos os comandos ffmpeg nos scripts do skill incluem ela por padrão.

Se você remover a flag ao adaptar um script, o processo travará silenciosamente no Windows sem mensagem de erro — difícil de diagnosticar.

-nostdin; Windows/git-bash; stdin interativo; processo travado.

O gerador e os templates proíbem Date.now(), Math.random() e qualquer fetch() dentro do HTML renderizável. O Remotion renderiza cada frame de forma independente — código não-determinístico produz frames inconsistentes e vídeo com flickering.

É a causa mais difícil de diagnosticar: o vídeo parece correto em preview mas treme no render final. A regra simples: se o valor muda entre execuções, não pertence ao template.

Determinismo total; sem Date.now; sem Math.random; sem fetch runtime; valores fixos.