Cómo crear una skill en Claude Code, paso a paso
Una Claude Skill es una carpeta dentro de .claude/skills/ con un archivo SKILL.md que define un nombre, una descripción y un prompt de sistema. El modelo lee la descripción al iniciar la sesión y activa la skill por su cuenta cuando una tarea la requiere. Son la forma de empaquetar capacidades repetibles (formatear PRs, generar release notes, adaptar un mensaje a varias redes) para que Claude Code las aplique de manera consistente.
La pieza clave es la descripción. Es lo que el modelo lee para decidir si activa la skill ante cada tarea. Una descripción genérica ("formatea PRs") no se activa bien; una específica que enumere las frases que la deben disparar, sí.
¿Qué es una skill y en qué se diferencia?
Una skill se ejecuta en el contexto principal (a diferencia de un subagente, que corre aislado) y carga sus archivos auxiliares bajo demanda (a diferencia de un slash command, que carga todo cada vez). Esa carga progresiva, el Progressive Disclosure, es su valor diferencial.
| Slash command | Skill | Subagente | |
|---|---|---|---|
| Activación | La invocas tú (/comando) |
El modelo la activa por descripción (o /nombre) |
El modelo o tú (@nombre) |
| Contexto | Principal | Principal | Aislado, descartable |
| Archivos | Un solo prompt | SKILL.md + N referencias bajo demanda |
Un solo archivo |
La estructura de una skill
La mínima es una carpeta con un SKILL.md:
.claude/skills/
└── pr-formatter/
└── SKILL.md
Pero brillan cuando crecen a paquetes con referencias que se cargan solo cuando aplican:
.claude/skills/
└── pr-formatter/
├── SKILL.md # único que se carga al inicio
├── examples.md # se carga bajo demanda
└── reference/
└── estilo.md
Solo SKILL.md se carga al arrancar. Si tu proyecto es TypeScript, la skill no carga la referencia de Python. Eso es Progressive Disclosure.
Crear una skill, paso a paso
1. Crea la carpeta y el archivo:
mkdir -p .claude/skills/pr-formatter
2. Escribe el SKILL.md con frontmatter (nombre + descripción) y el prompt de sistema:
---
name: pr-formatter
description: Usar cuando el usuario pida generar, formatear o
estandarizar un pull request. Produce el formato del proyecto con
secciones de contexto, cambios, riesgos y testing. Activar también
ante "arma el PR", "prepárame el PR".
---
# PR Formatter
Tu rol es producir descripciones de pull request consistentes.
## Estructura obligatoria
1. Contexto (prosa, 2-3 frases)
2. Cambios principales (máximo 7 bullets)
3. Riesgos
4. Testing
3. Añade referencias para Progressive Disclosure (opcional): un examples.md con ejemplos que el modelo cargue solo cuando la tarea lo pida.
4. Verifica que el modelo la detecta: en una sesión limpia, pregunta "¿qué skills tengo disponibles?" y comprueba que aparece.
5. Pruébala de tres formas: activación automática (pide el output sin nombrar la skill), explícita (/pr-formatter) y forzando la carga de una referencia.
Cómo se activan las skills
- Automática: el modelo lee las descripciones al iniciar y activa la skill cuando la tarea encaja. Es la novedad respecto a los slash commands.
- Explícita: la invocas con
/nombre-skill, igual que un slash command (de hecho, son el mismo sistema fusionado). - En lenguaje natural: "usa la skill de code review".
Las skills no se invocan con @ (eso es de los subagentes).
Los errores más comunes
- Descripción genérica. Es lo que decide la activación. Enumera el dominio, las frases que la disparan y qué problema resuelve.
- Meter todo en
SKILL.md. Si pasa de unos cientos de líneas, parte las referencias a archivos hermanos. Progressive Disclosure es el punto. - Confundirla con un subagente. Si quieres conservar el contexto del trabajo en la sesión principal para hacer follow-ups, es skill. Si solo te importa el output y quieres descartar el resto, es subagente.
Preguntas frecuentes
¿Qué es una skill en Claude Code?
Una skill es una carpeta en .claude/skills/ con al menos un SKILL.md que define nombre, descripción y prompt de sistema. El modelo lee la descripción al iniciar la sesión y activa la skill cuando una tarea encaja. Sirve para empaquetar capacidades repetibles con outputs consistentes.
¿Cómo se crea una skill en Claude Code?
Creas la carpeta .claude/skills/<nombre>/, escribes un SKILL.md con frontmatter (name y description) y el prompt de la capacidad, y opcionalmente añades archivos de referencia que se cargan bajo demanda. Luego verificas que el modelo la detecta preguntando qué skills hay disponibles.
¿Qué es el Progressive Disclosure en las skills?
Es la carga bajo demanda de los archivos auxiliares de una skill: solo SKILL.md se carga al iniciar, y las referencias (ejemplos, plantillas) se traen cuando la tarea concreta las necesita. Mantiene el contexto limpio.
¿Cuál es la diferencia entre una skill y un subagente?
Una skill corre en el contexto principal y conserva la conversación para follow-ups; un subagente corre en un contexto aislado que se descarta y solo devuelve el resultado. Skill para tareas plantilla con outputs consistentes; subagente para trabajo pesado que consume mucho contexto.
Recursos relacionados
- Skills, hooks y MCP: las tres capas para extender Claude Code.
- Subagentes en Claude Code: la alternativa para tareas que conviene aislar.
- Cómo dominar Claude Code: la guía completa.
Tu siguiente paso
Los comandos de skills y decenas más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).