Skills en Claude Code: qué son, cómo se escriben y cuándo usarlas (2026)

Una skill es la forma que tiene Claude Code de guardar un procedimiento: cómo se hace algo en tu empresa, paso a paso, con su formato y sus comprobaciones, para que el agente lo siga igual cada vez que haga falta. Es una carpeta con un archivo SKILL.md dentro, y se invoca con una barra, como un comando: /informe-semanal.

Resuelve un problema concreto. Cada sesión de Claude Code abre una ventana de contexto nueva. Lo que vale para todo el proyecto —cómo se prueba, qué no se toca— va en el archivo de instrucciones, que se carga siempre, y la memoria automática guarda preferencias y correcciones. Pero un procedimiento largo que solo usas los lunes no merece ocupar espacio en cada sesión, y tampoco conviene reescribirlo en el chat cada semana. Ese hueco es el de las skills.

Esta guía explica qué son, cómo las carga Claude, dónde se guardan, cómo se escribe su SKILL.md y cómo comprobar que funcionan, con una skill de ejemplo completa al final. Todo está comprobado con la documentación oficial el 27 de septiembre de 2026.

Imagina la cocina de un restaurante. El manual de la casa dice cosas que valen siempre: dónde está cada cosa, las normas de higiene, cómo se llama cada plato. Eso es el CLAUDE.md. Pero la receta del arroz de los domingos no está en el manual: está en una ficha aparte que el cocinero saca solo cuando toca hacer arroz. Eso es una skill.

La ventaja es la misma que en la cocina: el arroz sale parecido lo haga quien lo haga, y el manual no se llena de recetas que solo se usan una vez por semana.

Una skill es una carpeta con un archivo SKILL.md adentro. Ese archivo tiene dos partes: un encabezado con datos —el nombre y, sobre todo, la descripción— y el cuerpo con las instrucciones, escrito en Markdown. Nada más es obligatorio.

Si la tarea lo pide, la carpeta puede traer más: un archivo de referencia con el detalle que no cabe en las instrucciones, ejemplos, o scripts que el agente ejecuta en lugar de redactar de más. La recomendación de la documentación es mantener SKILL.md por debajo de 500 líneas y mover el material largo a archivos aparte que el propio SKILL.md nombra.

Dos datos que ordenan el tema:

• Es un estándar abierto. Las skills de Claude Code siguen el estándar Agent Skills, de agentskills.io, pensado para que la misma carpeta funcione en varias herramientas de IA, no solo en una.
• Los comandos personalizados ya son skills. Antes había dos cosas distintas; hoy un archivo .claude/commands/despliega.md y una skill .claude/skills/despliega/SKILL.md crean el mismo comando. Si encuentras carpetas commands viejas, siguen funcionando tal cual.

Y Claude Code ya trae algunas skills de fábrica —/doctor, /code-review, /debug— que se invocan igual que las tuyas y sirven de modelo de cómo se escriben.

Claude no lee tus skills completas al arrancar. Lo que entra en la ventana de contexto de cada sesión es un listado: el nombre y la descripción de cada una. Con eso sabe qué existe. El cuerpo —las instrucciones— lo lee solo cuando la skill se invoca, sea porque tú escribiste /nombre o porque tu pedido encaja con su descripción. Y los archivos de apoyo se leen solo cuando el propio SKILL.md los nombra.

Ese reparto tiene dos consecuencias prácticas:

• El material largo es barato. Como el cuerpo se carga solo al usarse, una referencia extensa dentro de la skill cuesta casi nada hasta el día que se necesita.
• Las skills que Claude puede activar solo ocupan un poco de contexto siempre. Su nombre y su descripción están en el listado, las uses o no; las que reservas para invocar tú no ocupan nada hasta que las llamas. Coleccionar skills sin uso gasta contexto que le hace falta a tu conversación.

Por eso la descripción es la parte que más trabajo merece: es lo único que Claude ve para decidir si la usa. Una descripción genérica («ayuda con informes») compite con todo lo demás; una concreta («prepara el informe semanal para dirección a partir de las hojas de ventas, gastos y banco») se reconoce en cuanto la pides. Hazla concreta y pon el caso de uso principal al principio, porque el texto conjunto de description y when_to_use se corta, en el listado, a los 1.536 caracteres.

La carpeta donde guardas la skill decide quién la ve. Las tres rutas que importan a diario: la personal, para todos tus proyectos; la de proyecto, para quien trabaja en ese repositorio; la de plugin, para entregarla instalada junto con otras piezas.

Un detalle que ahorra reinicios: si editas o agregas una skill en plena sesión, Claude Code detecta el cambio y la recoge sin que vuelvas a arrancar. La excepción es una carpeta de skills de nivel superior que no existía al abrir la sesión: para esa hay que ejecutar /reload-skills.

El archivo abre con un bloque de configuración en YAML entre dos líneas ---. Si la primera línea del archivo no es ---, todo el archivo se lee como instrucciones y ningún campo aplica. Después del bloque van las instrucciones en Markdown.

Todos los campos son opcionales y solo description es recomendable. Un campo que Claude Code no reconoce se ignora sin error, así que un nombre mal escrito no rompe nada: solo no hace nada. Estos son los que de verdad se usan al empezar:

Dos caminos. El tuyo: escribes /informe-semanal y listo; puedes pasar argumentos —/arregla-issue 123— y el texto que sigue al nombre llega a las instrucciones donde escribiste $ARGUMENTS. El de Claude: lee tu pedido, lo compara con las descripciones del listado y, si una encaja, carga esa skill.

Cada camino se puede cerrar por separado:

• disable-model-invocation: true deja la skill solo para ti. Es lo que quieres en tareas con efectos fuera del chat: desplegar, enviar, publicar. Tú decides cuándo, no el criterio del agente. Además, su descripción deja de ocupar espacio en el listado de Claude.
• user-invocable: false hace lo contrario: la oculta del menú / y la deja como conocimiento de fondo que Claude activa cuando encaja. Sirve para contexto que no es un comando, como cómo funciona el sistema viejo de la empresa o cómo se llama cada tabla.

Cuatro mecanismos que conviene no mezclar. Si no conoces el archivo de instrucciones, aquí está la guía de CLAUDE.md y AGENTS.md.

Y por encima de todo esto está el plugin: un directorio que agrupa skills, subagentes, hooks y servidores MCP y se instala como una unidad desde un catálogo. Sirve cuando quieres entregar o recibir un paquete completo con un comando, no cuando estás escribiendo tu primera skill.

Una skill son instrucciones; no le da a Claude brazos nuevos. Los brazos son herramientas, y un servidor MCP es la forma de conectar herramientas nuevas: un programa que le da acceso a un sistema externo. La distinción está explicada en herramienta y habilidad y en qué es MCP.

Juntas cubren el flujo completo. Imagina el circuito de una orden de compra: la skill lleva el procedimiento con el criterio de tu empresa —qué revisar, en qué orden, con qué formato dar de alta la factura— y el servidor MCP del sistema contable aporta las acciones: consultar la orden, crear el documento. La skill dice qué hacer; el servidor, con qué hacerlo. Y si quieres repartir el conjunto, un plugin puede empaquetar la skill y el servidor MCP juntos: quien instala recibe instrucciones y herramientas de una vez.

Que la skill se active solo prueba que Claude la encontró; no prueba que hizo lo que querías. Hay que medir dos cosas por separado: si se invoca con los pedidos que debe, y si el resultado sale como esperas cuando se invoca.

El método es una comparación de base. Junta unos pedidos reales —los que de verdad escribes en el trabajo, no ejemplos de laboratorio—, córrelos en una sesión nueva con la skill disponible y vuelve a correrlos con la skill desactivada. La sesión nueva importa: si la pruebas en la misma conversación donde la escribiste, el contexto sobrante tapa los huecos de las instrucciones. Para no hacerlo a mano, la documentación describe el plugin oficial skill-creator, que se instala con /plugin install skill-creator@claude-plugins-official: guarda los casos de prueba junto a la skill, corre cada uno en una sesión aislada, califica el resultado y compara dos versiones a ciegas para que confirmes que un cambio fue una mejora antes de guardarlo.

Con los resultados delante, revisa dos cosas:

• Activación. Haz una lista corta con pedidos que deberían usar la skill y otros parecidos que no. Si falla en los primeros, a la descripción le faltan las palabras con las que tú lo pides; si salta en los segundos, está demasiado abierta, o conviene reservarla con disable-model-invocation: true para invocarla tú.
• Calidad. Compara lo que devuelve con el resultado que harías a mano. Si se parece a lo que saldría sin skill, las instrucciones son demasiado generales: escribe el formato esperado y los pasos concretos, no consejos.

Imagina que cada lunes preparas el informe de dirección: abres la hoja de ventas, la de gastos y el archivo del banco, y lo armas con el formato que la dirección ya conoce: resumen, ventas por día, gastos por categoría y las diferencias que merecen atención. A mano, hay que reunir y ordenar los datos cada semana. Sin instrucciones, cada semana el agente te lo devolvería con otra estructura y otro criterio.

La skill fija el formato una vez. Crea la carpeta informe-semanal dentro de .claude/skills/ de tu proyecto y guarda dentro este SKILL.md:

Fíjate en qué hace que esta skill funcione: la descripción deja claro en el menú para qué sirve, y como lleva disable-model-invocation: true solo se ejecuta cuando tú escribes /informe-semanal; el formato está cerrado, con secciones, orden y títulos; la verificación va antes de entregar; y hay una regla para el hueco —si falta un dato, se escribe «dato faltante» en vez de completarlo—.

Pruébala en una sesión nueva con los datos de una semana que ya conozcas. Si el informe sale igual al que hiciste a mano, la skill está lista. Si no, el ajuste suele estar en la descripción o en un paso ambiguo, no en escribir más.

Imagina un restaurante que recibe reseñas en Google cada día y quiere contestarlas todas con el mismo tono, sin sonar a robot. Esta skill no publica nada: prepara los borradores para que alguien los revise y los pegue.

Elige una sola tarea para tu primera skill: una que hagas cada semana, que tenga un formato que ya conozcas y cuyo resultado puedas comparar con el que harías a mano. El informe de este ejemplo cumple las tres condiciones. Escríbela corta, pruébala con los datos de una semana cerrada y compara. Solo cuando falle en algo concreto, añade la instrucción que falta.

Una skill no hace infalible al agente: hace predecible el encargo. Revisar lo que devuelve sigue siendo trabajo tuyo, y la guía completa de Claude Code explica el resto de piezas —permisos, hooks, subagentes— que ayudan a controlarlo.