Una skill de Claude Code es una carpeta con un archivo SKILL.md dentro: frontmatter YAML que le indica a Claude cuándo usar la skill, e instrucciones en Markdown sobre qué hacer una vez que se activa. Ese es todo el modelo. Para crear una, creas el directorio, escribes el archivo de dos partes y Claude o bien la carga automáticamente cuando tu petición coincide con la descripción, o bien la invocas directamente con /skill-name. Sin compilar plugins ni reiniciar en la mayoría de los casos. Todo el pipeline de contenido de este sitio funciona como una única skill de Claude Code, así que el recorrido siguiente tiene la misma forma que usamos en producción, no es un ejemplo de juguete.
Las skills importan porque sustituyen aquello que todo usuario intensivo de Claude Code acaba haciendo: pegar la misma lista de comprobación o el mismo procedimiento de varios pasos en el chat una y otra vez. Traslada ese procedimiento a una skill una sola vez y se convierte en una capacidad reutilizable, con control de versiones, que se carga solo cuando es relevante. Según el artículo de ingeniería de Anthropic, las skills siguen un estándar abierto diseñado para que un agente incorpore experiencia bajo demanda en lugar de arrastrarla en el contexto todo el tiempo.
¿Qué es una skill de Claude Code?
Una skill es la unidad más pequeña de procedimiento reutilizable en Claude Code. Estructuralmente es un directorio que contiene un archivo obligatorio, SKILL.md, más los archivos de apoyo opcionales que quieras. El frontmatter incluye un name y una description; el cuerpo contiene las instrucciones que Claude sigue cuando se ejecuta la skill. Según la documentación de Claude Code, el nombre del directorio se convierte en el comando de barra que escribes, y la descripción es lo que Claude lee para decidir si carga la skill automáticamente. En 2026 los comandos personalizados se fusionaron con las skills: un archivo en .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md crean ambos /deploy y se comportan de la misma forma, salvo que la carpeta de la skill también puede empaquetar scripts y archivos de referencia. Si alguna vez has escrito un comando de barra, ya conoces el 80 % de las skills.
Dónde viven las skills
Dónde colocas la carpeta decide su alcance. Hay tres niveles, y la elección tiene que ver con quién debería ver la skill:
| Nivel | Ruta | Disponible en |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | Todos tus proyectos |
| Proyecto | .claude/skills/<name>/SKILL.md | Solo este repositorio (haz commit para compartirla con el equipo) |
| Plugin | <plugin>/skills/<name>/SKILL.md | Allá donde el plugin esté activado |
Cuando los nombres colisionan, el personal prevalece sobre el de proyecto, y cualquiera de los dos prevalece sobre una skill empaquetada del mismo nombre, de modo que una skill code-review de proyecto sustituye al /code-review integrado. Las skills de proyecto también se cargan desde carpetas .claude/skills/ anidadas, lo que permite que un paquete de un monorepo distribuya skills que solo se aplican cuando trabajas dentro de ese paquete. Para un equipo, a nivel de proyecto y con commit en git es casi siempre la opción correcta: todos obtienen automáticamente las mismas barreras de seguridad, del mismo modo que un archivo AGENTS.md compartido estandariza el comportamiento del agente en un repositorio.
Cómo crear una skill de Claude Code, paso a paso
Aquí tienes el ciclo completo para una skill real y útil que resume tus cambios sin confirmar. Primero crea el directorio en tu carpeta de skills personal:
mkdir -p ~/.claude/skills/summarize-changes
Después guarda esto como ~/.claude/skills/summarize-changes/SKILL.md:
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff before committing.
---
Run `git diff` and `git status` to see staged and unstaged changes.
Summarize what changed, grouped by file, in plain language.
Flag anything risky: secrets, deleted tests, large deletions, or config changes.
End with a suggested Conventional Commit message.
Eso es todo. Abre un proyecto de git, haz una edición y, o bien pregunta «¿qué he cambiado?» (Claude la carga automáticamente porque la petición coincide con la descripción), o bien escribe /summarize-changes para ejecutarla directamente. Claude Code vigila los directorios de skills en busca de cambios, así que las ediciones bajo ~/.claude/skills/ o un .claude/skills/ de proyecto surten efecto dentro de la sesión. Solo crear un directorio de skills de nivel superior completamente nuevo que no existía al arrancar requiere un reinicio.
Por qué la descripción lo es todo
El motivo más común, con diferencia, por el que una skill nunca se activa es una description débil. No es documentación, es el disparador: al arrancar, Claude carga únicamente el nombre y la descripción de cada skill, y luego usa ese texto para decidir qué incorporar. Una descripción vaga como «Constructor de dashboards» deja a Claude adivinando. El propio skill-creator de Anthropic aconseja hacer las descripciones deliberadamente «insistentes» y llenarlas de contextos de activación: en lugar de «Cómo construir un dashboard», escribe «...usa esta skill siempre que el usuario mencione dashboards, visualización de datos, métricas internas, o quiera mostrar cualquier tipo de datos de la empresa, incluso si no pide explícitamente un dashboard». Pon en la descripción tanto lo que hace la skill como cada contexto en el que debería activarse. Toda la información sobre «cuándo usarla» va ahí, nunca enterrada en el cuerpo. Si tu skill no se activa, arregla la descripción antes de tocar cualquier otra cosa.
Divulgación progresiva: por qué las skills siguen siendo baratas
La razón por la que una skill puede contener un procedimiento enorme sin inflar tu contexto es la divulgación progresiva, un modelo de carga de tres niveles. El nivel 1 son los metadatos (nombre + descripción, ~100 palabras) que están siempre en el contexto. El nivel 2 es el cuerpo de SKILL.md, que se carga solo cuando la skill se activa. El nivel 3 son los recursos empaquetados (scripts, documentos de referencia, plantillas) que se cargan solo cuando el cuerpo dirige a Claude hacia ellos. Así, una skill con una referencia de migración de 2.000 líneas te cuesta unos 100 tokens hasta el momento en que realmente la necesitas. La regla práctica de la documentación: mantén el cuerpo de SKILL.md por debajo de 500 líneas, y cuando crezca más allá de eso, traslada el detalle a archivos separados y enlázalos.
summarize-changes/
├── SKILL.md # required: frontmatter + core instructions
└── references/ # optional: loaded only when SKILL.md points here
└── risk-rules.md
Este es el mismo principio que mantiene componibles los servidores MCP: exponer los metadatos de la capacidad de forma barata y cargar el detalle pesado bajo demanda.
Controlar quién invoca una skill
Por defecto, tanto tú como Claude podéis invocar cualquier skill. Para cualquier cosa con efectos secundarios, eso no es lo que quieres, y no deberías confiar en que Claude decida desplegar porque el código «parece listo». Añade disable-model-invocation: true al frontmatter y solo tú podrás activar la skill, escribiendo su comando de barra:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Usa esto para /commit, /deploy, /send-slack-message y cualquier acción irreversible. Dos campos relacionados dan un control más fino: allowed-tools enumera las herramientas que la skill puede usar sin una solicitud de permiso, y disallowed-tools retira herramientas del conjunto mientras la skill está activa (útil para un bucle en segundo plano que nunca debería hacerle una pregunta al usuario). Recurre a ellos de forma deliberada, no por defecto.
Skill vs CLAUDE.md vs MCP: ¿cuál necesitas?
Estos tres se solapan lo suficiente como para confundir a la gente, así que aquí tienes la distinción:
| Enfoque | Se carga | Ideal para |
|---|---|---|
| CLAUDE.md | Siempre en el contexto | Datos breves y siempre ciertos sobre el repositorio |
| Skill | Bajo demanda, cuando es relevante | Procedimientos repetibles y listas de comprobación |
| Servidor MCP | Esquemas de herramientas, bajo demanda | Conectarse a sistemas y datos externos |
La señal que delata una skill es un procedimiento: si una sección de tu CLAUDE.md ha pasado de ser un dato a un tutorial de varios pasos, quiere convertirse en una skill, donde no cuesta nada hasta que se usa. Un dato se queda en CLAUDE.md. Una conexión en vivo a Jira o a una base de datos es un servidor MCP. Muchas configuraciones reales usan las tres juntas, y elegir bien forma parte de esa misma alfabetización en herramientas que distingue a las herramientas de programación con IA que merece la pena usar en 2026.
Preguntas frecuentes
¿Qué es un archivo SKILL.md?
Es el único archivo obligatorio en una carpeta de skill. Tiene frontmatter YAML (como mínimo name y description) entre marcadores ---, seguido de instrucciones en Markdown que Claude sigue cuando se ejecuta la skill. El nombre de la carpeta se convierte en el /comando-de-barra, y la descripción le dice a Claude cuándo cargar la skill por sí mismo.
¿Dónde coloco una skill de Claude Code?
En ~/.claude/skills/<name>/SKILL.md para una skill personal disponible en todos tus proyectos, o en .claude/skills/<name>/SKILL.md para una skill de proyecto de la que haces commit y compartes con tu equipo. Los plugins también pueden empaquetar skills. Las skills personales prevalecen sobre las skills de proyecto del mismo nombre.
¿Necesito reiniciar Claude Code después de añadir una skill? Normalmente no. Claude Code vigila los directorios de skills y detecta skills añadidas, editadas o eliminadas dentro de la sesión actual. La excepción es crear un directorio de skills de nivel superior que no existía cuando comenzó la sesión, lo que requiere un reinicio para que el nuevo directorio pueda ser vigilado.
¿Por qué no se activa mi skill? Casi siempre es la descripción. Claude decide si carga una skill solo a partir de su nombre y su descripción, así que una descripción vaga significa que no puede saber que tu petición encaja. Reescribe la descripción para nombrar las tareas y frases exactas que deberían activarla, y sé explícito en que debe activarse incluso cuando el usuario no use la palabra clave obvia.
¿Puedo impedir que Claude ejecute una skill automáticamente?
Sí. Añade disable-model-invocation: true al frontmatter. Entonces solo tú podrás invocar la skill escribiendo su comando de barra, que es lo que quieres para cualquier cosa con efectos secundarios como desplegar o enviar un mensaje.
Sources
- Documentación de Claude Code — Amplía Claude con skills: la referencia autorizada para la estructura de SKILL.md, los campos del frontmatter, las ubicaciones de las skills, el control de invocación y la detección de cambios en vivo.
- Anthropic Engineering — Equipping agents for the real world with Agent Skills: la justificación de diseño de las skills y el estándar abierto.
- anthropics/skills — skill-creator SKILL.md: buenas prácticas de primera mano sobre cómo escribir descripciones, estructurar SKILL.md y aplicar la divulgación progresiva.
- Estándar abierto Agent Skills: el estándar multiherramienta que siguen las skills de Claude Code.
Waqas Ahmed Waseer
Waqas Ahmed Waseer es desarrollador y creador de automatizaciones con más de 8 años construyendo sistemas en producción que usan más de 100.000 personas. Crea SaaS multiinquilino a medida, automatización con IA (n8n, flujos LLM, bots de WhatsApp) e infraestructura de hosting (WHM/cPanel, CloudLinux), y es el creador de WaSphere, FlowMaticX y la marca de hosting WaseerHost. Más de 100 proyectos entregados para pymes, agencias y startups financiadas.
