Cómo crear una skill personalizada de Claude Code (con un ejemplo real que funciona)

este artículo está basado en Claude Code CLI. Las skills son una función que cambia rápido y algunos detalles pueden variar; cito mis fuentes al final.

¿Qué es una skill personalizada en Claude Code? (definición rápida)

Una skill personalizada es un paquete de instrucciones - una carpeta más un archivo SKILL.md - que le enseña a Claude Code a realizar un flujo de trabajo repetible exactamente como tú lo quieres. En lugar de reescribir todo ese prompt de "formatea este post del blog al estándar X, añade una tabla de contenidos, escribe la meta..." cada vez, empaquetas esa receta una sola vez como una skill. A partir de ahí, Claude Code reconoce cuándo usarla y sigue tus pasos.

Quienes empiezan suelen confundir una skill con otras dos cosas, así que separémoslas rápido:

• Skill - conocimiento o un flujo de trabajo que Claude Code invoca automáticamente cuando el contexto coincide con tu description. No escribes ningún comando.
• Slash command - un atajo que escribes a propósito (por ejemplo /commit). Mira los detalles en slash commands en Claude Code.
• Subagent - un "subasistente" que ejecuta tareas pesadas en su propio contexto separado. Mira la guía de subagents.

Si los cuatro conceptos aún se te mezclan, el artículo sobre skills vs subagents vs hooks vs MCP lo desglosa con más detalle. Y si todavía no tienes claro qué es fundamentalmente una skill, lee primero qué son las Skills de Claude Code y luego vuelve aquí para construir una de verdad. Este artículo está 100% enfocado en poner a funcionar una skill real en Claude Code CLI.

¿Cómo funciona una skill? (divulgación progresiva)

Entiende este mecanismo y escribirás skills correctamente desde el principio. Claude Code no mete el contenido completo de cada skill en el contexto - eso quemaría tokens y añadiría ruido. Usa divulgación progresiva (carga bajo demanda), en tres capas:

• Capa 1 - siempre residente: Claude Code mantiene en el contexto solo el name y la description de cada skill. Es el "letrero" que indica qué skills existen y para qué sirven.
• Capa 2 - se carga al coincidir: solo cuando el contexto de la conversación coincide con la description se lee el cuerpo de SKILL.md en el contexto.
• Capa 3 - se carga bajo demanda: los archivos de apoyo como reference.md o scripts/ se abren solo cuando Claude realmente los necesita.

La consecuencia más importante: la description es el interruptor de invocación automática. Si tu description no contiene las palabras clave de contexto que un usuario realmente va a decir, Claude Code nunca abrirá el cuerpo de tu skill para leerlo - por muy bien escrito que esté ese cuerpo. Por eso la mayoría de las skills que "no se ejecutan" fallan justo en la línea de la description, no en el contenido.

Configuración: dónde vive la skill (personal vs proyecto)

Aquí es donde la mayoría de los tutoriales en inglés se saltan pasos, porque hablan de la app web claude.ai. Con Claude Code CLI, una skill vive en el sistema de archivos y tienes dos lugares para ponerla, elegidos según el propósito:

La regla simple: tu propio flujo va en ~/.claude/skills/; una convención de todo un equipo o proyecto va en .claude/skills/ dentro del repositorio, y luego haces commit en git para que todos la reciban.

El único requisito previo es tener Claude Code instalado (si no lo tienes, mira la guía de instalación de Claude Code). Puedes revisar tus skills existentes preguntando directamente en una sesión de Claude Code - por ejemplo el prompt "lista las skills que tienes ahora" - o abriendo la carpeta ~/.claude/skills/. Después de crear una skill nueva, acuérdate de reiniciar para que se escanee.

Cómo crear una skill personalizada de Claude Code en 5 pasos

Aquí está el flujo completo. Usaré un mismo ejemplo de principio a fin - una skill blog-formatter que limpia un post de blog en Markdown en bruto - para que sea fácil de imaginar, pero el enfoque sirve para cualquier flujo.

Paso 1 - Elige un flujo repetible

No te apresures a escribir una skill para algo que nunca has hecho a mano. Consejo práctico: hazlo manualmente con Claude Code unas cuantas veces hasta que produzca exactamente el resultado que quieres, y solo entonces destila ese prompt/flujo en una skill. Una buena skill es la cristalización de un proceso probado, no una suposición.

Algunos buenos candidatos para empezar: formatear un post de blog a tu estándar, generar mensajes de commit según la convención del proyecto, escribir tests unitarios a partir de una plantilla existente, o revisar docs de API. Elige algo que hagas al menos una vez por semana - ahí es donde se nota el ROI.

Paso 2 - Crea el árbol de carpetas + el archivo SKILL.md

Una skill mínima solo necesita una carpeta y un archivo SKILL.md. Añades archivos de apoyo cuando los necesitas. El árbol de carpetas completo se ve así:

~/.claude/skills/
 blog-formatter/
 SKILL.md # required - the main instructions
 reference.md # optional - long details, loaded on demand
 scripts/
 format.py # optional - a bundled script

Crea la carpeta desde la terminal:

mkdir -p ~/.claude/skills/blog-formatter
cd ~/.claude/skills/blog-formatter

Nombra la carpeta en kebab-case, corto y descriptivo de lo que hace la skill (blog-formatter, commit-msg). Para una skill pequeña, un solo SKILL.md basta - separa en reference.md o scripts/ solo cuando el cuerpo empiece a alargarse.

Paso 3 - Escribe el front matter YAML (name + description)

Abre SKILL.md. Justo arriba hay un bloque de front matter YAML entre dos líneas ---, con dos campos obligatorios: name y description. Esta es la parte que decide si la skill se autoinvoca o no, así que escríbela con cuidado.

La fórmula de una buena description: qué hace + CUÁNDO usarla + palabras clave de disparo que el usuario realmente va a decir en voz alta. Compara:

La de la izquierda es vaga, no tiene contexto, y Claude no tiene ni idea de cuándo llamarla. La de la derecha deja claro qué, cuándo, y las frases exactas que los usuarios suelen escribir. Escribe la description como si le dijeras a un compañero nuevo "es en estos momentos cuando acudes a mí".

Paso 4 - Escribe el cuerpo de instrucciones

Justo debajo del front matter está el cuerpo en Markdown - es el flujo que Claude Code lee y sigue cuando se llama a la skill. Un buen cuerpo debería incluir:

• Propósito - qué problema resuelve esta skill.
• Cuándo usarla - reformula el contexto (refuerza la description).
• Entradas que pedir - si falta información, qué preguntarle al usuario.
• Los pasos - un procedimiento claro y numerado.
• Estándar de salida - cómo se ve un resultado correcto.
• Errores a evitar + un ejemplo de entrada/salida.

Regla de oro: ser conciso es clave. Un cuerpo inflado quema contexto y distrae a Claude. Cuando las instrucciones se alarguen (tablas de consulta, muchos ejemplos), sepáralas en reference.md y apunta a él desde el cuerpo - gracias a la divulgación progresiva, el archivo de apoyo se carga solo cuando hace falta.

Paso 5 - Recarga & prueba la skill

Claude Code escanea la carpeta de skills al arrancar, así que después de crear o editar SKILL.md necesitas reiniciar: escribe /exit y vuelve a abrir la sesión de Claude Code. Luego prueba con un prompt natural que coincida con la description - por ejemplo: "Formatéame el post del blog en draft.md." Si lo escribiste bien, Claude Code lo reconoce y llama a la skill blog-formatter. Confirma que usó la skill correcta (Claude suele indicar qué skill se invocó) y luego comprueba que el resultado cumple el estándar que fijaste en el Paso 4.

Un ejemplo completo de skill personalizada (copia, pega y ejecuta)

Aquí tienes un SKILL.md completo que de verdad he escrito y usado. Cópialo tal cual en ~/.claude/skills/commit-msg/SKILL.md, reinicia y pruébalo enseguida:

---
name: commit-msg
description: Generate a Conventional Commits message from the currently staged changes. Use when the user says "write a commit", "commit message", "make a commit message", or right before committing code.
---

# Generate a Conventional Commits message

## Purpose
Read the staged diff and write a short, standards-compliant commit message.

## When to use
When the user is about to commit or asks for a commit message.

## Inputs to ask for
If nothing is staged, run `git diff --staged` to see the changes.
If it's still empty, ask the user: "Have you run `git add` yet?"

## Steps
1. Run `git diff --staged` to read the changes.
2. Determine the type: feat / fix / docs / refactor / test / chore.
3. Determine the scope (the main module/folder changed).
4. Write the subject line: `type(scope): short description` - max 72 chars, present tense.
5. If the change is complex, add 1-3 bullet points in the body explaining "why".

## Output standard
- Subject ≤ 72 chars, no trailing period.
- Description is clear and matches what was actually done.
- Do NOT invent changes that aren't in the diff.

## Mistakes to avoid
- Don't use the wrong type (adding a feature but labeling it `fix`).
- Don't write vague messages like "update code", "misc fixes".

## Example
Input diff: add an email validation function in `src/auth/`.
Output:
feat(auth): add email format validation on signup

Resultado real: una vez cargada, solo escribo "write a commit" y Claude Code ejecuta git diff --staged, lo clasifica bien y devuelve un mensaje que cumple el estándar - sin que yo reafirme la convención cada vez.

Una limitación observada (con honestidad): si el diff es enorme o mezcla varios tipos de cambio, el mensaje combinado a veces elige un type que no es el más adecuado - en ese punto todavía deberías dividir el commit o corregirlo a mano. La skill acierta el 90% de los casos; no reemplaza del todo tu criterio.

Prueba & depura cuando una skill no se dispara

Que Claude Code "ignore" una skill terminada es muy común. Aquí está la lista de comprobación que recorro, en orden, cuando una skill se niega a dispararse:

1. Sintaxis YAML rota. Un --- que falta, una indentación incorrecta o un carácter perdido en el front matter hacen que toda la skill se omita en silencio. Revisa primero el bloque de front matter.
2. Description vaga / faltan palabras clave de contexto. Este es el culpable número uno. Si tu prompt no tiene ninguna expresión que coincida con la description, la skill no se llama. Añade las palabras exactas que diría un usuario real.
3. No has reiniciado Claude Code. La carpeta de skills solo se escanea al arrancar. Después de editar, tienes que hacer /exit y volver a abrir.
4. Nombre duplicado o ruta incorrecta. Dos skills con el mismo name, o un SKILL.md en la carpeta equivocada (mayúsculas/minúsculas distintas, nivel incorrecto) no se cargan.
5. Cuerpo demasiado largo, que genera ruido. Un cuerpo inflado puede dificultar que Claude siga el procedimiento. Recórtalo y mueve el exceso a reference.md.

Consejo rápido de diagnóstico: fuerza una llamada manual para aislar el problema. Pide directamente: "Usa la skill blog-formatter para hacer esto." Si la llamada forzada funciona bien, el error está en la description (no puede autoinvocarse). Si la llamada forzada sigue fallando, el error está en el YAML o en la ruta.

Comparte & publica tu skill

Una vez que has escrito una buena skill, deberías compartirla - y esta es la parte que casi ningún tutorial en inglés cubre. Hay tres formas, de la más simple a la más pulida:

1. Haz commit en el repositorio para todo el equipo. Pon la skill en .claude/skills/ dentro del proyecto y haz git commit. Quien clone el repositorio obtiene esa skill de inmediato - la forma más rápida de estandarizar un proceso para un equipo.
2. Súbela a GitHub para la comunidad. Crea un repositorio de skills; otras personas lo clonan o copian la carpeta de la skill en su propio ~/.claude/skills/. Incluye un README que describa qué hace cada skill.
3. Empaquétala como un plugin. Con varias skills relacionadas, puedes agruparlas en un plugin para una distribución más ordenada (tengo un artículo aparte sobre plugins de Claude Code).

Extra: las skills usan un estándar abierto (Markdown + front matter YAML), así que un SKILL.md escrito para Claude Code suele ser reutilizable, o fácilmente convertible, en otras herramientas como Cursor o Copilot - escríbelo una vez, úsalo en muchos lugares.

¿No quieres escribir las tuyas? Usa más de 108 skills prediseñadas

Escribir tus propias skills es una habilidad que vale la pena aprender - te da control total para ajustar todo a tu flujo exacto, y se lo recomiendo a cualquiera que use Claude Code en serio. Pero si quieres un conjunto de skills listo para producción ahora mismo, sin construir cada una, el Engineer Kit trae más de 60 skills prediseñadas (frontend, backend, base de datos, DevOps, code review) y es un atajo que vale la pena considerar.

Toma el atajo: el paquete de skills prediseñadas de AgentKit — ahora $149 (antes $198) reúne más de 108 skills para Claude Code - usables de inmediato en vez de escribir cada archivo tú misma. Siendo honesta: aún deberías saber escribir skills (como en este artículo) para personalizar las partes especializadas; el kit se encarga del trabajo repetitivo de base.

Preguntas frecuentes (FAQ)

¿En qué se diferencia una skill de un subagent?

Una skill es un paquete de instrucciones que Claude Code carga en el contexto actual cuando el contexto coincide, ejecutándose en la misma sesión. Un subagent es un subasistente que ejecuta tareas pesadas en su propio contexto separado, de forma independiente. El trabajo ligero y repetible va a una skill; el trabajo grande que necesita aislamiento va a un subagent.

¿Dónde va el SKILL.md?

Ponlo en ~/.claude/skills/<name>/SKILL.md si lo quieres en todos los proyectos (personal), o en .claude/skills/<name>/SKILL.md dentro de un repositorio si quieres versionarlo y compartirlo con el equipo (proyecto). Cada skill es su propia carpeta que contiene un archivo SKILL.md.

¿Por qué mi skill no se ejecuta automáticamente?

Normalmente porque la description es vaga y le faltan las palabras clave que de verdad dices en tu prompt. Comprueba también: si el front matter YAML tiene un error de sintaxis, si has reiniciado Claude Code, y si la ruta de la carpeta es correcta.

¿Necesito reiniciar después de crear o editar una skill?

Sí. Claude Code solo escanea la carpeta de skills al arrancar, así que después de crear o editar SKILL.md necesitas hacer /exit y volver a abrir la sesión para que la skill se cargue.

¿Una skill escrita para Claude Code también se puede usar con claude.ai?

El estándar de skill (Markdown + front matter YAML) es abierto, así que el contenido suele ser reutilizable. Sin embargo, la carga es distinta: Claude Code usa una carpeta de archivos local (~/.claude/skills/), mientras que la app web claude.ai las carga a su manera. Trata un archivo SKILL.md como un activo reutilizable, no como algo idéntico y listo para enchufar en todas partes.

¿Hay skills listas que pueda usar ya mismo?

Sí. Si no quieres empezar desde cero, kits como AgentKit reúnen más de 108 skills para Claude Code en muchos dominios. Aún deberías saber escribir las tuyas para personalizar, pero un kit te ahorra el trabajo repetitivo de base.

Conclusión + próximos pasos

Las skills personalizadas son la forma más eficaz de "enseñarle" a Claude Code a trabajar exactamente a tu estándar sin repetir prompts. Empieza en pequeño: elige un flujo que hagas cada semana, destílalo en un SKILL.md, escribe una description muy clara, prueba e itera. Lee qué son las Skills de Claude Code a continuación para afianzar los fundamentos, y slash commands en Claude Code para combinar skills con atajos deliberados. Y cuando necesites un conjunto de skills listo para producción ya, en vez de escribir cada una, considera un kit prediseñado (mira el recuadro de abajo).

Fuentes: Claude Code Docs - Skills (Anthropic, actualizado en 2026) para la estructura de SKILL.md y el mecanismo de carga. Las skills son una función en evolución; los detalles pueden cambiar entre versiones.