Las skills de Claude Code resuelven un problema con el que todo usuario intensivo termina chocando: sigues pegando la misma checklist, procedimiento o reglas de la casa en el chat, o una sección de tu CLAUDE.md creció en silencio hasta volverse un manual que el modelo lee a medias en cada petición. Una skill empaqueta esas instrucciones en un archivo que el agente carga bajo demanda: puedes invocarla con un slash command, o Claude puede cargarla por sí mismo cuando decide que es relevante.
Esta guía cubre cómo escribir una Skill de Claude Code desde cero: el formato exacto de SKILL.md, los campos de frontmatter que importan, por qué el campo description decide si tu skill llega a dispararse, y los errores que convierten a las skills en peso muerto. Cada afirmación mecánica de abajo viene de la documentación oficial de Claude Code de Anthropic; la guía de calidad viene de lo que aprendimos construyendo el generador gratuito de skills de Claude Code de PromptArch y nuestro linter de archivos de contexto.
Qué es una skill y cuándo conviene usarla
Una skill es un directorio que contiene un archivo SKILL.md. El archivo tiene dos partes: frontmatter YAML entre marcadores --- que le dice a Claude cuándo usar la skill, y un cuerpo en markdown con las instrucciones que Claude sigue cuando la skill corre. El nombre del directorio se convierte en el comando que escribes (.claude/skills/migration-review/SKILL.md te da /migration-review), y la descripción ayuda a Claude a decidir cuándo cargarla por su cuenta.
La decisión entre una skill y otras superficies de configuración se reduce al comportamiento de carga:
- CLAUDE.md está siempre activo. Cada línea ocupa contexto en cada petición, sea relevante o no. Debe contener hechos duraderos: arquitectura, convenciones, comandos, restricciones. Si quieres un punto de partida, PromptArch tiene un generador de CLAUDE.md gratuito.
- Una skill es bajo demanda. Solo su descripción corta está siempre en contexto; el cuerpo se carga cuando la skill se invoca. La regla práctica de la propia Anthropic: crea una skill cuando sigues pegando las mismas instrucciones en el chat, o cuando una sección de CLAUDE.md creció hasta volverse un procedimiento en lugar de un hecho. El material de referencia largo dentro de una skill no cuesta casi nada hasta que lo necesitas.
- Los slash commands ahora son skills. Los comandos personalizados se fusionaron con el sistema de skills: un archivo en
.claude/commands/deploy.mdy una skill en.claude/skills/deploy/SKILL.mdcrean ambos/deployy funcionan igual. Las skills son la forma recomendada porque agregan un directorio para archivos de apoyo, frontmatter para controlar quién las invoca, y carga automática disparada por el modelo.
Dónde guardas la skill decide su alcance: ~/.claude/skills/<name>/SKILL.md es personal (todos tus proyectos), .claude/skills/<name>/SKILL.md es de proyecto (commiteada al repo, compartida con tu equipo), y los plugins pueden empaquetar skills bajo su propio namespace.
Anatomía: un SKILL.md completo
Aquí hay una skill de proyecto realista que revisa migraciones de base de datos nuevas. Guárdala en .claude/skills/migration-review/SKILL.md:
---
name: migration-review
description: Reviews a SQL migration for destructive operations, lock risk,
and rollback safety. Use when the user adds or edits a migration file,
asks to review a migration, or mentions ALTER TABLE, DROP COLUMN,
backfills, or "is this migration safe".
allowed-tools: Read Grep
---
# Migration review
Review the migration $ARGUMENTS against this checklist:
1. Flag destructive operations (DROP TABLE, DROP COLUMN, TRUNCATE) and
confirm a backup or archival step exists before them.
2. Check long-running statements: adding a NOT NULL column with a default
on a large table, or an index built without CONCURRENTLY, locks writes.
3. Verify new foreign keys have a supporting index on the referencing side.
4. Confirm the migration is reversible, or that the PR notes why it is not.
5. Check RLS: any new table needs policies before it ships, because our
API reads it through the anon client.
Report findings as a short list ordered by severity. If everything passes,
say so in one line.
Las piezas:
- Frontmatter. Todos los campos son opcionales; solo
descriptiones recomendado, porque es lo que Claude lee para decidir cuándo aplicar la skill.namees solo la etiqueta visible en los listados (el nombre del comando viene del directorio).allowed-toolspreaprueba herramientas durante el turno que invoca la skill, para que Claude no se detenga a pedir permiso. - Cuerpo. Instrucciones en markdown plano.
$ARGUMENTSse reemplaza con lo que sigue al nombre de la skill cuando escribes/migration-review supabase/migrations/039_foo.sql; si el placeholder no está, Claude Code agrega tu texto al final. - Extras útiles.
disable-model-invocation: truehace la skill solo manual (correcto para flujos tipo/deploycon efectos secundarios).user-invocable: falsela oculta del menú/, para conocimiento de fondo que no es una acción con sentido.context: forkcorre la skill en un subagente aislado. Y una línea con!seguida de un comando de shell entre backticks corre antes de que Claude vea el contenido, inyectando salida en vivo (un diff, una lista de archivos) en el prompt.
La descripción es el campo decisivo
Este es el modelo mental que separa las skills que se disparan de las que se pudren: la descripción es un router, y Claude es el motor de ruteo. En una sesión normal, Claude ve un listado con el nombre y la descripción de cada skill. Cuando llega tu petición, compara tus palabras contra esas descripciones y decide qué skill cargar, si alguna. El cuerpo de tu skill, por bueno que sea, es invisible al momento de rutear.
Eso tiene tres consecuencias prácticas:
- Di qué hace la skill Y cuándo usarla. "Revisa migraciones SQL" es media descripción. La mitad de disparo ("usar cuando el usuario agrega un archivo de migración, pide revisar una migración o menciona ALTER TABLE...") es lo que realmente se compara.
- Cubre las frases que la gente escribe de verdad. Incluye el vocabulario de la petición, no el vocabulario de la solución. Los usuarios dicen "¿es segura esta migración?", no "realiza un análisis de riesgo de locks". Si la descripción no contiene sus palabras, la skill nunca se activa, y concluirás erróneamente que las skills no funcionan.
- Pon el caso de uso clave primero. El texto combinado de
descriptionmáswhen_to_usese trunca a 1.536 caracteres en el listado de skills, y con muchas skills instaladas el listado mismo tiene un presupuesto de contexto, así que adelanta la frase que importa. El campo opcionalwhen_to_useexiste precisamente para guía de activación extendida: peticiones de ejemplo y formulaciones que deberían activar la skill.
Una salvedad: poner disable-model-invocation: true quita la descripción del contexto por completo. Ese es el punto (Claude no puede dispararla), pero significa que todo este consejo de ruteo aplica solo a skills que Claude tiene permitido invocar.
Divulgación progresiva: mantén el cuerpo liviano
Las skills son baratas hasta que se cargan. Las descripciones están siempre en contexto; el cuerpo completo entra a la conversación solo cuando la skill se invoca. Pero una vez invocado, el cuerpo renderizado se queda en contexto por el resto de la sesión, así que cada línea es un costo recurrente de tokens. De ahí siguen dos reglas:
- Di qué hacer, no por qué. Aplica la misma prueba de concisión que aplicarías a CLAUDE.md. El consejo de Anthropic: mantén SKILL.md por debajo de 500 líneas.
- Empuja el volumen a archivos de apoyo. El directorio de una skill puede contener
reference.md,examples.md, plantillas o scripts ejecutables junto a SKILL.md. Referéncialos desde el cuerpo ("para los detalles completos de la API, ver reference.md") y Claude los lee solo cuando hace falta. Esa es la segunda capa de divulgación progresiva: descripción siempre, cuerpo al invocar, archivos de apoyo bajo demanda.
Qué va en una skill y qué no
Buen material para una skill: flujos de varios pasos (release, deploy, triage), checklists de revisión, procedimientos específicos del repo ("cómo escribimos migraciones", "cómo armamos un changelog") y material de referencia profundo detrás de un SKILL.md delgado. En resumen: procedimientos y playbooks.
Mal material para una skill: hechos duraderos sobre el codebase (eso es CLAUDE.md), cosas que quieres imponer de forma determinista en cada edición (eso son hooks), políticas de permisos (eso es settings) y prompts de una sola vez que nunca reutilizarás. La mala ubicación más común es la duplicación: las mismas reglas viviendo en CLAUDE.md y en una skill a la vez. Se desincronizan con el tiempo, y pagas la copia de CLAUDE.md en absolutamente cada petición.
Errores comunes
- Descripciones vagas que nunca disparan. "Ayuda con cosas de base de datos" no rutea nada. Es la razón número uno por la que las skills quedan sin uso.
- Skills que duplican CLAUDE.md. Si es un hecho que el agente necesita constantemente, va en CLAUDE.md una sola vez. Si es un procedimiento, sácalo de CLAUDE.md por completo y muévelo a la skill.
- Cuerpos gigantes. Un SKILL.md de 900 líneas derrota la divulgación progresiva; tras una invocación es un impuesto permanente sobre la sesión.
- Efectos secundarios auto-disparables. Si una skill despliega, hace commits o le escribe a gente, agrega
disable-model-invocation: true. Quieres escribir/deploydeliberadamente, no que Claude decida que tu código se ve listo. - Anti-patrones dentro del cuerpo. Los cuerpos de skill son instrucciones para un agente, así que las mismas reglas respaldadas por investigación que aplican a CLAUDE.md aplican aquí: la inflación de énfasis (muros de MUST/NEVER/CRITICAL), las frases evasivas tipo "try to... if possible" que se leen como opcionales, y las prohibiciones sin razón ni alternativa degradan de forma medible a los modelos actuales. Nuestro linter las marca (
antipattern/emphasis-inflation,antipattern/weak-language,antipattern/bare-prohibitiony unas 30 más); pega el cuerpo de tu skill en lint para un chequeo gratuito y offline, y mira la lista completa de reglas con sus fuentes.
Prueba el disparo y luego la salida
Ver que una skill se dispara te dice que Claude la encontró, no que hizo lo que pretendías, así que mide las dos cosas por separado:
- Confiabilidad del disparo. En una sesión nueva (el contexto sobrante de cuando la escribiste enmascara los huecos), escribe algunas peticiones realistas que deberían activar la skill y algunas que no. Si se sub-activa, agrega las frases faltantes a la descripción o a
when_to_use. Si se sobre-activa, haz la descripción más específica o pásala a solo manual. - Invocación directa como control.
/skill-namesiempre funciona para skills invocables por el usuario, y preguntar "What skills are available?" confirma que la skill está registrada. Si/skill-namefunciona pero el frontmatter parece ignorado, el sospechoso habitual es YAML mal formado: Claude Code entonces carga el cuerpo con metadatos vacíos, yclaude --debugmuestra el error de parseo. - Calidad de la salida. Corre los mismos prompts con la skill disponible y con ella deshabilitada, y compara. El plugin
skill-creatorde Anthropic automatiza este ciclo con casos de prueba guardados, corridas aisladas, calificación de pasa/falla y ajuste de la descripción.
Itera primero sobre la descripción. Es la línea de mayor palanca de todo el archivo.
Genera una en dos minutos
Puedes escribir un SKILL.md a mano con todo lo de arriba. O puedes hacer que la estructura, el frontmatter, la descripción orientada a disparo y un cuerpo limpio para el linter se generen por ti: el generador gratuito de skills de Claude Code de PromptArch te guía por nombre, descripción, disparadores, permisos de herramientas y pasos del flujo, y produce un SKILL.md listo para guardar. La primera es gratis, sin registro. Después pásala por lint y súbela al .claude/skills/ de tu repo.