📁 Anatomía: carpeta + SKILL.md
Una skill es fundamentalmente una carpeta — no es solo un archivo. El nombre de la carpeta es el identificador de la skill; el archivo SKILL.md es el cerebro. Todo lo que existe dentro de esta carpeta sirve a la skill.
✓ Estructura correcta
- ✓
~/.claude/skills/minha-skill/SKILL.md - ✓Carpeta en kebab-case, SKILL.md en la raíz
- ✓Subcarpetas scripts/ y references/ opcionales
- ✓Cada archivo con una responsabilidad clara
✗ Errores comunes
- ✗SKILL.md suelto en ~/.claude/ sin carpeta
- ✗Carpeta con espacios o camelCase en el nombre
- ✗Todo mezclado en un SKILL.md gigante
- ✗Scripts incluidos en el markdown en lugar de archivos
📄 Frontmatter YAML
El frontmatter es el bloque YAML entre los delimitadores --- en la parte superior del SKILL.md. Aquí declaras la identidad de la skill y cómo debe activarse.
---
name: formato-curso
description: |-
Template e padrões de design para criar páginas HTML
de cursos no formato INEMA.CLUB.
Use esta skill SEMPRE que o usuário pedir para criar,
editar ou revisar páginas HTML de curso — incluindo
index de trilhas, páginas de módulos, componentes.
SKIP: páginas web genéricas sem contexto de curso INEMA.CLUB.
---
# Formato Curso - INEMA.CLUB
# (corpo do SKILL.md começa aqui)💡 Consejo: el campo name = identificador
O name en el frontmatter debe ser idéntico al nombre de la carpeta. Esto crea coherencia: la carpeta formato-curso/ contiene un SKILL.md con name: formato-curso. El agente usa ese nombre para referirse a ella en los logs e invocarla mediante /formato-curso.
✓ Frontmatter válido
- ✓Delimitadores
---al principio y al final - ✓Indentación con 2 espacios (nunca tabulaciones)
- ✓Campos
nameedescriptionpresentes - ✓Description en lenguaje natural y claro
✗ Frontmatter inválido
- ✗YAML con tabulaciones en lugar de espacios
- ✗Falta de
---de cierre - ✗Description vacía o de 1 palabra
- ✗Campos adicionales no reconocidos (sin efecto)
📝 Cuerpo en Markdown
Después del frontmatter, el cuerpo del SKILL.md es Markdown puro. Aquí programas el comportamiento real de la skill: qué hacer, en qué orden y qué nunca hacer.
# Nome da Skill
Parágrafo de contexto curto — o que esta skill faz.
## Referências
Sempre leia estes arquivos antes de agir:
1. **`references/MASTER.md`** — Templates completos
2. **`references/CHECKLIST.md`** — Verificação final
## Fluxo de Trabalho
1. Entender o que será criado
2. Ler referências relevantes
3. Criar seguindo os templates
4. Verificar com o checklist
## Hard Rules
- **NUNCA** usar seta ▶ em tópicos (usar número em círculo)
- **SEMPRE** incluir INEMA.CLUB em todas as páginas
- **JAMAIS** simplificar o nav para páginas internasSecciones recomendadas en el cuerpo
Contexto / Referencias
Lista de archivos que el agente debe leer antes de actuar. Enlace a la documentación detallada en references/.
Flujo de trabajo
Pasos numerados que el agente ejecuta en orden. Incluye puntos de confirmación antes de acciones costosas.
Errores críticos / reglas estrictas
Reglas inviolables en MAYÚSCULAS. Lo que NUNCA debes hacer. Protege contra los errores más costosos e irreversibles.
Tablas de referencia rápida
Tablas de decisión, mapeos de colores, listas de componentes. Información densa en un formato fácil de explorar.
💡 Tamaño ideal del SKILL.md
El SKILL.md se lee por completo en cada activación. 50–150 líneas es el punto ideal: lo bastante denso para programar el comportamiento y lo bastante conciso para no desperdiciar tokens. El contenido más extenso va en references/.
🗂️ Dónde están las skills
Las skills pueden existir en dos ámbitos: global (disponible en todos los proyectos) o local (restringido al proyecto actual). La elección depende de qué tan específica sea la skill.
🗺️ Mapa de ubicación
Global (~/.claude/skills/)
Skills utilitarias reutilizables en cualquier proyecto. Ejemplos: formato-curso, n8n-code-python, claude-api.
└── skills/
├── formato-curso/
├── n8n-code-python/
└── ads-skill/
Local (.claude/skills/)
Skills específicas del proyecto actual. No aparecen en otros repositorios. Ejemplo: una skill con la lógica de negocio del cliente.
└── .claude/
└── skills/
└── projeto-especifico/
📊 Regla de precedencia
Cuando existe una skill con el mismo nombre en ambos ámbitos, la local sobrescribe la global. Esto permite que proyectos específicos personalicen el comportamiento de una skill global sin modificar la original.
✓ Usa global cuando
- ✓La skill es útil en varios proyectos
- ✓No contiene datos sensibles de clientes
- ✓Es una utilidad genérica (formateador, analizador)
✓ Usa local cuando
- ✓Contiene lógica de negocio específica
- ✓Hace referencia a APIs privadas del proyecto
- ✓Debe versionarse junto con el código
🔍 Cómo el agente descubre y activa
El proceso de descubrimiento y activación ocurre en dos fases: descubrimiento pasivo (al iniciar) y activación activa (cuando el mensaje sea relevante).
💡 Carga diferida: ahorro de tokens
El agente NO lee el cuerpo completo de todas las skills en cada sesión. Solo se inyectan los metadatos (name + description). El cuerpo completo se carga solamente cuando se activa la skill. Esto mantiene el contexto ligero incluso con decenas de skills instaladas.
⚖️ Skill vs. prompt vs. comando
Tres herramientas, tres propósitos. Elegir la equivocada no rompe nada, pero elegir la correcta te ahorra horas.
Tabla comparativa
| Criterio | Skill | Prompt | Comando |
|---|---|---|---|
| Persistencia | Permanente (archivo) | Stateless | Guardado en config |
| Complejidad | Varias etapas, scripts | Instrucción puntual | Atajo de prompt |
| Reglas estrictas | Sí (reglas estrictas) | No | No |
| Archivos auxiliares | Sí (scripts/, refs/) | No | No |
| Mejor para | Workflows complejos | Tareas puntuales | Atajos rápidos |
💡 Regla de oro
Si vas a repetir el mismo conjunto de pasos más de 3 veces, crea una skill. Si es algo puntual y específico, usa un prompt inline. Si es un atajo para un prompt que escribes con frecuencia, crea un comando slash.
🧩 Resumen del módulo
Siguiente módulo:
3.2 — Description y triggers: cómo escribir el campo description que hace que la skill se active en el momento adecuado