Claude Code ignoró mi skill 5 veces. 1 línea lo arregló

Una skill de Claude Code puede funcionar perfectamente cuando escribes su nombre y no cargarse nunca cuando pides lo mismo con palabras normales. La nuestra se ejecutó siempre que escribimos su nombre y se ignoró siempre que pedimos la misma tarea en lenguaje corriente. Vimos cómo se ignoraba, leímos por qué y reescribimos la única línea que lo arregló.

Una skill es un conjunto de instrucciones guardado que Claude Code recoge por su cuenta cuando tu petición encaja. Lo que decide el encaje es una línea que Claude lee antes de elegir, y no son tus instrucciones. Los seis pasos de abajo te llevan del prompt que no dejas de reescribir a una skill que se carga sola, más una prueba de veinte peticiones que detecta una skill ignorada antes de que lo haga tu equipo.

Prueba (misma petición, sesiones nuevas)	Skill cargada
Llamada por su nombre (/release-notes)	2 de 2
Palabras normales, descripción original	0 de 5
Palabras normales, descripción reescrita	5 de 5

Una skill es una carpeta con un único archivo dentro, SKILL.md. El archivo empieza con una cabecera corta (un nombre y una descripción de una frase) seguida de las instrucciones. Funciona como una función: quien llama lee la firma y el docstring, y el cuerpo solo se ejecuta cuando se la llama. Guárdala en tu carpeta personal para tenerla en todos los proyectos, o dentro del repositorio para que la tenga todo el que trabaje allí.

Empieza por la tarea, no por el archivo. Elige el prompt que no dejas de reescribir y anota el resultado exacto que quieres. El nuestro eran las notas de versión semanales: los commits desde el lunes, agrupados por área, sin las tareas de mantenimiento, una línea por cambio con el número de su pull request. En el repositorio open source Hono, ese prompt largo produjo notas limpias para ocho correcciones de bugs de esa semana, y ese resultado se convirtió en el objetivo que la skill tenía que alcanzar.

No todos los prompts merecen una skill. Una pregunta puntual no, y una skill que nunca reutilizas es una línea más que Claude tiene que leer. Guarda una lista corta de los prompts que escribes cada semana; el que está arriba se convierte en tu primera skill.

Crea .claude/skills/release-notes/SKILL.md en tu proyecto: una carpeta skills dentro de la carpeta oculta .claude, una carpeta con el nombre de la skill y el archivo de la skill dentro. La carpeta importa. Un release-notes.md suelto no se carga en absoluto, y la documentación lo señala como lo primero que hay que comprobar.

La cabecera son unas pocas líneas con etiquetas entre dos filas de guiones, y debe empezar en la primera línea del archivo, o Claude Code la ignora. La nuestra tenía un nombre, release-notes, y la descripción que escribiría la mayoría de la gente:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Bajo la cabecera van las instrucciones como pasos numerados, los que le darías a un compañero nuevo. Las nuestras tienen cinco: encontrar los commits desde el lunes, descartar los commits chore y docs, agrupar por ámbito de commit convencional, escribir una línea sencilla por cambio y devolver un bloque con título y un breve resumen arriba. Anthropic recomienda mantener esta parte corta. No hace falta reiniciar: Claude Code recoge una skill nueva o editada en la sesión en la que ya estás.

Pruébala por nombre: escribe una barra, elige la skill en el menú y pulsa enter. En sesiones nuevas, la nuestra leyó el registro de commits, agrupó las correcciones por área y escribió las notas exactamente como queríamos, siempre. El problema es que tú, y todo tu equipo, tenéis que acordaros de su nombre.

Un compañero no escribirá el nombre de la skill. Abrirá una sesión nueva y pedirá las cosas como te las pediría a ti. Así que prueba eso: abre una sesión nueva (una conversación nueva sin nada cargado) y pide la tarea con tus propias palabras. Tiene que ser nueva, porque una skill ya usada se queda en la conversación y una prueba en esa sesión no demuestra nada.

Escribimos "what did we ship this week?". Claude ejecutó él mismo el registro de commits y escribió un resumen a su manera, sin rastro de la skill. Las respuestas no eran malas, pero variaban de una ejecución a otra: una contaba desde el lunes, otra desde la última etiqueta de versión y metía un cambio de documentación que la skill habría descartado. En cinco sesiones nuevas, la skill se ignoró en las cinco.

Cinco ejecuciones son una demostración, no una estadística. Pero una skill que funciona por nombre y se ignora siempre con palabras normales no está haciendo su trabajo, y como pasó la prueba por nombre del paso dos, nunca se te ocurriría mirar.

Antes de cambiar una sola palabra, haz tres comprobaciones:

1. /skills lista todas las skills que la sesión puede ver. Busca la tuya. La nuestra aparecía y estaba activada, pero la instalación tenía 277 skills, y varias skills de plugins coincidían con "release" antes que la nuestra.
2. claude --debug escribe un registro detallado de lo que carga Claude Code. Busca las líneas de skills. El nuestro mostraba la skill del proyecto cargada, y también un aviso de que el listado de skills superaba el presupuesto, así que algunas descripciones se recortan.
3. claude plugin validate .claude/skills comprueba que la cabecera está bien formada. Esta importa: una cabecera rota deja que la skill se ejecute por nombre, pero Claude ya no puede encajarla por su cuenta. La nuestra pasó.

Comprobación	Qué te dice	Nuestro resultado
/skills	¿Está visible y activada la skill?	Aparece, activada (277 skills)
--debug	¿Se cargó? ¿Está recortado el listado?	Cargada; aviso de listado fuera de presupuesto
plugin validate	¿Se interpreta bien la cabecera?	Superada

Con el archivo cargado y la cabecera válida, la causa es la descripción. Hasta que decide cargar una skill, Claude no lee tus instrucciones. Lee una línea por skill, el nombre y la descripción, y las compara con tus palabras. La nuestra decía "generates changelog documents from repository history"; la petición decía "what did we ship this week". Las dos frases no comparten ni una palabra. Claude nunca leyó nuestras instrucciones; leyó una línea, y esa línea no usaba nuestras palabras.

El aviso de presupuesto significa que Claude Code recorta las descripciones para que quepan, empezando por las skills menos usadas, y una skill recién creada es la menos usada de todas. Comprueba que la tuya sobrevivió: la nuestra sí, porque las peticiones con sus propias palabras seguían cargándola.

Escribe la descripción para el momento en que alguien pide, no para el archivo. Di qué hace la skill, cuándo usarla y las palabras que la gente escribe de verdad. La nuestra pasó a ser:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

La guía de redacción de Anthropic añade una regla: escríbela en tercera persona ("Writes"), nunca "I can help" ni "You can use this".

Luego compruébalo en una sesión nueva con la misma petición. "What did we ship this week?" cargó ahora la skill antes de que Claude tocara nada, y las notas salieron en nuestro formato, en cinco de cinco sesiones nuevas.

Haz también una línea base: desactiva la skill con un ajuste skillOverrides en tu archivo de ajustes local (la oculta sin borrarla). Desactivada, Claude volvió a su propio resumen; activada, se cargó la skill. La diferencia la hizo la skill, no la suerte.

El límite: una descripción que encaja con demasiado hace que la skill salte donde no debe. Añade las palabras que usas de verdad, no todas las que se te ocurran.

Una petición demostró el arreglo; una skill de la que depende un equipo se pide de muchas formas. El skill-creator de Anthropic describe la prueba: veinte peticiones, una mezcla de las que deben cargar la skill y casi aciertos que no. Un casi acierto suena parecido pero es otro trabajo, como "write a commit message for my staged changes". Ejecuta cada petición en su propia sesión nueva y anota si la skill se cargó. El script del skill-creator no veía la skill en nuestra versión de Claude Code, así que ejecutamos las mismas veinte peticiones con un script corto propio.

Descripción	Peticiones a cargar que la cargaron	Casi aciertos que la cargaron
Original	4 de 10	0 de 10
Reescrita	10 de 10	0 de 10

Antes de la reescritura, la skill solo se cargaba con las peticiones que ya contenían "release notes", "changelog" o "release": la coincidencia por palabras del paso cuatro, a plena vista. Después de la reescritura se cargó con todas las peticiones que debían cargarla y se mantuvo fuera de todos los casi aciertos.

Para una skill que no puede fallar nunca, fuérzala. Escribe su nombre, o añade un hook (un script pequeño que Claude Code ejecuta en un momento fijo, aquí en cada mensaje que envías) cuya salida le diga a Claude que use la skill para esa tarea. Con el hook puesto, incluso la descripción original se cargó con la petición en palabras normales. El límite: cada ejecución de prueba consume uso real y un hook añade una línea a cada mensaje, así que resérvalo para las pocas skills que de verdad deben saltar. Vuelve a ejecutar tu lista cada vez que cambies la descripción.

Nuestra skill de notas de versión funcionó siempre por nombre, se ignoró en todas las sesiones nuevas con palabras normales, y una línea reescrita hizo que se cargara siempre. El motivo: Claude lee una línea por skill antes de decidir, y compara tus palabras, no tus intenciones.

Una skill rinde en una tarea que repites con un resultado fijo: notas semanales, la descripción de una pull request, una checklist de versión. No rinde para una pregunta puntual, y no es la herramienta para una regla que debe cumplirse siempre; eso es trabajo de un hook. Una pila de skills sin usar también cuesta, porque con demasiadas Claude Code empieza a recortar descripciones, las menos usadas primero. Una buena descripción sube las probabilidades, pero no hará saltar una skill para un trabajo para el que nunca se creó, y un puñado de ejecuciones es una demostración, así que tu lista de peticiones de prueba es la comprobación real.

La regla: escribe la descripción con las palabras que escribes de verdad cuando pides la tarea.