Ejemplos de skills de Claude Code: 5 SKILL.md que puedes copiar

Un ejemplo de skill de Claude Code es una carpeta con un archivo SKILL.md: arriba, entre dos líneas ---, un name y una description que dicen qué hace y cuándo usarla; debajo, los pasos en Markdown. Con eso Claude ya puede activarla solo o tú llamarla con /nombre.

Para seguir este post te basta con saber qué es una skill (si no, empieza por qué es una skill y en qué se diferencia de un prompt) y haber abierto alguna vez Claude Code, el asistente de Anthropic que trabaja desde tu terminal. Aquí no repito la teoría: vamos a ver ejemplos de Claude skills enteros, listos para copiar.

Esta es la más corta que me parece útil:

---
name: explicar-codigo
description: Explica un fragmento de código en lenguaje llano para alguien que empieza. Úsala cuando el usuario pregunte qué hace un código o pida que se lo expliquen.
---

1. Resume en una frase qué hace el código.
2. Recórrelo bloque a bloque, sin usar jerga que no hayas explicado.
3. Termina con un ejemplo de entrada y la salida que produce.

Guárdala en .claude/skills/explicar-codigo/SKILL.md y ya existe /explicar-codigo (si la carpeta .claude/skills/ no existía al abrir la sesión, ejecuta antes /reload-skills). Todo lo demás que vas a ver son variaciones sobre esta forma.

Qué enseña cada ejemplo

Cada ejemplo enseña una idea distinta (última columna).

Skill	Para qué	Quién la activa	Qué enseña
mensaje-commit	Mensajes con Conventional Commits	Claude o tú	Inyectar la salida de un comando con !
revisar-pr	Revisar un PR con el checklist del equipo	Claude o tú	Recibir argumentos con $ARGUMENTS
generar-tests	Tests con el estilo del proyecto	Claude o tú	Una skill de solo instrucciones
depurar-error	Encontrar la causa antes de tocar código	Claude o tú	Un procedimiento con bucle
informe-semanal	Informe a partir de los commits	Solo tú	disable-model-invocation y un archivo de apoyo

Cinco skills de Claude Code que puedes copiar

Todas siguen el formato de la documentación oficial ^[1] y su frontmatter pasa un parser YAML.

1. Mensajes de commit con convención

Para que todos los commits sigan la misma convención sin tener que recordarla (qué hace bueno a un mensaje lo tienes en buenas prácticas para mensajes de commit).

---
name: mensaje-commit
description: Redacta mensajes de commit con Conventional Commits a partir de los cambios en staging. Úsala cuando el usuario pida hacer un commit, escribir un mensaje de commit o revisar qué hay en staging.
allowed-tools: Bash(git diff *) Bash(git status *)
---

## Cambios en staging
!`git diff --staged --stat`

## Cómo escribir el mensaje
1. Si no hay nada en staging, dilo y para. No hagas `git add` por tu cuenta.
2. Elige el tipo: feat, fix, docs, refactor, test o chore.
3. Primera línea: `tipo(ámbito): resumen en imperativo`, máximo 72 caracteres.
4. Cuerpo opcional: el porqué del cambio, no el qué.
5. Enseña el mensaje y espera mi confirmación antes de ejecutar `git commit`.

Por qué funciona: el staging es lo que ya has preparado con git add, y la línea que empieza por ! ejecuta git diff --staged --stat antes de que Claude lea la skill y su salida sustituye a la línea, así que Claude recibe los cambios reales ^[1]. allowed-tools aprueba esos comandos durante el turno en que invocas la skill (tu mensaje y todo lo que Claude hace hasta responderte); si un comando inyectado no está permitido, la invocación se aborta y Claude no llega a leer la skill. git commit se queda fuera a propósito: Claude te sigue pidiendo permiso antes de commitear. La forma tipo(ámbito): descripción y los tipos feat y fix son de Conventional Commits, que admite tipos adicionales como docs o chore ^[2].

2. Revisar un PR con tu checklist

Si en tu equipo revisáis pull requests siempre con las mismas preguntas, esas preguntas piden ser una skill.

---
name: revisar-pr
description: Revisa un pull request de GitHub con el checklist del equipo y devuelve hallazgos por prioridad. Úsala cuando el usuario pida revisar un PR o una pull request de GitHub antes de aprobarlo.
argument-hint: "[número-de-pr]"
allowed-tools: Bash(gh pr diff *) Bash(gh pr view *)
---

Revisa el PR $ARGUMENTS.

1. Lee la descripción con `gh pr view $ARGUMENTS` y el diff con `gh pr diff $ARGUMENTS`.
2. Pasa este checklist, en orden:
   - ¿El cambio hace lo que dice la descripción?
   - ¿Hay tests para el comportamiento nuevo?
   - ¿Se cuela algún secreto, `console.log` o código comentado?
   - ¿Algún nombre obliga a leer el cuerpo para entenderlo?
3. Devuelve los hallazgos en dos grupos: "Bloquea el merge" y "Sugerencia".
4. Cada hallazgo lleva archivo, línea y una propuesta concreta.
5. No apruebes ni comentes en GitHub: solo informa.

Por qué funciona: con /revisar-pr 42, Claude Code sustituye cada $ARGUMENTS por 42 ^[1]; argument-hint es solo la pista del autocompletado. Necesitas la CLI gh instalada y autenticada. El paso 5 es el que más agradezco, porque un comentario publicado en tu nombre en el PR de un compañero, sin que lo hayas leído, es justo lo que no quieres.

3. Generar tests con el estilo del proyecto

Sin campos especiales: solo instrucciones, que es lo normal en la mayoría de skills.

---
name: generar-tests
description: Escribe tests unitarios con Vitest siguiendo las convenciones del proyecto. Úsala cuando el usuario pida tests para una función o un módulo.
---

1. Busca un test existente cerca del archivo y copia su estilo (imports, nombres, mocks).
2. Escribe un `describe` por función y un `it` por comportamiento.
3. Cubre el caso feliz, al menos un caso límite y un caso de error.
4. Nombra cada test con lo que comprueba: `it('devuelve 0 si la lista está vacía')`.
5. Ejecuta `npx vitest run <archivo>` y no des la tarea por terminada hasta que pase.

Por qué funciona: el paso 1 hace que Claude imite tu repo (también sus mocks, las piezas falsas que sustituyen a una dependencia real en un test) en vez de su idea genérica de un test, y el paso 3 le pide al menos un caso límite (una entrada en el borde, como una lista vacía). El paso 5 le da una condición objetiva de terminado. ¿Usas Jest o pytest? Cambia la description y el comando del paso 5.

4. Depurar un error con un procedimiento

Cuando pegas un stack trace (la lista de llamadas que lleva hasta el error), la tentación del modelo es arreglar lo primero que ve. Esta skill le obliga a ir por pasos.

---
name: depurar-error
description: Investiga un error o un test que falla con un procedimiento de causa raíz antes de tocar código. Úsala cuando el usuario pegue un stack trace, un mensaje de error o diga que algo ha dejado de funcionar.
---

Sigue estos pasos en orden y no te saltes ninguno:

1. Reproduce el error con un comando concreto. Si no se reproduce, para y pregunta.
2. Lee el mensaje completo y el stack trace. Señala la primera línea que es código nuestro.
3. Escribe una hipótesis en una frase y cómo vas a comprobarla.
4. Compruébala leyendo código o añadiendo un log temporal. Si falla, vuelve al paso 3.
5. Escribe un test que reproduzca el error y comprueba que falla.
6. Arregla con el cambio mínimo y comprueba que el test pasa.
7. Quita los logs temporales y resume: causa, arreglo y test añadido.

Por qué funciona: la description recoge cómo pides ayuda de verdad (“ha dejado de funcionar”, un stack trace pegado) y el paso 4 es un bucle con salida clara. El “no te saltes ninguno” va como instrucción permanente porque Claude Code no relee el archivo en turnos posteriores ^[1].

5. Informe semanal con plantilla

La última no la quiero nunca en automático: un informe se genera cuando yo lo pido.

---
name: informe-semanal
description: Genera el informe semanal de avance del equipo a partir de los commits de los últimos siete días en todas las ramas.
disable-model-invocation: true
allowed-tools: Bash(git log *)
---

## Commits de la semana
!`git log --all --since="7 days ago" --oneline --no-merges`

## Instrucciones
1. Agrupa los commits por tema, no por autor.
2. Rellena la plantilla de [plantilla.md](plantilla.md) sin añadir secciones.
3. Si una sección se queda vacía, escribe "Nada esta semana" en vez de inventar.

La plantilla vive al lado, en .claude/skills/informe-semanal/plantilla.md:

# Informe semanal

## Hecho
- 

## En curso
- 

## Bloqueos
- 

Por qué funciona: con disable-model-invocation: true la descripción ni entra en el contexto de Claude, así que solo corre cuando escribes /informe-semanal ^[1]. Claude lee la plantilla solo cuando la necesita: material largo que no ocupa contexto hasta entonces. Un detalle: --all lee las ramas que tienes en local, incluidas las remotas que hayas traído, así que haz git fetch antes para ver el trabajo de todo el equipo.

El patrón detrás de los cinco ejemplos

Si quitas lo particular, todas tienen la misma anatomía. Una description que dice qué hace la skill y con qué palabras la pediría alguien. Un cuerpo con pasos numerados, cortos y comprobables. Y, cuando hace falta, uno de estos extras: datos inyectados con !, argumentos, permisos de herramientas o un archivo de apoyo.

La guía de Anthropic añade dos detalles: descripción en tercera persona (“Revisa un PR”, no “Puedo revisar tu PR”) y SKILL.md por debajo de 500 líneas, con lo largo en archivos aparte ^[3]. En Claude Code el name es opcional y por defecto toma el nombre de la carpeta, pero si lo escribes en minúsculas, números y guiones, hasta 64 caracteres, la skill también vale en otros productos de Claude ^{[1] [3]}.

Errores que te vas a encontrar

Descripción vaga. “Ayuda con tests” no le dice a Claude cuándo entrar; la descripción tiene que llevar las palabras con las que lo pedirías ^[1].

Una skill para algo que debe aplicarse siempre. Una regla permanente va en CLAUDE.md o en un hook (un comando que Claude Code ejecuta siempre en un evento, lo pida el modelo o no); lo desarrollo en cuándo usar skills, CLAUDE.md o hooks en Claude Code.

Frontmatter roto. Si el YAML no parsea, la skill carga sin metadatos: /nombre sigue funcionando, pero Claude ya no puede emparejar tu petición con la descripción ^[1]. Un dos puntos suelto dentro de la descripción basta para romperlo, así que entrecomíllala si lo lleva.

Cómo crear una skill en Claude Code: dónde guardarla y cómo probarla

Para crear una skill en Claude Code solo necesitas la carpeta y el SKILL.md. Una skill de proyecto va en .claude/skills/nombre/SKILL.md dentro del repo y la comparte todo el equipo al hacer commit. Una personal va en ~/.claude/skills/nombre/SKILL.md y la tienes en todos tus proyectos. Si coinciden los nombres, gana la personal sobre la de proyecto ^[1].

No hace falta reiniciar: Claude Code detecta los cambios en esas carpetas mientras trabajas. La excepción es una carpeta .claude/skills/ que no existía al abrir la sesión: Claude Code aún no la vigila, así que ejecuta /reload-skills para cargarla y repítelo tras cada cambio hasta que reinicies ^[1]. Para probarla:

1. Escribe /skills y comprueba que aparece.
2. Invócala a mano con /nombre para ver que el cuerpo hace lo que esperas.
3. Abre una sesión nueva y pídele la tarea con tus palabras, sin nombrar la skill, para ver si la descripción la activa.
4. Si no entra, reescribe la descripción con esas palabras y repite el paso anterior.

La sesión nueva importa: lo que queda en el contexto mientras escribes la skill tapa los huecos de las instrucciones. Cuando tienes varias skills, herramientas y un bucle de agente a la vez, la pregunta pasa a ser qué pieza usar para cada cosa; eso es lo que practicamos en el curso Patrones Agénticos, componiendo skills, herramientas y bucles con criterio. Y si dudas entre una skill y un servidor MCP para una tarea, tienes la comparación en MCP vs Skills.

Fuentes

1. Extend Claude with skills, Claude Code Docs: formato del SKILL.md, campos del frontmatter, ubicaciones, invocación con /nombre, $ARGUMENTS, inyección con !, allowed-tools, disable-model-invocation, recarga y solución de problemas.
2. Especificación Conventional Commits 1.0.0: estructura tipo(ámbito): descripción y tipos feat, fix y adicionales.
3. Skill authoring best practices, Claude Docs: límites de name y description, descripción en tercera persona, límite orientativo de 500 líneas.

Preguntas Frecuentes

¿Puedo escribir la description de una skill en español?

Sí. La documentación no exige un idioma; mi criterio es escribirla en el idioma en el que vas a pedir las cosas, porque Claude empareja tu petición con ese texto.

¿Qué diferencia hay entre una skill y un comando en .claude/commands?

Los dos crean un /nombre: un archivo .claude/commands/deploy.md y una skill .claude/skills/deploy/SKILL.md dan el mismo /deploy. Los comandos siguen funcionando, pero la documentación recomienda skills para lo nuevo porque admiten archivos de apoyo; con el mismo nombre, gana la skill.

¿Por qué mi skill de Claude Code no se activa sola?

Casi siempre es la descripción: no contiene las palabras con las que lo has pedido. Comprueba también que no tiene disable-model-invocation: true y que el frontmatter parsea; si el YAML está roto, la skill carga sin descripción y Claude no tiene con qué emparejarla.

¿Una skill puede ejecutar comandos sin pedirme permiso?

Además de lo que ya permitan tus reglas de permisos, los que liste en allowed-tools, y solo durante el turno en que la invocas: el permiso se borra con tu siguiente mensaje, y una regla deny o ask tuya sigue mandando. Ese campo se aplica aunque no hayas aceptado la confianza del directorio, así que léelo en cualquier skill que venga en un repo antes de abrir Claude Code en él; el riesgo de fondo lo cuento en skills y MCP como cadena de suministro.

¿Cuánto debería ocupar un SKILL.md?

Lo justo para el procedimiento. Las cinco de este post caben en una pantalla, y la guía de Anthropic pone el techo en 500 líneas; lo que pase de ahí va a archivos aparte que la skill enlaza.