El problema más común con las skills no es que estén mal escritas: es que Claude no las usa. Para arreglarlo hay que entender cómo las carga, porque el diseño por capas condiciona cómo debes escribirlas.
Las tres capas de una skill
Las skills se apoyan en la llamada divulgación progresiva: Claude no lee todo de golpe, sino lo justo en cada momento.
- Metadatos (siempre presentes). Al empezar, Claude solo ve el
namey ladescriptionde cada skill instalada. Es poco texto por skill, así que puedes tener muchas sin saturar el contexto. - Instrucciones (cuando se activa). Si la petición encaja con la descripción, Claude lee el cuerpo del
SKILL.md. - Recursos (bajo demanda). Plantillas, guías de referencia y scripts adicionales solo se abren si las instrucciones lo piden y la tarea los necesita.
Anatomía de una buena descripción
Una descripción eficaz responde a tres preguntas en una o dos frases: qué hace, qué produce y cuándo usarla (con las palabras que usaría una persona real).
Mala: «Ayuda con presentaciones.»
Buena: «Crea presentaciones de ventas de 8-12 diapositivas en el formato de la empresa a partir de un briefing o unas notas. Úsala cuando pidan “deck”, “presentación comercial”, “pitch” o “propuesta para cliente”.»
La buena incluye el entregable, el formato, el tipo de insumo y los sinónimos con los que la gente lo pide. Eso es lo que permite el emparejamiento.
Lista de verificación
- ¿Dice qué entrega produce (documento, hoja, código, análisis)?
- ¿Incluye 3-5 frases o palabras clave reales de activación?
- ¿Delimita lo que no cubre, si hay una skill vecina con la que se podría confundir?
- ¿Está en tercera persona y describe la capacidad, no da órdenes al usuario?
- ¿El nombre es corto, en minúsculas y sin ambigüedad?
Cómo depurar una activación fallida
- Pega la petición exacta que falló y pregúntale a Claude qué skills tiene disponibles y cuál elegiría. A menudo te dirá por qué descartó la tuya.
- Reescribe la descripción acercándola a las palabras literales de la petición.
- Si dos skills compiten, añade a cada una una frase de exclusión («no la uses para…»).
- Repite con un conjunto fijo de peticiones de prueba: unas que deben activarla y otras que no.
Cuando una skill crece demasiado
Si el cuerpo supera unos cientos de líneas o cubre varios flujos, divídelo: deja en SKILL.md el recorrido principal y enlaza ficheros de referencia (referencia/precios.md, referencia/errores.md) con una línea que explique cuándo abrirlos. Así pagas el coste de leer cada parte solo cuando la tarea la necesita.