La skill no se dispara, qué comprobar en 10 pasos antes de volver a teclear /comando

Has escrito una skill, está en ~/.claude/skills/<nombre>/SKILL.md, y Claude hace como si no existiera. Dices "échale un vistazo a esa revisión de código" y recibes una respuesta genérica en vez de la lógica de la skill que habías preparado. No es raro. Las skills son un mecanismo probabilístico, no determinista. Claude decide en cada prompt si la descripción del trigger encaja, y eso sale mal más veces de lo que uno cree. Este es el camino de depuración que sigo cuando una skill no arranca.

1. SKILL.md está en el sitio correcto

Primera comprobación. Una skill necesita exactamente esta estructura, ~/.claude/skills/<nombreskill>/SKILL.md. El directorio puede tener más niveles con ficheros de apoyo o scripts, pero el SKILL.md tiene que estar directamente en la raíz de la skill. Si lo has llamado skill.md (en minúscula) o README.md, no se dispara nada. Claude solo escanea SKILL.md con S mayúscula.

Prueba: ls ~/.claude/skills/*/SKILL.md. Si tu skill no sale en la lista, ese ya es el problema.

2. El frontmatter es YAML válido

Las skills se cargan a través del frontmatter. Si el YAML está roto, Claude se salta la skill sin avisar. Asesinos típicos: comillas que no cierran, tabuladores en vez de espacios, comentarios con # en medio de un valor multilínea, indentación mal puesta en allowed-tools.

Comprobación rápida: yq eval ~/.claude/skills/<nombre>/SKILL.md o sencillamente pégalo en un linter de YAML. Si pasa, el frontmatter está bien sintácticamente. Si no tienes yq, abre el fichero en un editor con resaltado de YAML y mira si los colores cuadran.

3. La descripción no es documentación, es el trigger

Aquí está el error principal del que venían el 90 por ciento de mis problemas con skills. La description del frontmatter no es una descripción para personas, es el trigger que Claude lee para decidir si la skill encaja. Si pone "ayuda con temas de código", eso no se dispara limpio nunca, porque "temas de código" es demasiado general.

Escribe en concreto. En vez de "para revisión de código", mejor "use this skill when the user asks to review, audit, or critique TypeScript or JavaScript code for bugs, security issues, or performance problems". Eso es una descripción de trigger, no un texto de marketing. Anthropic lo documenta explícitamente en la página de skills, en la sección de resolución de problemas, y en la práctica es con diferencia la palanca más importante.

4. Comprobar la longitud de la descripción

Las skills tienen un límite de longitud en la descripción. Si escribes en el frontmatter una explicación de 800 caracteres, en algún punto se corta y la parte del trigger se queda fuera. Anthropic lo lista en la sección de resolución de problemas como "skill descriptions are cut short".

Una regla que a mí me funciona: dos frases, la primera dice qué hace la skill, la segunda dice cuándo debe dispararse. Si quieres dar más contexto, eso va en el cuerpo de la skill, no en el frontmatter.

5. Revisar el bloque allowed-tools

Si tu skill pone allowed-tools y ahí hay una herramienta que no existe en el montaje actual, Claude puede rechazar la skill. Caso típico: has permitido Bash y Edit en la skill, pero la sesión va en modo plan, que bloquea Edit. Entonces la skill no se dispara, o se dispara sin poder hacer su trabajo.

Arreglo rápido si no lo tienes claro: comenta allowed-tools temporalmente. Si entonces la skill se dispara, sabes que era el problema de permisos. Después lo vuelves a poner con las herramientas correctas.

6. Modo plan y skills, qué pasa cuando van juntos

Las skills también se disparan en modo plan, pero no pueden escribir ni ejecutar nada. Si tu skill depende de Edit o de Bash, parece que no está corriendo. Sí corre, pero Claude responde en la capa de plan en vez de actuar.

Prueba: desactiva el modo plan con Shift+Tab y manda el mismo prompt otra vez. Si ahora la skill dispara, solo tenías un artefacto del modo plan. Apúntatelo, porque la próxima vez tendrá exactamente la misma pinta que un trigger roto.

7. Probar el prompt de la skill de forma explícita

Si no tienes claro por qué no se dispara la skill, díselo a Claude directamente. "Hay una skill <nombre> en ~/.claude/skills/, mira el SKILL.md y úsala para la siguiente tarea." Con eso te saltas el mecanismo probabilístico del trigger y Claude carga la skill a mano.

Si eso funciona, la skill está técnicamente bien y tu problema es solo la descripción del trigger. Si tampoco funciona, la skill en sí está rota o está en el sitio equivocado.

8. settings.json, mirar si las skills están habilitadas

En ~/.claude/settings.json puede haber un bloque que habilite o deshabilite skills de forma selectiva. Si alguna vez trasteaste con skills.disabled o lo puso un plugin, tu skill puede estar apagada globalmente.

cat ~/.claude/settings.json | grep -i skill. Si ahí hay algo que excluya tu skill, fuera. Los ajustes globales son aquí más habituales que los locales del proyecto, así que si tienes varios montajes de Claude, mira en todos.

9. Conflicto con otras skills

Si tienes tres skills con descripciones de trigger parecidas, puede pasar que Claude escoja la equivocada. Por ejemplo, code-review y security-audit se solapan a menudo, porque una revisión de código casi siempre tiene aspectos de seguridad. Claude dispara entonces unas veces una y otras la otra, y tú piensas que tu skill está rota.

Prueba: desactiva temporalmente las otras skills (renombra SKILL.md a SKILL.md.bak) y manda el prompt otra vez. Si ahora tu skill se dispara de forma fiable, tienes un conflicto de triggers. La solución es delimitar mejor las descripciones de trigger o fusionar las skills.

10. Que no dispare un script no es lo mismo que que no dispare la skill

Última trampa. Una skill puede dispararse y aun así no hacer nada visible, porque su script está roto. Claude carga el cuerpo, llama al script, el script casca en silencio, y Claude responde con lo que ha aprendido del cuerpo. Parece "la skill no se dispara" pero es "la skill se dispara, el script casca".

Prueba: en el directorio de la skill llama al script a mano con los mismos argumentos con los que lo llamaría Claude. Si a mano casca, ya sabes dónde buscar. La salida de error de los scripts de skill normalmente se la traga Claude Code, así que eso lo tienes que probar fuera de la sesión.

Qué sigue

Si ahora la skill se dispara, apunta en tu propia memoria o en un CHANGELOG interno cuál era el fallo real. La mayoría de problemas de trigger se repiten, y a la tercera no quieres volver a recorrer los 10 pasos. Guarda el patrón y depura más rápido.

Si quieres profundizar en la composición de skills, mira el playbook erste-eigene-skill-in-30-min (/playbooks/erste-eigene-skill-in-30-min), que entra en detalle en los scripts y en allowed-tools. Para el paso siguiente después de las skills (cuándo es mejor un subagent, cuándo una herramienta MCP) merece la pena la comparación de la lección L4-04 (/levels/4/04-hooks-und-skills).

Source

• Documentación de skills, sección de resolución de problemas: https://code.claude.com/docs/en/skills
• Especificación del frontmatter y activación de skills verificadas ahí el 2026-05-23