Claude Code skills. Qué son y cómo escribir una.

Una skill de Claude Code es un archivo SKILL.md con instrucciones que Claude usa automáticamente cuando son relevantes, o que ejecutas directamente como /skill-name. Escribe una cuando pegues una y otra vez las mismas instrucciones en el chat, o cuando una sección de tu CLAUDE.md se haya convertido en un procedimiento. A diferencia de CLAUDE.md, el cuerpo de una skill solo se carga cuando se usa.

01Skills y slash commands

Si aprendiste Claude Code hace tiempo, este es el cambio principal. Los comandos personalizados se han fusionado con las skills. .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean /deploy y funcionan igual, y tus archivos de comandos existentes siguen funcionando.

Las skills añaden tres cosas que un archivo de comando no tiene: una carpeta para archivos de apoyo, frontmatter que controla quién puede invocarlas y la capacidad de que Claude las cargue por su cuenta.

02Dónde viven las skills

La ubicación determina quién tiene la skill:

Cuando dos skills comparten nombre, enterprise gana a personal, y personal gana a proyecto. Las skills de plugins llevan su propio espacio de nombres, así que nunca colisionan.

03Qué viene incluido

Claude Code incluye skills que puedes ejecutar hoy, como /code-review, /batch, /debug, /loop, /run, /verify, /claude-api y /skill-doctor. Revisa estas antes de escribir las tuyas. Una skill tuya con el mismo nombre reemplaza al comando incluido, así que elige los nombres a propósito.

Las skills de documentos de Anthropic son otro caso. Las skills de Word, Excel, PowerPoint y PDF no vienen incluidas con Claude Code, aunque pdf y xlsx sí llegan mediante la sincronización de cuenta si inicias sesión con claude.ai.

04Escribe tu primera skill

Esta redacta notas de versión para clientes a partir de tu historial de git. Crea la carpeta:

mkdir -p ~/.claude/skills/release-notes

Guarda esto dentro de esa carpeta como SKILL.md:

---
name: release-notes
description: Redacta notas de versión para clientes a partir de los commits recientes de git. Úsala cuando el usuario pida notas de versión, una entrada de changelog o un resumen de lo publicado.
disable-model-invocation: true
allowed-tools: Bash(git log *)
---

Escribe las notas de versión a partir de estos commits:

!`git log --oneline -20`

Reglas:
- Agrupa las entradas en Añadido, Cambiado y Corregido.
- Describe qué ha cambiado para el cliente, no en el código.
- Omite los commits de merge y las refactorizaciones internas.
- Si nada afecta al cliente, dilo.

Ahora escribe /release-notes. No hace falta reiniciar, porque Claude Code vigila las carpetas de skills y recoge los cambios en directo. La única excepción es crear un directorio .claude/skills/ de nivel superior a mitad de sesión, que requiere /reload-skills.

Aquí hay dos detalles que hacen trabajo de verdad. La línea !`command` se ejecuta antes de que Claude vea la skill, así que recibe la lista real de commits. Y disable-model-invocation: true significa que solo tú puedes iniciarla, lo que viene bien para cualquier cosa cuyo momento quieras decidir tú.

05El frontmatter que importa

En Claude Code todos los campos son opcionales, aunque description es muy recomendable. Sin él, Claude recurre a la primera línea del archivo. Estos son los campos que conviene aprender primero:

06Cuándo una skill no es la herramienta adecuada

Las skills no son la respuesta a todo. Cada uno de estos hace un trabajo que una skill hace mal:

07Instalar y compartir

Para un equipo, haz commit de .claude/skills/ en el repositorio. Para una distribución más amplia, publica un plugin. Instalar desde un marketplace requiere dos comandos:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Ejecuta /plugin sin argumentos para explorar y gestionar lo que tienes instalado. Las skills tienen el mismo acceso a la red que cualquier otro programa de tu ordenador, así que lee primero las skills de terceros, scripts incluidos.

08Cuando una skill falla