Cómo crear una skill con Claude Code que tu agente realmente use

1. Detecta el último tag con git describe --tags --abbrev=0.
   Si no hay tags, usa el primer commit del repo (git rev-list --max-parents=0 HEAD).

2. Lista los commits desde ese punto:
   git log <tag>..HEAD --pretty=format:"%s|%h|%an"

   Si el repo tiene el script scripts/parse-commits.sh, úsalo en su lugar —
   ya devuelve los commits agrupados por tipo.

3. Clasifica cada commit por su prefijo (Conventional Commits):

   • feat: → Added
   • fix: → Fixed
   • refactor:, perf:, chore: → Changed
   • Cualquier otro → Otros cambios (inclúyelo, no lo descartes)

4. Redacta cada línea en español, orientada al usuario final, no al código.
   "feat: add retry logic to http client" se convierte en
   "El cliente HTTP ahora reintenta automáticamente las peticiones fallidas."

5. Genera la sección nueva del changelog:

   [Sin publicar] – AAAA-MM-DD

   Added

   • …

   Fixed

   • …

   Changed

   • …

6. CHECKPOINT — antes de tocar el archivo, muéstrame la sección generada
   en el chat y espera mi confirmación explícita. Este paso es obligatorio:
   CHANGELOG.md está versionado y no quiero sorpresas.

7. Si confirmo, inserta la sección arriba de la última entrada en
   CHANGELOG.md. Si pido cambios, ajusta y vuelve al paso 6.

8. No hagas commit ni push. Termina mostrando el diff del archivo.

Y el script de soporte, `scripts/parse-commits.sh` — opcional, pero le ahorra a Claude tener que interpretar el output crudo de `git log`:

```bash
#!/usr/bin/env bash
set -euo pipefail

TAG=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)

git log "${TAG}..HEAD" --pretty=format:'%s' | while read -r line; do
  case "$line" in
    feat:*)     echo "ADDED|${line#feat: }" ;;
    fix:*)      echo "FIXED|${line#fix: }" ;;
    refactor:*) echo "CHANGED|${line#refactor: }" ;;
    chore:*)    echo "CHANGED|${line#chore: }" ;;
    *)          echo "OTHER|${line}" ;;
  esac
done

Con esto guardado, escribo en el chat "prepara las notas de la release" y Claude Code hace el resto: detecta la skill por la description, corre el script, clasifica, redacta, y me para en seco antes de tocar un archivo versionado.

Buenas prácticas que aprendí a la fuerza

Pon checkpoints en todo lo irreversible. Escribir un archivo, hacer push, mandar un mensaje a Slack, borrar algo — cualquier paso caro de deshacer necesita una confirmación explícita en medio de la skill, no al final. Es la diferencia entre revisar un preview y descubrir el desastre ya en producción.

Deja que la skill delegue en un subagente cuando el trabajo es pesado. Si un paso implica investigar, leer decenas de archivos o generar contenido largo, no lo hagas inline: invoca un subagente especializado para esa parte. Mantiene limpio el contexto de la conversación principal y evita que la skill se vuelva un monstruo de 300 líneas.

Prueba la skill en conversación real antes de darla por terminada. Escribe la description, úsala tres o cuatro veces con frases distintas y fíjate en cuándo se activa y cuándo no. Ajusta el texto según lo que veas, no según lo que creas que debería pasar. Es la misma lógica de iteración que enseño en el curso Construye con IA: no escribes la spec perfecta a la primera, la afinas contra el comportamiento real del agente.

Hay un nivel más adelante: agentes que escriben sus propias skills en caliente cuando se topan con un problema nuevo, sin que tú definas nada de antemano. Así funciona el Self-Improving Loop de Hermes Agent — pero esa es una capa distinta a la que cubrimos hoy, donde eres tú quien define el proceso.

Skills, comandos y subagentes: cuándo usar cada uno

No son excluyentes. Mi skill del changelog podría, en un paso intermedio, delegar en un subagente que revise el tono de cada línea antes de mostrarme el preview. Se combinan.

Qué hacer con esto hoy

Abre un proyecto donde repitas algo cada semana. Escribe el SKILL.md con una description que incluya las frases exactas que usarías para pedirlo, y un "NO la uses para" explícito. Pruébala tres veces antes de confiar en ella.

Si el proceso involucra tocar código, escribir archivos o correr comandos, mete un checkpoint. Siempre. La skill que no para a preguntar es la skill que un día te rompe algo en silencio.

Si quieres ver más skills reales que uso en producción — no solo la del changelog — las voy soltando en Dominicode Labs. Y si prefieres verlo en pantalla en vez de leerlo, en el canal de YouTube tengo el mismo flujo grabado de principio a fin.

Preguntas frecuentes

¿Cuál es la diferencia entre una skill y un subagente en Claude Code?

Una skill inyecta sus instrucciones en la conversación que ya tienes abierta — no aísla nada. Un subagente corre en una ventana de contexto separada, con su propio system prompt y su propio set de herramientas. Usas una skill para aplicar un proceso o conocimiento de forma consistente; usas un subagente para delegar una tarea larga o ruidosa que ensuciaría el contexto principal. Y una skill puede invocar a un subagente dentro de sus propios pasos — no son excluyentes.

¿En qué se diferencia una skill de un comando slash en Claude Code?

En quién decide invocarla. Un comando slash (.claude/commands/*.md) lo disparas tú a propósito, escribiendo /nombre-del-comando. Una skill la dispara Claude solo, cuando el contexto de la conversación coincide con lo que describe su description en el frontmatter. Si necesitas control total sobre cuándo se ejecuta algo, usa un comando. Si quieres que el agente aplique un proceso sin que se lo tengas que pedir cada vez, crea una skill.

¿Dónde debo guardar mis skills, en el proyecto o de forma global?

Si la skill depende de convenciones específicas de un repo — como el formato exacto del changelog de ese proyecto — guárdala en .claude/skills/ dentro del repo. Si es un proceso que repites en todos tus proyectos (auditar accesibilidad, generar tests, revisar una spec), ponla en ~/.claude/skills/ para que esté disponible en cualquier sesión.

¿Cómo sé si Claude realmente activó mi skill y no está improvisando?

Claude Code indica cuándo carga una skill durante la conversación. Si pides algo que debería activarla y no ves esa señal, es casi siempre un problema de description: o es demasiado vaga, o compite con otra skill que describe algo parecido.

¿Puedo tener dos skills que se superpongan en tema sin que se pisen?

Puedes, pero no deberías. Si dos descriptions cubren un terreno similar, Claude tiene que decidir entre ambas y a veces se equivoca. Es mejor una sola skill bien delimitada que dos que compiten por el mismo trigger.

¿Una skill puede invocar a un subagente dentro de sus instrucciones?

Sí. Puedes escribir un paso que diga explícitamente "delega esta parte en el subagente X" y Claude lo hace como parte del flujo de la skill. Es la combinación que uso cuando un paso requiere investigación o generación larga sin ensuciar el contexto principal.

¿Las skills reemplazan al archivo CLAUDE.md del proyecto?

No. CLAUDE.md es contexto general que Claude lee siempre — arquitectura, convenciones, comandos del proyecto. Una skill es un proceso puntual que se activa solo cuando aplica. Uno da contexto permanente, la otra ejecuta un flujo específico. Se complementan, no se sustituyen.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.