📑 Frontmatter YAML
El frontmatter es el bloque de metadatos que está al inicio del SKILL.md. Está delimitado por dos líneas de tres guiones (---) y contiene pares clave-valor en formato YAML. Sin ese bloque, Claude Code no reconoce el archivo como una skill válida.
El frontmatter YAML son exactamente las líneas entre el primer --- y el segundo ---. Todo lo que viene después del segundo --- es el cuerpo de la skill en Markdown puro.
Es lo primero que lee el harness de Claude Code: si el YAML está mal formado, la skill no se carga.
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.
---El frontmatter mínimo válido contiene solamente name e description. El harness actual ignora los campos adicionales.
🏷️ name = identidad de la skill
El campo name es el identificador único del skill. Debe ser idéntico al nombre de la carpeta donde el SKILL.md está guardado, y seguir rigurosamente el formato kebab-case (todo en minúsculas, palabras separadas por guiones).
name recorre el sistemaEl harness busca skills en ~/.claude/skills/<name>/SKILL.md. El nombre de la carpeta debe coincidir con el campo name.
El sistema-reminder enumera todas las skills por el campo name. Es el nombre que aparece en el menú de skills de Claude.
Cuando Claude decide usar la skill, llama a Skill(skill: "video-explicativo") — el valor es exactamente el name.
/nameEl usuario puede invocar manualmente con /video-explicativo. El harness mapea directamente del slash al name.
- ✓
video-explicativo - ✓
formato-curso - ✓
n8n-workflow-patterns - ✓ Todo en minúsculas, con guiones, sin espacios
- ✗
VideoExplicativo— no se permite camelCase - ✗
video explicativo— el espacio rompe la búsqueda - ✗
video_explicativo— el guion bajo no es estándar - ✗ Nombre distinto al de la carpeta = la skill no carga
🎣 description = disparador de activación
A description es la parte más importante del SKILL.md. Es el único campo que Claude lee para decidir, en tiempo real, si debe invocar el skill o no. Piensa en ella como el etiqueta del envase: si la etiqueta no describe lo que contiene, Claude elige el paquete equivocado.
En cada turno, Claude recibe todos los nombres + descriptions de las skills disponibles en el contexto.
Claude compara el mensaje del usuario con las descripciones y decide qué skill tiene mayor superposición semántica.
Cuando hay una coincidencia, Claude llama a la herramienta Skill antes de cualquier otra respuesta: la descripción es la ley.
El cuerpo del SKILL.md puede ser perfecto, pero si la description es vaga, la skill nunca se activará. Dedica el doble de tiempo a este campo.
✨ Escribir buenas descriptions
Una buena description tiene dos partes: una frase que resume lo que hace la skill, seguida de frases desencadenantes concretas con las variaciones de solicitud que el usuario podría hacer. Cuantos más sinónimos y variaciones, mayor será la cobertura semántica.
video-explicativoCrea videos explicativos completos en PT-BR (HTML→MP4 mediante HyperFrames) a partir de un tema: guion, narración TTS local, escenas animadas dark premium, captions y CTA de INEMA.CLUB, en formatos 16:9 (YouTube) y 9:16 (Shorts/Reels).
Especifica la salida (videos en PT-BR), el mecanismo (HTML→MP4) y los subproductos (guion, TTS, captions, CTA).
Usa cuando el usuario pida "hacer un video", "video explicativo", "video sobre X", "video para Shorts/Reels", "minitutorial en video", "video de INEMA" o cuando dé un tema y quiera un video narrado listo.
Son citas literales de cómo lo pediría el usuario, con comillas, variaciones de lenguaje y distintos casos de uso.
- ✓ Incluye frases que el usuario escribe literalmente
- ✓ Tiene sinónimos: "video", "tutorial en video", "mini video"
- ✓ Cubre variaciones de canal: YouTube, Shorts, Reels
- ✓ Menciona el resultado concreto: MP4, narración, captions
- ✓ Usa «Úsala cuando el usuario pida X, Y, Z»
- ✗ "Crea videos." — demasiado vago, sin disparadores
- ✗ Solo explica el «cómo», no el «cuándo usarlo»
- ✗ Usa jerga técnica que el usuario nunca escribiría
- ✗ No enumera las posibles variaciones del pedido
- ✗ Una sola línea — cobertura semántica mínima
Por cada frase de activación que escribas, pregúntate: "Un usuario real, sin saber que esta skill existe, ¿escribiría esta frase?" Si la respuesta es sí, es un buen disparador. Las palabras técnicas internas del sistema son pésimos disparadores.
📄 Cuerpo en Markdown
Todo lo que viene después del segundo --- es el cuerpo de la skill. Es un documento Markdown común que describe, paso a paso, lo que Claude debe hacer cuando se activa la skill. Claude lo lee y lo ejecuta literalmente.
El cuerpo del SKILL.md es el script de ejecución de Claude. Si la description es el activador, el cuerpo es la instrucción de operación. Claude sigue el cuerpo como una lista de verificación: lee, entiende y ejecuta cada paso en orden.
# 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⚠️ Errores comunes en SKILL.md
Pequeños descuidos en SKILL.md causan fallas silenciosas: la skill no carga, no se activa o se activa en el momento equivocado. Conoce los errores más frecuentes y cómo evitarlos antes de publicar tu skill.
La causa más común es el frontmatter mal formado. Verifica siempre: el archivo empieza con --- en la primera línea (sin espacios antes) y hay un segundo --- de cierre.
name: meu-skill
description: Faz coisas...
# Corpo aquiSin los delimitadores ---, el harness ignora el frontmatter.
---
name: meu-skill
description: Faz coisas...
---
# Corpo aquiAmbos --- obligatorios, cada uno en su propia línea.
---
name: meu-skill
description: Texto longo
que continua aqui
sem indentação
---Una línea sin sangría rompe el YAML multilínea: el parser la interpreta como un campo nuevo.
---
name: meu-skill
description: Texto longo
que continua aqui
com 2 espaços de indentação
---Las líneas de continuación deben tener al menos 2 espacios de sangría.
---
name: video-explicativo
description: Cria vídeos.
---Sin frases disparadoras concretas, Claude rara vez hace la correspondencia semántica correcta.
---
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".
---Las frases desencadenantes entre comillas aumentan drásticamente la coincidencia.
- ✓ El archivo comienza con
---en la línea 1 (sin BOM ni espacios) - ✓ Segundo
---presente después de los campos YAML - ✓
nameigual al nombre de la carpeta (kebab-case) - ✓
descriptiontiene al menos 3 frases concretas que activan su uso - ✓ Líneas de continuación de description con sangría de 2 espacios
✅ Resumen del Módulo 1.2
Qué aprendiste en este módulo
--- y contiene name + description
name debe estar en kebab-case y ser idéntico al nombre de la carpeta del skill
description es el disparador de activación: Claude lee este campo para decidir cuándo invocar la skill
---) es el script de ejecución que Claude sigue paso a paso
--- faltante, indentación YAML incorrecta, descripción vaga sin frases que activen
Aprende exactamente cómo estructurar el cuerpo del SKILL.md en capas de profundidad, desde el uso básico hasta los casos avanzados, para que Claude ejecute la skill con precisión en cualquier contexto.