Cómo crear un skill en Claude Code para automatizar lo que haces siempre

Un skill es un archivo SKILL.md con instrucciones que Claude Code suma a sus herramientas. Claude lo usa cuando detecta que es relevante, o tú lo invocas de forma directa escribiendo /nombre-del-skill.

Crea uno cuando te descubras pegando el mismo checklist o procedimiento en el chat, o cuando una sección de tu CLAUDE.md haya dejado de ser un dato y se haya convertido en un procedimiento. La ventaja frente a CLAUDE.md es que el contenido de un skill solo se carga cuando se usa, así que puedes tener material largo de referencia sin gastar contexto todo el tiempo.

Si aún no usas Claude Code, empieza por la guía de inicio.

Anatomía de un skill

Cada skill vive en su propia carpeta y necesita un SKILL.md con dos partes:

1. Frontmatter YAML entre marcas ---, que le dice a Claude cuándo usarlo.
2. Contenido markdown con las instrucciones que sigue cuando se ejecuta.

El nombre de la carpeta (o el campo name, si lo defines) es el comando que escribes.

Dónde se guardan

Los comandos personalizados antiguos de .claude/commands/ siguen funcionando: los comandos y los skills se fusionaron, y un archivo .claude/commands/deploy.md crea el mismo /deploy que un skill.

Ejemplo: un skill para escribir artículos del blog

Voy a crear uno para mi blog en Astro. Guarda esto en .claude/skills/nuevo-articulo/SKILL.md:

---
name: nuevo-articulo
description: Crea un artículo nuevo para el blog en español con el frontmatter correcto.
disable-model-invocation: true
---

Crea un artículo nuevo en `src/content/blog/` sobre el tema: $ARGUMENTS

Sigue estos pasos:

1. Genera un slug en minúsculas, sin acentos y con guiones.
2. Crea el archivo `.md` con este frontmatter: title, excerpt, image, date (fecha de hoy), author "Javi Mata", categories y tags.
3. Escribe en español, con tono práctico y cercano, y bloques de código donde aplique.
4. Termina con una sección "Fuentes" si citaste documentación.
5. Corre `yarn build` para validar que el frontmatter sea correcto.

Ahora, dentro de Claude Code:

/nuevo-articulo cómo optimizar imágenes en Astro

Todo lo que escribas después del comando llega al skill en $ARGUMENTS.

Los campos de frontmatter que más vas a usar

Existen más (model, effort, context: fork para ejecutarlo en un subagente, hooks, paths), pero con los anteriores cubres casi todo.

Un detalle sobre el ejemplo: con disable-model-invocation: true la descripción ni siquiera se carga en el contexto de Claude, y el skill completo se carga solo cuando tú lo invocas.

Otro detalle importante: los campos aceptados dependen de dónde uses el skill. Claude Code entiende todos, pero si subes un skill a claude.ai o a la API, solo se permiten name, description, license, compatibility, metadata y allowed-tools. Un campo como argument-hint ahí produce un error de validación.

Archivos de apoyo

Un skill puede incluir más archivos en su carpeta: plantillas, ejemplos, scripts. Mantén el SKILL.md enfocado en lo esencial y referencia esos archivos desde ahí; Claude los leerá solo cuando haga falta.

Skills que vienen incluidos

Claude Code trae algunos por defecto, como /code-review, /debug, /run y /verify. Escribe / en una sesión para ver todos los disponibles.

Consejos

• Escribe una description clara. Es lo que Claude lee para decidir si carga el skill por su cuenta (no aplica si usas disable-model-invocation: true). Ponle primero el caso de uso principal, porque el texto se recorta a 1,536 caracteres en el listado.
• Usa disable-model-invocation: true en lo que tenga efectos (publicar, borrar, desplegar).
• Versiona los skills de proyecto. Así todo tu equipo trabaja igual.
• Empieza pequeño. Convierte en skill el procedimiento que más repites y ajústalo con el uso.

Conclusión

Un skill convierte un procedimiento que repetías a mano en un comando reutilizable. Es una de las formas más simples de personalizar Claude Code, y el único requisito es saber escribir markdown.

Fuentes

• Extend Claude with skills (documentación oficial)