Qué son los skills de Claude Code y para qué sirven

Si llevas unos meses usando IA para trabajar, probablemente tengas un documento —o una nota, o un chat marcado como favorito— donde guardas los prompts que sí funcionan. El de resumir reuniones. El de revisar código. El que te escribe la descripción de una vacante sin que suene a plantilla de 2015.

Ese documento es el síntoma de un problema: el conocimiento sobre cómo pedirle las cosas a la IA está fuera de la herramienta. Cada vez que lo necesitas tienes que acordarte de que existe, buscarlo, copiarlo y adaptarlo. Los skills existen para resolver exactamente eso.

Qué es exactamente un skill

Un skill es una carpeta con un archivo llamado SKILL.md dentro. Ese archivo tiene dos partes: una cabecera con el nombre y una descripción de cuándo debe usarse, y debajo las instrucciones en Markdown normal.

~/.claude/skills/
└── revisar-pr/
    └── SKILL.md

Y el contenido, simplificado:

---
name: revisar-pr
description: Revisa un pull request buscando bugs, casos
  no cubiertos por tests y cambios que rompan la API pública.
  Úsalo cuando el usuario pida revisar código o un PR.
---

# Revisión de pull request

## Qué mirar, en este orden
1. Correctitud: ¿el cambio hace lo que dice el título?
2. Casos límite: nulos, listas vacías, fallos de red.
3. Contrato público: ¿rompe algo que otros consumen?

## Cómo reportar
Agrupa por severidad. Cada hallazgo con archivo:línea
y un escenario concreto de fallo, no una opinión.
Si no hay nada, dilo en una línea y termina.

Eso es todo. No hay código, no hay configuración, no hay instalador. Es un procedimiento escrito, guardado en un sitio donde el asistente puede encontrarlo.

Prompt, skill y plugin: las diferencias

Los tres términos se usan como sinónimos y no lo son. La diferencia práctica está en quién se acuerda de usarlos y qué pueden hacer.

La regla que uso: si he pegado el mismo texto tres veces, deja de ser un prompt y se convierte en un skill. Si el skill necesita además ejecutar scripts, engancharse a un evento o venir acompañado de otros, entonces hablamos de plugin.

Cómo decide Claude que debe usar un skill

Aquí está la parte que casi nadie explica bien, y la que determina si tu skill se usará o quedará muerto en el disco.

El asistente no lee todos tus skills en cada mensaje: eso llenaría el contexto de ruido. Lo que lee es la descripción de cada uno. Con esa lista corta decide si alguna encaja con lo que le estás pidiendo y, solo entonces, carga el contenido completo de ese skill.

La consecuencia es directa: la descripción no es documentación, es el mecanismo de activación. Estas dos descripciones producen resultados muy distintos:

• Mala: «Herramienta de revisión de código.» Describe qué es, no cuándo usarla. El modelo no tiene con qué comparar tu petición.
• Buena: «Revisa un pull request buscando bugs y casos sin tests. Úsalo cuando el usuario pida revisar código, un PR, un diff o diga que algo "está raro" en un cambio.» Incluye las palabras que la persona va a escribir de verdad.

Escribe la descripción pensando en las frases que dirás tú, no en el nombre técnico de la tarea. Si tu equipo dice «pásale un ojo a esto», que esa frase aparezca.

Dónde se instalan y quién los ve

Hay dos ubicaciones y la elección tiene consecuencias sociales, no técnicas:

• ~/.claude/skills/ — tus skills personales. Están en todos tus proyectos y no los ve nadie más. Aquí van tus manías: cómo quieres los mensajes de commit, cómo prefieres que te resuma un documento.
• .claude/skills/ dentro del repositorio — skills del proyecto. Se versionan con el código y los tiene todo el que clone. Aquí van las convenciones del equipo: cómo se escriben los tests en esta casa, qué hay que revisar antes de tocar el módulo de facturación.

El segundo caso es el que cambia cómo trabaja un equipo. Una convención que vive en la cabeza de dos personas se pierde en cuanto una se va de vacaciones. La misma convención escrita en un skill del repositorio la aplica cualquiera, incluido el que entró la semana pasada.

Cuándo merece la pena convertir un prompt en skill

No todo merece un skill. Estas cuatro señales indican que sí:

1. Lo repites. Tres veces es el umbral razonable.
2. El resultado varía sin que quieras. Si cada vez que pides lo mismo obtienes un formato distinto, lo que falta es un procedimiento fijo.
3. Tiene criterio, no solo formato. «Ponlo en tabla» no necesita un skill. «Prioriza por impacto en ingresos y descarta lo que no se pueda medir en un trimestre» sí: es una decisión que quieres que se tome siempre igual.
4. Otra persona debería poder hacerlo igual que tú. El skill es la forma más barata de documentar cómo se hace algo bien.

Los cinco errores que más se repiten

1. Descripción vaga. El skill nunca se activa y acabas invocándolo a mano, lo que anula su ventaja.
2. Meterlo todo en un skill. Un skill que hace revisión de código, generación de tests y redacción de changelog no hace bien ninguna de las tres. Uno por tarea.
3. Escribir un ensayo. Las instrucciones se compilan mentalmente cada vez que se cargan. Sé imperativo: pasos, criterios, formato de salida. Fuera la introducción y las justificaciones.
4. No decir cuándo no aplicarlo. Una línea de «no lo uses si…» evita la mitad de las activaciones equivocadas.
5. No fijar el formato de salida. Si no dices cómo quieres el resultado, cada ejecución te dará una versión distinta y tendrás que reformatear a mano.

Cuando tengas claro esto, el siguiente paso es escribir el tuyo. Lo cubrimos paso a paso en cómo crear un skill para Claude Code, y si lo que necesitas es afinar el texto de las instrucciones, en cómo escribir prompts efectivos.