Cómo escribir un SKILL.md para Claude Code

Una skill es una carpeta con un archivo de texto. Casi todo el trabajo está en las dos primeras líneas, porque así decide Claude si la usa.

Dónde va

Una carpeta por skill, con un SKILL.md dentro. Las personales viven en ~/.claude/skills/<nombre>/SKILL.md; las de un solo proyecto, en .claude/skills/<nombre>/SKILL.md dentro de ese proyecto. Reinicia la sesión tras añadir una.

Las dos líneas que importan

---
name: session-handoff
description: Use when the user ends a session. Writes a HANDOFF.md.
---

El name es el nombre de la carpeta. La description es lo que Claude lee para decidir si la skill aplica, así que escríbela como un disparador, no como un título. Di cuándo usarla y luego qué hace. Compara:

• Floja: «Ayuda con notas.» Encaja con todo y con nada.
• Mejor: «Úsala cuando el usuario cierre una sesión o pida una nota de relevo. Escribe HANDOFF.md con la salida real de git.»

La descripción puede ir en el idioma que uses con Claude; lo importante es que diga cuándo se activa.

El cuerpo: pasos, un ejemplo y cuándo no usarla

1. Una frase de objetivo y una línea sobre cuándo no usarla.
2. Pasos numerados en el orden en que ocurren, con el verbo primero: «Ejecuta git status --short», no «Es útil revisar el estado».
3. Un ejemplo real: una entrada y la salida que quieres. Enseña más que un párrafo de reglas.
4. Una comprobación al final: qué confirma el agente antes de decir que ha terminado.

Que sea corta. Las nuestras van de 15 a 48 líneas. Si una skill necesita más, pon el razonamiento en otro archivo a su lado (usamos un WHY.md breve) y deja el SKILL.md solo con los pasos.

Pruébala antes de fiarte

1. Debe activarse: abre una sesión nueva y pide la tarea con palabras normales, sin nombrar la skill. Mira si sigue los pasos.
2. No debe activarse: pide algo parecido que no cubre. Si salta igualmente, afina la descripción.
3. Léela como un desconocido. Cualquier paso que necesite tu memoria para entenderse fallará en otra sesión.
4. Busca secretos. Claves, rutas con tu nombre y nombres de proyectos privados no van en un archivo que compartes.

Errores comunes

• Una descripción que dice qué es la skill, no cuándo usarla.
• Reglas sin ejemplo, así que el agente adivina el formato.
• Tres objetivos en una skill. Divídela.
• Sin regla de parada en nada que repita o busque.

Ejemplos para leer

Tres skills pequeñas con este estilo, licencia MIT, gratis para copiar: loop-stop, session-handoff y ask-before-building. Las probamos a mano en nuestros proyectos; no las hemos medido con el flujo de otras personas.