📑 Frontmatter YAML
O frontmatter é o bloco de metadados que fica no topo do SKILL.md. Ele é delimitado por duas linhas de três hifens (---) e contém pares chave-valor em formato YAML. Sem esse bloco, o Claude Code não reconhece o arquivo como um skill válido.
O frontmatter YAML são exatamente as linhas entre o primeiro --- e o segundo ---. Tudo o que vem depois do segundo --- é o corpo do skill em Markdown puro.
É a primeira coisa que o harness do Claude Code lê — se o YAML estiver malformado, o skill não carrega.
video-explicativo---
name: video-explicativo
description: Cria vídeos explicativos completos em PT-BR (HTML→MP4 via
HyperFrames) a partir de um assunto — roteiro, narração TTS local,
cenas animadas dark premium, captions e CTA do INEMA.CLUB, nos
formatos 16:9 (YouTube) e 9:16 (Shorts/Reels). Use quando o usuário
pedir para "fazer um vídeo", "vídeo explicativo", "vídeo sobre X",
"vídeo pra Shorts/Reels", "mini tutorial em vídeo", "vídeo do
INEMA", ou quando der um assunto e quiser um vídeo narrado pronto.
---O frontmatter mínimo válido contém somente name e description. Campos extras são ignorados pelo harness atual.
🏷️ name = identidade do skill
O campo name é o identificador único do skill. Ele deve ser idêntico ao nome da pasta onde o SKILL.md está guardado, e seguir rigorosamente o formato kebab-case (tudo minúsculo, palavras separadas por hífen).
name percorre o sistemaO harness procura skills em ~/.claude/skills/<name>/SKILL.md. O nome da pasta deve bater com o campo name.
O sistema-reminder lista todos os skills pelo campo name. É o nome que aparece no menu de skills do Claude.
Quando o Claude decide usar o skill, ele chama Skill(skill: "video-explicativo") — o valor é exatamente o name.
/nameO usuário pode invocar manualmente com /video-explicativo. O harness mapeia diretamente do slash para o name.
- ✓
video-explicativo - ✓
formato-curso - ✓
n8n-workflow-patterns - ✓ Todas minúsculas, hifens, sem espaços
- ✗
VideoExplicativo— camelCase não permitido - ✗
video explicativo— espaço quebra o lookup - ✗
video_explicativo— underscore não é padrão - ✗ Nome diferente da pasta = skill não carrega
🎣 description = gatilho de ativação
A description é a parte mais importante do SKILL.md. É o único campo que o Claude lê para decidir, em tempo real, se deve ou não invocar o skill. Pense nela como o rótulo da embalagem: se o rótulo não descrever o que está dentro, o Claude pega a embalagem errada.
Cada turn, o Claude recebe todos os nomes + descriptions dos skills disponíveis no contexto.
Claude compara a mensagem do usuário com as descriptions e decide qual skill tem maior sobreposição semântica.
Quando há match, Claude chama a Skill tool antes de qualquer outra resposta — a description é lei.
O corpo do SKILL.md pode ser perfeito, mas se a description for vaga o skill nunca será acionado. Invista o dobro do tempo nesse campo.
✨ Escrever boas descriptions
Uma boa description tem duas partes: uma frase-resumo do que o skill faz, seguida de frases-gatilho concretas com as variações de pedido que o usuário poderia fazer. Quanto mais sinônimos e variações, maior a cobertura semântica.
video-explicativoCria vídeos explicativos completos em PT-BR (HTML→MP4 via HyperFrames) a partir de um assunto — roteiro, narração TTS local, cenas animadas dark premium, captions e CTA do INEMA.CLUB, nos formatos 16:9 (YouTube) e 9:16 (Shorts/Reels).
Especifica o output (vídeos em PT-BR), o mecanismo (HTML→MP4) e os sub-produtos (roteiro, TTS, captions, CTA).
Use quando o usuário pedir para "fazer um vídeo", "vídeo explicativo", "vídeo sobre X", "vídeo pra Shorts/Reels", "mini tutorial em vídeo", "vídeo do INEMA", ou quando der um assunto e quiser um vídeo narrado pronto.
São citações literais de como o usuário pediria — com aspas, variações de linguagem e casos de uso distintos.
- ✓ Inclui frases que o usuário literalmente digita
- ✓ Tem sinônimos: "vídeo", "tutorial em vídeo", "mini-vídeo"
- ✓ Cobre variações de canal: YouTube, Shorts, Reels
- ✓ Menciona o output concreto: MP4, narração, captions
- ✓ Usa "Use quando o usuário pedir X, Y, Z"
- ✗ "Cria vídeos." — vago demais, sem gatilhos
- ✗ Só explica o "como", não o "quando usar"
- ✗ Usa jargão técnico que o usuário nunca digitaria
- ✗ Não lista as variações de pedido possíveis
- ✗ Uma linha só — cobertura semântica mínima
Para cada frase-gatilho que você escreve, pergunte: "Um usuário real, sem saber que esse skill existe, digitaria essa frase?" Se a resposta for sim, é um bom gatilho. Palavras técnicas internas ao sistema são péssimos gatilhos.
📄 Corpo em Markdown
Tudo o que vem depois do segundo --- é o corpo do skill. É um documento Markdown comum que descreve, passo a passo, o que o Claude deve fazer quando o skill for ativado. O Claude lê e executa literalmente.
O corpo do SKILL.md é o script de execução do Claude. Se a description é o gatilho, o corpo é a instrução de operação. O Claude segue o corpo como um checklist: lê, entende e executa cada etapa em ordem.
# Vídeo Explicativo (HyperFrames)
## Pré-requisitos (já instalados nesta máquina)
- Node.js ≥ 18, npx hyperframes, FFmpeg, Kokoro TTS
- Voz: pf_dora · `--speed 0.98` · sem espeak-ng
## Fluxo (sempre nesta ordem)
1. **Roteiro** — escreva `SCRIPT.md`: 6–9 cenas, do primeiro
princípio ao avançado, com exemplo real.
2. **Projeto** — `npx hyperframes init <nome> --example blank`
3. **Fontes** — `node fetch-fonts.mjs`
4. **Narração** — gere WAVs com Kokoro, voz `pf_dora`
5. **Composição** — adapte `composition-template.mjs`
6. **Validar** — `npx hyperframes lint`
7. **Render** — `--quality high`
## Regras de ouro (não-negociáveis)
- Animar `.scene-inner`, nunca o wrapper `.clip`
- Fontes locais via `@font-face` (não CDN)
- Timing vem de AUDIO[] — fonte única de verdade⚠️ Erros comuns no SKILL.md
Pequenos descuidos no SKILL.md causam falhas silenciosas: o skill não carrega, não é acionado ou é acionado na hora errada. Conheça os erros mais frequentes e como evitá-los antes de publicar seu skill.
A causa mais comum é o frontmatter malformado. Verifique sempre: o arquivo começa com --- na primeira linha (sem espaço antes) e há um segundo --- de fechamento.
name: meu-skill
description: Faz coisas...
# Corpo aquiSem os delimitadores ---, o harness ignora o frontmatter.
---
name: meu-skill
description: Faz coisas...
---
# Corpo aquiAmbos os --- obrigatórios, cada um em sua própria linha.
---
name: meu-skill
description: Texto longo
que continua aqui
sem indentação
---Linha sem indentação quebra o YAML multiline — o parser vê um campo novo.
---
name: meu-skill
description: Texto longo
que continua aqui
com 2 espaços de indentação
---Linhas de continuação devem ter pelo menos 2 espaços de recuo.
---
name: video-explicativo
description: Cria vídeos.
---Sem frases-gatilho concretas, o Claude raramente faz o match semântico correto.
---
name: video-explicativo
description: Cria vídeos em PT-BR.
Use quando o usuário pedir
"fazer um vídeo", "vídeo
sobre X", "tutorial em vídeo".
---Frases-gatilho com aspas aumentam drasticamente o match.
- ✓ Arquivo começa com
---na linha 1 (sem BOM, sem espaço) - ✓ Segundo
---presente após os campos YAML - ✓
nameigual ao nome da pasta (kebab-case) - ✓
descriptiontem pelo menos 3 frases-gatilho concretas - ✓ Linhas de continuação da description indentadas com 2 espaços
✅ Resumo do Módulo 1.2
O que você aprendeu neste módulo
--- e contém name + description
name deve estar em kebab-case e ser idêntico ao nome da pasta do skill
description é o gatilho de ativação — o Claude lê esse campo para decidir quando invocar o skill
---) é o script de execução que o Claude segue passo a passo
--- faltando, indentação YAML errada, description vaga sem frases-gatilho
Aprenda como estruturar o corpo do SKILL.md em camadas de profundidade — do uso básico aos casos avançados — para que o Claude execute o skill com precisão em qualquer contexto.