📑 YAML frontmatter
The frontmatter is the metadata block at the top of the SKILL.md. It is delimited by two lines of three hyphens (---) and contains key-value pairs in YAML format. Without this block, Claude Code won't recognize the file as a valid skill.
The YAML frontmatter consists of exactly the lines between the first --- and the second one ---. Everything that comes after the second --- is the skill body in plain Markdown.
This is the first thing the Claude Code harness reads — if the YAML is malformed, the skill won't load.
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.
---The minimum valid frontmatter contains only name e description. Extra fields are ignored by the current harness.
🏷️ name = skill identity
The field name is the skill’s unique identifier. It must be identical to the name of the folder where the SKILL.md is stored, and strictly follow the format kebab-case (all lowercase, words separated by hyphens).
name walks through the systemThe harness looks for skills in ~/.claude/skills/<name>/SKILL.md. The folder name must match the field name.
The reminder system lists all skills by the name. This is the name that appears in Claude’s skills menu.
When Claude decides to use the skill, it calls Skill(skill: "video-explicativo") — the value is exactly the name.
/nameYou can invoke it manually with /video-explicativo. The harness maps directly from the slash to the name.
- ✓
video-explicativo - ✓
formato-curso - ✓
n8n-workflow-patterns - ✓ All lowercase, hyphens, no spaces
- ✗
VideoExplicativo— camelCase not allowed - ✗
video explicativo— spaces break the lookup - ✗
video_explicativo— underscore is not the standard - ✗ Folder name mismatch = skill won’t load
🎣 description = activation trigger
A description is the part most important in the SKILL.md. It’s the only field Claude reads to decide in real time whether to invoke the skill. Think of it as the packaging label: if the label doesn’t describe what’s inside, Claude grabs the wrong package.
Each turn, Claude receives all the names + descriptions of the skills available in context.
Claude compares the user's message with the descriptions and decides which skill has the greatest semantic overlap.
When there's a match, Claude calls the Skill tool before any other response — the description is law.
The body of SKILL.md can be perfect, but if the description is vague, the skill will never be triggered. Spend twice as much time on this field.
✨ Writing good descriptions
A good description has two parts: a one-sentence summary of what the skill does, followed by concrete trigger phrases with variations of requests the user might make. The more synonyms and variations, the greater the semantic coverage.
video-explicativoCreates complete explainer videos in PT-BR (HTML→MP4 via HyperFrames) from a topic — script, local TTS narration, premium dark animated scenes, captions, and an INEMA.CLUB CTA, in 16:9 (YouTube) and 9:16 (Shorts/Reels) formats.
Specifies the output (videos in PT-BR), the mechanism (HTML→MP4) and sub-products (script, TTS, captions, CTA).
Use when the user asks to "make a video," "explainer video," "video about X," "video for Shorts/Reels," "mini video tutorial," "INEMA video," or when they provide a topic and want a ready-to-use narrated video.
These are literal quotes of how the user would ask — with quotation marks, variations in wording, and distinct use cases.
- ✓ Includes phrases the user literally types
- ✓ Has synonyms: "video", "video tutorial", "mini video"
- ✓ Covers channel variations: YouTube, Shorts, Reels
- ✓ Mention the concrete output: MP4, narration, captions
- ✓ Uses "Use when the user asks for X, Y, Z"
- ✗ "Creates videos." — too vague, without triggers
- ✗ Only explains “how,” not “when to use”
- ✗ Uses technical jargon the user would never type
- ✗ Doesn't list the possible request variations
- ✗ One line only — minimum semantic coverage
For each trigger phrase you write, ask: "Would a real user, without knowing this skill exists, type this phrase?" If the answer is yes, it's a good trigger. Technical terms internal to the system are poor triggers.
📄 Body in Markdown
Everything that follows after of the second --- is the skill body. It's a regular Markdown document that describes, step by step, what Claude should do when the skill is activated. Claude reads and executes it literally.
The body of SKILL.md is the execution script from Claude. If the description is the trigger, the body is the operating instructions. Claude follows the body like a checklist: it reads, understands, and executes each step in order.
# 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⚠️ Common errors in SKILL.md
Small oversights in SKILL.md cause silent failures: the skill doesn’t load, doesn’t trigger, or triggers at the wrong time. Learn the most common mistakes and how to avoid them before publishing your skill.
The most common cause is malformed frontmatter. Always check: the file starts with --- on the first line (no spaces before it) and there is a second --- of closing.
name: meu-skill
description: Faz coisas...
# Corpo aquiWithout the delimiters ---, the harness ignores the frontmatter.
---
name: meu-skill
description: Faz coisas...
---
# Corpo aquiBoth --- required, each on its own line.
---
name: meu-skill
description: Texto longo
que continua aqui
sem indentação
---A line without indentation breaks YAML multiline — the parser sees a new field.
---
name: meu-skill
description: Texto longo
que continua aqui
com 2 espaços de indentação
---Continuation lines must have at least 2 spaces of indentation.
---
name: video-explicativo
description: Cria vídeos.
---Without concrete trigger phrases, Claude rarely makes the correct semantic match.
---
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".
---Trigger phrases in quotation marks dramatically increase the match.
- ✓ File starts with
---on line 1 (no BOM, no spaces) - ✓ Second
---present after the YAML fields - ✓
namesame as the folder name (kebab-case) - ✓
descriptionhas at least 3 concrete trigger phrases - ✓ Description continuation lines indented with 2 spaces
✅ Module 1.2 Summary
What you learned in this module
--- and contains name + description
name must be in kebab-case and identical to the skill folder name
description is the activation trigger — Claude reads this field to decide when to invoke the skill
---) is the execution script Claude follows step by step
--- missing, incorrect YAML indentation, vague description without trigger phrases
Learn how to structure the SKILL.md body in layers of depth—from basic usage to advanced cases—so Claude can execute the skill accurately in any context.