SKILL.md: qué es y cómo crear skills de Claude

Una skill es una carpeta con un archivo SKILL.md que enseña a Claude a hacer una tarea concreta. A diferencia de las instrucciones permanentes, no ocupa contexto hasta que hace falta: Claude lee su descripción, decide si la necesita y solo entonces carga el resto. Todo el formato es Markdown con un pequeño bloque de frontmatter.

Qué es una skill

Piensa en una skill como en un manual de procedimiento. Explica cómo publicar una versión, cómo revisar un pull request según las normas del equipo o cómo escribir un artículo siguiendo la plantilla de tu blog. Claude la tiene disponible siempre, pero solo la abre cuando la tarea lo pide.

Hay dos formas de usarla. La primera es automática: Claude ve que tu petición encaja con la descripción de la skill y la carga por su cuenta. La segunda es manual: la invocas tú escribiendo / seguido de su nombre, como si fuera un comando.

Las skills funcionan en Claude y en Claude Code, y el formato está publicado como especificación abierta en agentskills.io, así que no es exclusivo de una herramienta.

Skills frente a CLAUDE.md

La diferencia con CLAUDE.md está en cuándo se cargan. El CLAUDE.md entra en el contexto al principio de cada sesión, se use o no. De una skill, al arrancar solo se carga el nombre y la descripción; el cuerpo entra cuando se usa.

Eso cambia qué conviene poner en cada sitio:

	CLAUDE.md	Skill
Cuándo se carga	Siempre, al arrancar	Solo cuando hace falta
Qué contiene	Hechos y reglas generales	Procedimientos de varios pasos
Coste de contexto	Todo el archivo, en cada sesión	Casi nada hasta que se usa
Ejemplo	"Los tests se lanzan con `npm test`"	"Cómo preparar y publicar una release"

La propia documentación de Claude Code lo resume así: si una entrada de tu CLAUDE.md es un procedimiento de varios pasos o solo importa en una parte del proyecto, muévela a una skill.

Estructura de una skill

Una skill es un directorio. Lo único obligatorio es el SKILL.md; el resto son archivos de apoyo opcionales que Claude solo lee si los necesita:

articulo-blog/
├── SKILL.md          # Obligatorio: metadatos e instrucciones
├── references/       # Opcional: documentacion de consulta
├── scripts/          # Opcional: codigo que el agente puede ejecutar
└── assets/           # Opcional: plantillas, imagenes, datos

El nombre de la carpeta importa: según la especificación abierta, debe coincidir con el campo name del frontmatter.

El archivo SKILL.md

El SKILL.md tiene dos partes: un bloque de frontmatter en YAML entre líneas --- y, debajo, las instrucciones en Markdown. Este es el ejemplo mínimo:

---
name: articulo-blog
description: Escribe articulos para el blog siguiendo el estandar del sitio. Usala cuando el usuario pida un articulo, un post o una entrada nueva para el blog.
---

# Instrucciones

Aqui van los pasos que Claude debe seguir.

El frontmatter tiene que empezar en la primera línea del archivo. Si hay cualquier cosa antes del primer ---, Claude Code trata todo el archivo, frontmatter incluido, como texto de la skill.

Campos obligatorios

La especificación abierta pide dos campos. Claude Code es más flexible y los acepta ausentes, pero conviene ponerlos siempre para que la skill funcione en cualquier herramienta compatible:

name: hasta 64 caracteres, solo minúsculas, números y guiones. No puede empezar ni acabar en guion ni tener dos guiones seguidos. En Claude Code es también el nombre del comando: name: articulo-blog se invoca con /articulo-blog.
description: hasta 1.024 caracteres. Dice qué hace la skill y cuándo usarla. Es el campo más importante, porque es lo único que Claude ve antes de decidir si la carga.

Campos opcionales

Hay más campos, y algunos solo los entiende Claude Code. Estos son los más útiles:

allowed-tools: herramientas que la skill puede usar sin pedir permiso, como Bash(git commit *).
disable-model-invocation: con true, Claude no la carga por su cuenta; solo se ejecuta si la invocas tú. Es lo recomendable para acciones con efectos, como desplegar o enviar un mensaje.
license, compatibility y metadata: información sobre licencia, requisitos de entorno y datos propios.

La lista completa de Claude Code es larga y cambia con las versiones; consulta la documentación oficial de skills para los detalles del momento.

Cómo escribir una buena descripción

Como Claude decide si usar la skill solo con la descripción, una descripción vaga hace que la skill no se use nunca o que se use cuando no toca. La especificación pone este contraste:

Mala: "Ayuda con PDF."
Buena: "Extrae texto y tablas de archivos PDF, rellena formularios PDF y combina varios PDF. Úsala cuando trabajes con documentos PDF o cuando el usuario mencione PDF, formularios o extracción de documentos."

La buena tiene tres cosas: qué hace, cuándo usarla y las palabras que usaría el usuario al pedirlo. Esas palabras son las que Claude compara con tu petición.

Pon el caso de uso principal al principio. Claude Code recorta la descripción en el listado de skills si es muy larga, y lo primero es lo que siempre se ve.

Un ejemplo completo

Esta skill recoge el estándar de artículos de este blog. Es un buen candidato porque, escrito dentro del CLAUDE.md del proyecto, ocupa contexto incluso en sesiones que no tienen nada que ver con el blog:

---
name: articulo-blog
description: Escribe articulos para el blog de tutorialmarkdown.com siguiendo el estandar del sitio. Usala cuando el usuario pida un articulo, post o entrada nueva para el blog.
---

# Articulo de blog

## Ubicacion
- Archivo en src/pages/blog/<slug>.mdx
- Despues, anade la tarjeta al grid de src/pages/blog.mdx

## Frontmatter
- Solo title, description y date (formato 2026-10-07)
- Sin dos puntos seguidos de espacio dentro de los valores

## Cuerpo
- Primera linea en cursiva con la fecha de publicacion
- Sin H1: lo pone el layout
- Apertura de un parrafo directo, de 2 o 3 frases
- Secciones con ##, subsecciones con ###
- Tras cada encabezado, un parrafo antes de cualquier lista o tabla
- Cierre con ## Recursos relacionados y enlaces internos

## Antes de terminar
- Revisa que todo el texto lleve tildes
- Comprueba las afirmaciones sobre productos externos en su documentacion

Fíjate en que no explica qué es Markdown ni cómo se escribe un buen artículo en general. Claude ya lo sabe. Una skill rinde cuando recoge lo que es propio de tu proyecto y no se puede deducir.

Carga progresiva

La especificación describe la carga de una skill en tres niveles, y entenderlos ayuda a decidir qué poner en cada sitio:

Metadatos, unos 100 tokens: el nombre y la descripción de todas las skills se cargan al arrancar.
Instrucciones, menos de 5.000 tokens recomendados: el cuerpo del SKILL.md se carga al activar la skill.
Recursos, según haga falta: los archivos de references/, scripts/ o assets/ solo se leen si la tarea los necesita.

La recomendación práctica es mantener el SKILL.md por debajo de 500 líneas y llevar el material de consulta largo a archivos aparte, enlazados con rutas relativas:

## Recursos adicionales

- Para la referencia completa de la API, consulta [reference.md](references/reference.md)
- Para ver ejemplos de uso, consulta [examples.md](references/examples.md)

Mantén las referencias a un solo nivel de profundidad: que el SKILL.md enlace a archivos, pero que esos archivos no enlacen a otros. Es la misma lógica de enlaces internos en Markdown que usarías en cualquier documentación.

Dónde se guardan las skills en Claude Code

Claude Code busca las skills en varias ubicaciones, según a quién deban servir:

Alcance	Ruta	Para quién
Personal	`~/.claude/skills/<nombre>/SKILL.md`	Tú, en todos tus proyectos
Proyecto	`.claude/skills/<nombre>/SKILL.md`	Todo el equipo, vía Git
Plugin	`<plugin>/skills/<nombre>/SKILL.md`	Quien tenga el plugin activado

Si vienes de versiones anteriores de Claude Code y tienes comandos personalizados en .claude/commands/, siguen funcionando. Los comandos se han integrado en las skills: un archivo .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md crean el mismo /deploy. La skill añade la carpeta para archivos de apoyo y la carga automática.

Errores comunes

Estos son los fallos más habituales al escribir una skill:

Descripción genérica: "Ayuda con el blog" no le dice a Claude cuándo usarla. Incluye las palabras que usarías al pedirlo.
Explicar lo que el modelo ya sabe: cada línea obvia ocupa contexto y diluye las que importan.
Un SKILL.md gigante: si pasa de 500 líneas, divide el material de consulta en archivos de references/.
Nombre que no coincide con la carpeta: la especificación lo exige, y algunas herramientas no cargarán la skill.
Carga automática en acciones con efectos: una skill que despliega o envía correos debería llevar disable-model-invocation: true.
Frontmatter mal colocado: si el primer --- no está en la primera línea, el frontmatter no se lee. Revisa también que el YAML sea válido, igual que en cualquier front matter de Markdown.

Recursos relacionados

CLAUDE.md, el archivo de instrucciones de Claude Code: las reglas que se cargan en todas las sesiones
AGENTS.md, el estándar para agentes de IA: el archivo de contexto que comparten varias herramientas
MCP y Markdown: cómo se conectan los agentes con herramientas externas
Cómo usar MarkItDown con Claude: convertir documentos a Markdown para trabajar con ellos en Claude
System prompts con Markdown: cómo escribir instrucciones para agentes y chatbots
Prompt engineering: técnicas para sacar más partido a los modelos