La primera skill útil para escribir

En el post anterior sobre cómo escribir un buen CLAUDE.md había una frase que salía varias veces: eso no va en el archivo CLAUDE.md, eso es una skill.

Los siete pasos para publicar una release, el repaso antes de abrir una pull request. Todo lo que solo hace falta de vez en cuando y que no debería estar ocupando contexto en cada sesión.

El siguiente capítulo del curso Claude Code in Action de Anthropic va justo de eso y de una skill concreta que recomienda escribir antes que ninguna otra que es la que comprueba el trabajo hecho.

El problema ahora es que la comprobación depende de que te acuerdes de hacerla

Piensa en cómo revisas ahora lo que hace Claude Code, si es que lo haces. Le pides una refactorización y termina, y a partir de ahí te toca a ti. Le dices que ejecute los tests y te lees el diff para comprobar que no la haya liado.

Compruebas y lees el diff cuando te acuerdas y cuando tienes tiempo, el día que no pues seguramente lo que haya hecho tiene autovía directa hacía producción, y ahí tenemos un problemita.

Y aún así hay una segunda trampa, que sería aceptar: los tests pasan, escrito en la respuesta de Claude Code, no es lo mismo que haber visto la salida del comando. Claude es perfectamente capaz de decírtelo con toda la confianza del mundo sin haberlos ejecutado, y tu te lo acabarías creyendo.

Una skill de verificación quita las dos cosas de en medio. La comprobación deja de ser algo que tú pides y pasa a ser algo que se dispara sola cuando el trabajo encaja con su descripción.

Una skill es una carpeta

Antes de entrar en la de verificación conviene saber qué estamos montando, que suena a más de lo que es. Una skill es una carpeta con un SKILL.md dentro y ya está.

.claude/skills/
└── verificar-cambios/
    └── SKILL.md

Y ese archivo lleva un frontmatter con dos campos al comienzo y el procedimiento debajo.

---
name: verificar-cambios
description: Comprueba los cambios de código antes de darlos por terminados. Ejecuta los tests, revisa el diff y confirma que no se ha aflojado ninguna comprobación.
---

# Verificar cambios

1. Ejecuta `npm test` y pega la salida real.
etc etc

La description es la parte que decide si la skill sirve para algo, porque es lo que Claude Code lee para saber cuándo activarla. Si pones comprueba cosas, no se va a activar nunca. Si describes la situación en la que quieres que entre, entra sola.

Lo interesante de todo esto es que al arrancar la sesión solo se cargan los nombres y las descripciones de tus skills. El cuerpo del archivo no entra en el contexto hasta que la skill se usa de verdad. Es decir, puedes tener veinte procedimientos guardados y lo que pagas por tenerlos ahí son veinte líneas.

Con CLAUDE.md no pasa eso, que entra entero y desde el principio. Por eso el criterio del capítulo anterior sigue valiendo, ya que si has escrito dos veces la misma instrucción de varios pasos, ahí tienes una skill.

Lo que hace la skill de verificación

El flujo es siempre el mismo. Le pides el cambio, termina, y como lo que ha hecho encaja con la descripción, la skill se activa sin que digas nada y a partir de ahí:

1. Ejecuta la batería de tests.

2. Lee el diff de lo que se ha modificado.

3. Comprueba que ningún test se haya aflojado para que las cosas pasen.

4. Informa de si va bien o mal, y enseña las pruebas.

El tercer paso es el que de verdad justifica montar esto. Los otros tres los podrías pedir a mano cualquier día, pero ese no se te ocurre pedirlo porque acabas confiando en que no se van a trampear los tests.

Porque los tests en verde no significan nada por sí solos y menos si por detrás está una IA. Un test se puede relajar hasta que pase siempre. Cambiar un toBe por un toBeTruthy, meter un .skip en el caso que molestaba, borrar el assert que fallaba y dejar el resto, ampliar el margen de una comparación numérica hasta que quepa el resultado nuevo. Todo eso deja la suite verde y no arregla nada.

Importante

Terminado NO es "el diff tiene buena pinta". Terminado es que las comprobaciones se han ejecutado, alguien ha mirado el resultado y ese resultado está escrito en la conversación.

Para este blog la skill sería algo así:

---
name: verificar-cambios
description: Verifica los cambios del blog antes de darlos por terminados. Ejecuta build, chequeo de tipos y tests, y revisa el diff en busca de comprobaciones debilitadas.
---

# Verificar cambios

Ejecuta estos comandos en orden y pega la salida real de cada uno:

1. `npm run build`
2. `npx astro check`
3. `npm test`

`astro check` devuelve un error conocido en `PasswordStrengthDemo.astro`. Ese se ignora.
Cualquier otro error cuenta como fallo, incluidos los de los posts.

Después revisa el diff completo:

- Ningún test puede quedar con `.skip`, comentado ni con asserts eliminados.
- Si un test se ha modificado, explica por qué el comportamiento esperado ha cambiado.

Termina con VERIFICADO o FALLA, y en caso de fallo indica el comando y el error concreto.

Fíjate en lo del error conocido, porque ese detalle es lo que hoy vive en tu mente y tienes que explicar cada vez que Claude se encuentra con él. En la skill solo se explica una vez.

La carpeta admite más cosas que el SKILL.md

Puedes dejar un referencia.md al lado y enlazarlo desde el SKILL.md. Claude Code solo lo abre cuando necesita ese nivel de detalle, así que el archivo principal se queda corto y la explicación larga sigue estando disponible para cuando haga falta.

Y puedes meter scripts en la carpeta. Un script no se carga en el contexto, solo se ejecuta. Toda la lógica que quepa en un check.sh deja de ser texto que Claude tiene que leer e interpretar y se convierte en un comando con su código de salida.

.claude/skills/verificar-cambios/
├── SKILL.md
├── referencia.md
└── check.sh

El SKILL.md dice qué hay que hacer, y lo pesado (las explicaciones largas y las herramientas) está en archivos de al lado.

Tres sitios donde poner una norma

Con esto ya tenemos tres superficies para dar instrucciones y es fácil hacerse un lío. Yo lo separo así.

Va en	Qué	Ejemplo
CLAUDE.md	Convenciones que aplican siempre	Dónde viven los componentes, qué gestor de paquetes
Una skill	Procedimientos y referencia de una tarea concreta	Cómo se verifica, cómo se publica una release
Un hook	Lo que no se puede saltar bajo ningún concepto	No hacer push a main, pasar el formateador

CLAUDE.md y las skills son instrucciones que Claude Code sigue y un hook es código que se ejecuta. Si el hecho de que se salte la norma un día entre veinte te parece asumible, escríbela. Si no lo es, no la dejes en manos de un Markdown.

Lo que me llevo del capítulo

Que la primera skill sea la de verificación tiene sentido por algo que poco tiene que ver con lo técnico. Las demás te ahorran escribir. Esta te puede ahorrar commits bobos.

Y como es una carpeta dentro del repositorio, la comparte todo el equipo. La verificación deja de depender de si el que estaba delante ese día le picaba y miró el diff.

Yo la voy a escribir para el blog esta semana, además seguro que se me ocurre alguna más para ahorrarme trabajo y hacer más robusto lo que hago día a día, que al final en eso consiste.

EA! Nos vemos en los bares! 🍻