Skills de Claude Code: cómo funcionan, SKILL.md y cuándo el agente los carga

Qué son los skills de Claude Code

Un skill (habilidad) es una carpeta con un archivo SKILL.md que contiene la instrucción para un tipo concreto de tarea: cómo desplegar el proyecto, cómo hacer una revisión, cómo sacar una versión. El agente conoce la existencia del skill desde el inicio de la sesión, pero lo lee completo solo cuando la tarea realmente lo requiere.

Los skills de Claude Code resuelven un problema conocido por quien lleva mucho tiempo manteniendo un CLAUDE.md: el archivo de instrucciones crece sin control. Un procedimiento de despliegue de 80 líneas hace falta una vez por semana, pero en el archivo ocupa espacio en el contexto de cada sesión, también cuando solo se corrige una errata en el README. El skill saca estos procedimientos del contexto permanente y los incorpora cuando hacen falta.

De qué se compone un skill

El skill mínimo es una carpeta y un archivo. Los skills de proyecto viven en el repositorio; los personales, en el directorio de inicio del usuario:

.claude/skills/deploy/SKILL.md      # skill del proyecto, compartido por el equipo vía git
~/.claude/skills/review/SKILL.md    # skill personal, disponible en todos los proyectos

Junto a SKILL.md puede colocar archivos auxiliares: plantillas, scripts, documentación de referencia. El agente los abrirá solo si el texto principal del skill los menciona y hacen falta:

.claude/skills/deploy/
├── SKILL.md           # instrucción principal
├── checklist.md       # lista de verificación detallada, se lee por referencia
└── rollback.sh        # script de reversión

Frontmatter: name y description

El archivo empieza con un bloque YAML entre líneas ---. Dos campos son más importantes que los demás: name, el nombre corto del skill, y description, la descripción de lo que hace el skill y de cuándo aplicarlo.

---
name: deploy
description: Despliegue del sitio en el hosting por FTP. Usar cuando haya que subir cambios al servidor, revisar diferencias con el servidor o revertir un despliegue.
---

# Despliegue

1. Primero una prueba en seco: `./deploy.sh -n`.
2. Revisar la lista de archivos: no debe haber secretos ni scripts de prueba.
3. Subir: `./deploy.sh`.
4. Abrir las páginas modificadas y comprobar que responden 200.

La reversión está en rollback.sh dentro de esta carpeta.

Debajo del frontmatter va Markdown normal: pasos, comandos, restricciones, enlaces a los archivos vecinos. Escríbalo como escribiría una instrucción para un compañero nuevo que hace esa tarea por primera vez.

Cuándo el agente carga un skill

Al inicio de la sesión, al contexto llegan solo el nombre y la descripción de cada skill disponible. Son unas pocas líneas por skill, así que se pueden tener decenas. Cuando la petición del usuario o el paso actual del trabajo coincide con la descripción, el agente invoca el skill, y solo entonces entra en el contexto el texto completo de SKILL.md.

De ahí sale la regla práctica principal: el skill se activa por su descripción. El agente no ve el cuerpo del skill hasta que decide abrirlo. Si en description se escribe «Skill auxiliar», el agente no entenderá cuándo hace falta. Si se escribe «Despliegue en el hosting; usar cuando haya que subir cambios al servidor o revertir un despliegue», sí lo entenderá.

Además de la selección automática, el skill se puede invocar de forma explícita por su nombre con una barra, por ejemplo /deploy. Es útil cuando sabe con seguridad qué procedimiento necesita y no quiere depender de que el agente relacione la petición con la descripción.

Cómo escribir description para que el skill se active

• Qué hace: en una frase, con verbo: «Despliegue del sitio», «Revisión de los cambios antes del commit».
• Cuándo usarlo: enumere las formulaciones con las que el usuario pide realmente esta tarea: «sube al servidor», «publica», «revierte».
• Cuándo no usarlo, si el skill es fácil de confundir con otro: «no para desplegar el bot, solo el sitio».
• Evite frases genéricas como «skill útil» o «ayuda en el trabajo»: no aportan señal.

Carga progresiva

Los skills se construyen sobre el principio de carga progresiva (progressive disclosure): la información se entrega por capas, y cada capa siguiente se carga solo cuando hace falta.

Es la misma idea que un router en lugar de un muro de texto en el archivo de instrucciones: un mapa corto siempre a mano, los detalles por referencia. La diferencia es que el skill convierte esa carga en un mecanismo habitual, y no en la esperanza de que el agente abra por sí mismo el documento adecuado. Una ventaja adicional: un script de la tercera capa el agente lo puede ejecutar sin cargar su código entero en el contexto.

Skills, CLAUDE.md y comandos slash: en qué se diferencian

Los tres mecanismos transmiten instrucciones al agente, pero en momentos distintos y con un coste distinto para el contexto.

La regla práctica de elección es sencilla. Si una instrucción hace falta en casi todas las tareas, su lugar es CLAUDE.md. Si hace falta en las tareas de un tipo determinado, es un skill. Si usted mismo escribe cada vez la misma petición larga, es candidato a un comando o a un skill que se invoca a mano.

Las prohibiciones estrictas no las pase al skill. El skill puede no cargarse, y la regla «nunca subir secretos al commit» debe cumplirse siempre. Esos invariantes se quedan en CLAUDE.md y, siempre que sea posible, se refuerzan con mecanismos: hooks, permisos de acceso, comprobaciones en el CI.

Cómo crear un skill para Claude Code: paso a paso

1. Localice un procedimiento repetido. Señal clara: ya ha explicado tres veces al agente lo mismo, o hay una sección en CLAUDE.md que hace falta en una de cada diez tareas.
2. Cree la carpeta .claude/skills/<nombre>/ y dentro el archivo SKILL.md.
3. Escriba el frontmatter con name y description, donde quede explícito cuándo aplicar el skill.
4. Describa los pasos con comandos concretos y criterios de terminación: qué comprobar y qué resultado se considera éxito.
5. Saque lo largo a archivos vecinos y enlácelos desde el texto principal.
6. Quite el duplicado de CLAUDE.md y deje una sola línea de referencia: «Despliegue: skill deploy».
7. Compruebe: en una sesión nueva pida la tarea con sus propias palabras, sin nombrar el skill, y mire si el agente lo utiliza. Si no lo hace, reescriba la descripción.

Ejemplos de skills

Skill de despliegue

El candidato clásico: el procedimiento es poco frecuente, largo y peligroso, y un error sale caro. El skill fija el orden de los pasos (primero la prueba en seco, después la subida), qué no se debe publicar, cómo comprobar el resultado y cómo revertir. El agente no necesita tener todo esto en la cabeza al editar código, solo cuando se trata del servidor.

Skill de revisión

---
name: review
description: Revisión de los cambios actuales antes del commit. Usar cuando pidan revisar el diff, buscar errores en las ediciones o preparar los cambios para el commit.
---

# Revisión de cambios

1. Obtener el diff: `git diff` y `git diff --staged`.
2. Para cada archivo modificado comprobar:
   - la entrada del usuario se escapa al mostrarla;
   - las consultas SQL están parametrizadas;
   - no hay salida de depuración ni archivos temporales.
3. Ejecutar las pruebas y el linter del proyecto (los comandos están en CLAUDE.md).
4. Informe: lista de problemas con archivo y línea, de los graves a los menores.
   Si no hay problemas, decirlo así, sin inventar observaciones.

Este skill convierte «revisa que todo esté bien» en una comprobación reproducible, con el mismo conjunto de puntos cada vez.

Skill de cierre de sesión

Otro tipo útil es el ritual al final del trabajo: detener el entorno local, eliminar los archivos temporales, anotar en el diario de progreso lo hecho y lo pendiente, y hacer un commit con descripción detallada. Esto cura directamente la pérdida de contexto entre sesiones: la siguiente sesión empieza con el estado real del repositorio, no con suposiciones.

Errores típicos

• Descripción vaga. El skill existe, pero el agente no lo invoca. Se corrige reescribiendo description con disparadores concretos.
• Skill en forma de muro. Se pasó a SKILL.md una sección antigua de 400 líneas. El problema del contexto inflado vuelve, solo que más tarde. Mantenga el texto principal corto y los detalles en archivos vecinos.
• Duplicación con CLAUDE.md. El mismo procedimiento está descrito en dos sitios y con el tiempo se desalinea. La fuente de verdad debe ser una sola.
• Skills que se solapan. Dos skills con descripciones parecidas: el agente elige entre ellos al azar. Sepárelos con indicaciones explícitas de «usar / no usar».
• Comandos obsoletos. Se renombró un script y el skill sigue apuntando al antiguo. El skill forma parte del código del proyecto: actualícelo en el mismo commit que el procedimiento.

Cómo saber cuándo conviene pasar una sección a un skill

Conviene revisar de vez en cuando CLAUDE.md y preguntarse por cada sección: ¿en qué proporción de las tareas habituales hace falta realmente? Si casi siempre, está en su sitio. Si solo en una de cada diez, es candidata a skill.

La segunda señal es la longitud. Una sección que no cabe en una pantalla casi seguro describe un procedimiento, no una regla. Los procedimientos se leen mejor completos en el momento de ejecutarlos que manteniéndolos en segundo plano durante toda la sesión.

La tercera señal son las explicaciones repetidas. Si una y otra vez le da al agente las mismas aclaraciones sobre la misma tarea, escríbalas una vez en un skill. Una semana después compruebe si han disminuido las correcciones manuales: eso demuestra que el skill funciona.

Resumen

Los skills de Claude Code sirven para guardar procedimientos junto al proyecto sin pagar por ellos con contexto en cada sesión. La descripción del skill se ve siempre, el cuerpo se carga cuando hace falta y los archivos auxiliares, aún después. En CLAUDE.md quedan el mapa del proyecto y las reglas estrictas; a los skills van el despliegue, la revisión, las publicaciones y otras tareas de un tipo concreto. La estructura de los archivos de instrucciones y la carga progresiva del contexto se explican en la práctica dentro del curso de harness engineering.