Dirijo un equipo de desarrollo que lleva prácticamente un año viviendo dentro de Claude Code. Y no hablo de ese tipo de “lo probamos durante un sprint” y ya está. Hablo de que nuestro CI corre sobre Claude Code y nuestras plantillas de pull request son en realidad prompts de Claude. En algún momento de ese camino, me puse ambicioso. Creé un set de skills personalizadas para el equipo: `code-review`, `debug-protocol` y `team-conventions`. Están en `.claude/skills/`, se ven preciosas, tienen todo el frontmatter YAML que puedas soñar… y durante las primeras semanas, se quedaron ahí sentadas. Calladas. Ignoradas. Como una alarma de incendios que solo suena cuando ya hay fuego.
Lo más frustrante era que los archivos de las skills estaban bien. Las rutas eran correctas. El markdown estaba limpio y documentado de maravilla. La skill simplemente nunca se activaba. Después de meses tirándome de los pelos, por fin entendí la verdad: la culpa no era de la skill. Era mía.
La trampa de la “skill que no se activó”
Para quien todavía no haya mirado al abismo de la configuración de skills de Claude Code, va la versión corta: las skills son carpetas dentro de `.claude/skills/
```markdown
---
name: code-review
description: Úsala cuando el usuario pida una revisión de código.
---
```
Eso parece inofensivo. Pero la forma en que Claude Code decide si activar una skill es leyendo *todas* las descripciones, mezclándolas en su system prompt, y comparando tu solicitud actual contra ellas. En otras palabras, la activación de una skill es básicamente un juego de coincidencia de intenciones. Y si escribes tu descripción como un disparador literal de palabras clave, el juego está amañado desde el principio.
Pasamos tres semanas echándole la culpa a Claude, a la API, a la fase de la luna. Luego leímos la documentación oficial de skills en [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) y nos dimos cuenta de algo incómodo: el modelo no es perezoso, es literal. Solo puede activar una skill que *reconoce* como relevante a partir de la descripción. Y nuestras descripciones eran pésimas.
El problema real: la descripción no coincide
Esto nos costó muchísimo entenderlo: **la skill no existe en el vacío.** Existe en una sopa de otras skills, comportamientos integrados y todo lo demás que haya en el contexto de Claude. Cuando un desarrollador escribe algo, Claude hace un cálculo mental rápido: *"¿Esto coincide con alguna descripción de skill? Si coinciden varias, ¿cuál es la más cercana? ¿Mejor respondo directamente?"*
Si tu descripción es demasiado estrecha, demasiado vaga o demasiado centrada en palabras clave, Claude no la va a ver. Y si tu descripción choca con otra skill o con un comando integrado, Claude elegirá la equivocada. El código dentro de tu `SKILL.md` nunca es el problema. El metadata es el problema.
Estas son las tres formas más grandes en las que esto muerde a equipos reales.
Escenario 1: La skill de code review que se quedaba dormida
Escribí nuestra skill `code-review` con la descripción más obvia del mundo: *"Úsala cuando el usuario pida una revisión de código."* Sencillo, ¿no? Pues no.
Nuestros desarrolladores nunca decían "code review". Decían:
- "¿Me puedes hacer una revisión rápida de mi PR?"
- "Mira este diff, algo anda mal."
- "Revísame esto antes de que lo despliegue."
- "¿Esto está sobre-diseñado?"
¿Adivina cuál activó la skill? Ninguna. Claude respondía directamente sin invocar la skill porque la frase "code review" nunca aparecía en el mensaje. El arreglo fue ridículamente simple. Reescribimos la descripción para que fuera semántica, no literal:
```yaml
description: >-
Úsala para revisar cambios de código, pull requests, diffs o merge requests.
Se activa con frases como "revisa este PR", "checa mi diff", "valida este
código", "¿esto está listo para merge?" o "mira estos cambios".
No es para depuración general ni para explicar código.
```
También añadimos una cláusula de "No es para". Ese único cambio hizo que la skill se activara aproximadamente un 80% más seguido. Las skills de Claude Code son fundamentalmente prompt engineering — y el prompt es la descripción.
Escenario 2: El protocolo de depuración que nos fantasma
Nuestra skill `debug-protocol` se suponía que sería la heroína del equipo. Un proceso estructurado, paso a paso, para reproducir bugs, revisar logs, inspeccionar estado y proponer arreglos. Era hermosa. También nunca se activó.
¿Por qué? Porque la descripción empezaba con la palabra "debug". Y "debug" está en todos lados dentro de Claude Code. Hay un flag integrado de debug, hay comportamiento de depuración a nivel de sistema, y seguramente hay otras tres skills en el mismo directorio usando lenguaje similar. Cuando nuestros desarrolladores decían "ayúdame a depurar este test que falla", Claude tenía cuatro coincidencias plausibles y elegía la que tuviera la relevancia *general* más fuerte en el prompt — normalmente el comportamiento integrado, no nuestra skill personalizada.
De aquí aprendimos dos lecciones:
1. **Dale a las skills nombres únicos y específicos.** `debug-protocol` es muy genérico. `sentry-repro-protocol` o `memory-leak-hunt` habrían sido mucho mejores. Los nombres genéricos pierden contra la intención genérica.
2. **Usa el override manual.** En Claude Code, siempre puedes escribir `/debug-protocol` para forzar que una skill se ejecute. Agregamos eso a las convenciones de nuestro equipo, y de pronto la skill no estaba muerta — solo necesitaba una invitación directa.
Pero la idea más profunda es esta: el modelo eligió la skill equivocada porque *nosotros* diseñamos una colisión. Si tienes dos skills que suenan parecido, Claude va a adivinar. Haz que las descripciones se descalifiquen entre ellas. Dile a Claude explícitamente: "usa esta en lugar del comportamiento general de depuración cuando el problema involucre logs del servidor."
Escenario 3: La skill de convenciones del equipo que lo olvidaba todo
El fallo más raro vino de nuestra skill `team-conventions`. Ahí vivían las reglas para mensajes de commit, nombres de ramas y descripciones de PR. Funcionaba perfectamente al inicio de la sesión, y luego se apagaba alrededor del mensaje 20. Asumimos que el modelo estaba "olvidando". No era un bug de memoria — era contexto.
Claude Code mete todas las descripciones de skills en el system prompt. Las descripciones largas consumen contexto. Y cuando la conversación crece, el sistema empieza a comprimir o truncar el system prompt para hacer espacio. La descripción de `team-conventions` era un muro de texto — tres párrafos de jerga corporativa. Fue lo primero que se lanzó por la borda cuando el contexto se puso apretado.
El arreglo fue reducir la descripción a dos o tres frases y mover las reglas reales a un archivo referenciado dentro de la carpeta de la skill. Ahora la descripción es solo un letrero: *"Úsala para mensajes de commit, nombres de ramas y convenciones de PR. Reglas completas en convention.md."* El modelo puede retener eso, y cuando la skill se activa, lee el archivo completo. También movimos reglas que no eran de skills a nuestro archivo de memoria `CLAUDE.md`, que se carga de forma más confiable para instrucciones de todo el equipo.
Arreglos prácticos que puedes aplicar hoy
Después de semanas de dolor, esta es la lista que me hubiera encantado que alguien me diera el primer día.
Trata la descripción como una consulta de búsqueda
Si alguien buscara tu descripción de skill, ¿coincidiría con lo que realmente quieres? Escribe la descripción como si fuera una cadena de búsqueda semántica. Incluye sinónimos, frases reales que usa tu equipo, y exclusiones explícitas. No asumas que el modelo "sabe lo que querías decir". Solo sabe lo que escribiste.
Mantén los archivos de skill ligeros
Un archivo de skill de 500 líneas es un pasivo. Consume contexto, se trunca, y se vuelve poco confiable. Mantén el `SKILL.md` enfocado en la *decisión* de cuándo activarse. Mete los detalles pesados en archivos auxiliares — `prompt.md`, `criteria.md`, `checklist.md` — que Claude solo lee después de que la skill se activa.
Añade ejemplos negativos
Suena contraproducente, pero funciona. En la descripción, di explícitamente para qué *no* es la skill. Escribe: *"No es para discusiones generales de arquitectura. No es para preguntas de sintaxis."* Esto reduce los falsos positivos y además ayuda al modelo a distinguir entre skills similares. Los ejemplos negativos son la herramienta más afilada de la caja.
Usa `/` para el override manual
No importa qué tan bueno sea tu metadata, siempre llegará un momento en que la detección automática falle. Entrena a tu equipo para escribir `/nombre-de-la-skill` cuando necesiten forzar la activación. No es un fracaso — es un plan B. Los equipos más listos tratan la activación automática como una conveniencia, no como una dependencia.
Depúrala como cualquier otro código
Claude Code tiene un flag `--debug`. Úsalo. Inspecciona el system prompt que se arma al inicio de una sesión y confirma que tus descripciones de skills están ahí dentro. Esto suena obvio, pero nosotros descubrimos que una coma al final de uno de nuestros bloques de frontmatter YAML invalidaba silenciosamente el archivo completo. La skill nunca cargaba. No por coincidencia de intención — por un error de parseo. La salida de debug lo atrapó en diez segundos.
Prueba con frases diferentes
No pruebes solo la frase exacta de tu documentación. Abre una sesión nueva y escribe la forma desordenada, humana y ambigua en la que tu equipo habla de verdad. "¿Este PR va a explotar?" debería activar tu skill de review si tus descripciones están bien hechas. Si no lo hace, tu descripción todavía no es suficientemente buena.
FAQ
¿Por qué mi skill funciona en una sesión nueva pero deja de activarse después?
Eso casi siempre es truncamiento de contexto. Las descripciones largas de skills se caen del system prompt conforme la conversación crece. Reduce la descripción, o reestructúrala con un archivo de referencia. No es un problema de memoria — es un problema de espacio.
¿Es mejor usar palabras clave o lenguaje natural en las descripciones de skills?
Ambos, en la proporción correcta. Empieza con una frase semántica que describa la *intención* ("úsala para revisar cambios de código"), y luego agrega una lista de frases comunes que la activen. No dependas solo de palabras clave, pero tampoco seas tan abstracto que nada coincida.
¿Puede una skill personalizada sobrescribir el comportamiento integrado de Claude Code?
No directamente. Los comportamientos integrados están conectados en un nivel que tu skill no puede sobrescribir. Pero puedes ganar la partida haciendo que tu descripción sea más específica y relevante para la situación real de tu equipo. Si estás atascado, usa `/nombre-de-la-skill` para forzarla, o reformula la solicitud para que el camino integrado ya no encaje.
¿Cómo sé si mi archivo de skill siquiera está cargando?
Ejecuta `claude --debug` e inspecciona la salida. Deberías ver tus skills listadas en el ensamblado del system prompt. Si tu skill no aparece, revisa el frontmatter YAML, la estructura de carpetas y el nombre del archivo. Una carpeta de skill sin un `SKILL.md` válido es solo decoración.
La conclusión final
Aquí va la verdad incómoda: cuando una skill no se activa, el archivo de la skill casi nunca es el problema. El problema es qué tan bien tradujiste la intención humana — "revisa mi trabajo, sigue nuestras reglas, arregla este bug de la forma en que acordamos" — al metadata que Claude realmente lee. No se trata de escribir mejor código. Se trata de escribir mejores *letreros*.
Si estás frustrado con tus skills silenciosas, no reescribas tu markdown desde cero. Reescribe tus descripciones. Añade ejemplos reales. Añade exclusiones. Mantén el archivo ligero. Y cuando todo lo demás falle, escribe `/nombre-de-la-skill` directamente y sigue con tu día.
La skill no está rota. Y aunque no lo creas, Claude tampoco. Solo se nos olvidó que al modelo hay que invitarlo a la fiesta con algo más que un gesto vago desde el otro lado de la sala.
Comments (0)
No comments yet. Be the first to comment!
Leave a Comment