🧱 Estructura general
Un SKILL.md tiene exactamente dos partes. En la parte superior, un bloque de frontmatter YAML entre dos delimitadores ---. Justo debajo, el cuerpo en Markdown con las instrucciones de comportamiento. Esa separación es lo que todo agente compatible espera encontrar.
Esqueleto de un SKILL.md:
--- name: nome-da-skill description: Lo que hace y cuándo usarla. --- # Título de la Skill Instrucciones en Markdown que el agente sigue cuando se activa la skill.
💡 Consejo
El frontmatter tiene solo dos campos obligatorios: name e description. Todo lo demás (license, allowed-tools, etc.) es opcional. Empieza siempre por estos dos.
🏷️ Campo name
O name es el identificador único de la skill. Convención fija: kebab-case (palabras separadas por guiones), todo en minúsculas, y normalmente igual al nombre de la carpeta que contiene el SKILL.md.
✗ name mal formado
- ✗Frontend_Design
- ✗mi skill
- ✗ReactBestPractices
- ✗skill (demasiado genérica)
✓ nombre correcto
- ✓frontend-design
- ✓react-best-practices
- ✓skill-creator
- ✓supabase-postgres-best-practices
Por qué importa kebab-case
El name se usa en comandos, logs y como clave única en el agente. Los espacios y las mayúsculas rompen la referencia, y los nombres genéricos como skill entran en conflicto con otras instalaciones. Las skills más instaladas de skills.sh — find-skills (1,8M), frontend-design (488k) — todas siguen el patrón.
🎣 Campo description: el disparador
A description es el campo más importante del archivo. Es la frase que el agente lee para decidir si activa la skill. Una buena description dice dos cosas: QUÉ la skill hace y CUÁNDO usarla — de preferencia con ejemplos concretos de situaciones.
✗ Descripción vaga
"Ayuda con frontend."
No indica cuándo activarla. El agente casi nunca la activará.
✓ Descripción con gatillo
"Crea interfaces frontend. Úsalo cuando el usuario pida construir componentes web, páginas, landing pages..."
Dice qué hace Y enumera situaciones de uso.
Patrón recomendado:
description: <O QUE faz>. Use this skill when <QUANDO usar> (examples include <gatilhos concretos>).
💡 Consejo
La description siempre permanece cargada en el contexto (Nivel 1 de progressive disclosure — consulta el módulo 3.2). Por eso conviene ser específico e incluso un poco insistente: Claude tiende a activar poco las skills.
📝 El cuerpo en Markdown
Debajo del frontmatter viene el cuerpo: las instrucciones de verdad. Escribe en modo imperativo ("Crea", "Usa", "Prefiere"), explica el PORQUÉ en vez de gritar MUSTs en mayúsculas, y muestra patrones de output y ejemplos de cómo debería verse el resultado.
✗ Cuerpo débil
- ✗Lista de MUSTs en MAYÚSCULAS sin contexto
- ✗Reglas sin explicar por qué
- ✗Ningún ejemplo del resultado esperado
- ✗Párrafos largos y genéricos
✓ Contenido eficaz
- ✓Instrucciones imperativas y directas
- ✓Explica el motivo de cada elección
- ✓Muestra ejemplos de buen y mal output
- ✓Secciones cortas con headings claros
Fragmento real del cuerpo de frontend-design:
## Frontend Aesthetics Guidelines Focus on: - **Typography**: Choose fonts that are beautiful, unique... Avoid generic fonts like Arial and Inter. - **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables...
Imperativo + porqué
Fíjate en el ejemplo anterior: cada directriz es un comando ("Focus on", "Choose", "Commit to") seguido del razonamiento. Esto es mucho más eficaz que "TÚ DEBES SIEMPRE...": el agente asimila mejor cuando entiende la intención.
📁 Estructura de carpetas
Una skill profesional no es solo el SKILL.md. A su alrededor, tres carpetas convencionales organizan los recursos, y cada una tiene un propósito claro.
scripts/ — código determinista
Scripts que ejecutan tareas repetibles sin depender del criterio del agente. Se ejecutan sin cargar el código en el contexto: el agente solo los llama y recibe el resultado.
references/ — docs bajo demanda
Documentación extensa que el agente lee solo cuando hace falta. Mantiene breve el SKILL.md y ofrece profundidad cuando se necesita.
assets/ — templates
Archivos de apoyo: plantillas, boilerplates, imágenes y configuraciones que la skill usa o copia al proyecto del usuario.
Estructura típica de una skill:
minha-skill/
├── SKILL.md
├── scripts/
│ └── gerar.py
├── references/
│ └── guia-completo.md
└── assets/
└── template.html
💡 Consejo
No crees carpetas vacías por anticipado. Empieza solo con el SKILL.md y agrega scripts/ o references/ cuando el contenido realmente lo justifique: cada carpeta corresponde al Nivel 3 de la divulgación progresiva.
🔬 Ejemplo mínimo vs. real
Para terminar, compara los extremos. Un SKILL.md mínimo cabe en 5 líneas. En cambio, una skill de producción —como la frontend-design de Anthropic (488.299 instalaciones): incluye en el frontmatter una description con abundantes desencadenantes.
Mínimo:
--- name: git-commit-style description: Formata mensagens de commit no padrão Conventional Commits. --- Sempre escreva commits no formato tipo(escopo): descrição.
Real — frontmatter de anthropics/skills/frontend-design:
--- name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. license: Complete terms in LICENSE.txt ---
Qué enseña el ejemplo real
- •Empieza con QUÉ hace: «Create distinctive, production-grade frontend interfaces».
- •Continúa con CUÁNDO: "Usa esta skill cuando el usuario pida crear...".
- •Lista activadores concretos entre paréntesis: sitios web, páginas de destino, paneles, React.
- •Cierra con el diferencial: "evita la estética genérica de la IA".
✅ Resumen del módulo
Próximo:
3.2 — 🎚️ Progressive disclosure y la description que se activa: los 3 niveles de carga y cómo escribir el disparador perfecto.