Habilidades para la resolución de problemas
Cuando una habilidad no funciona como esperas, el problema casi siempre cae en una de cuatro categorías: no se activa, no se carga, hay un conflicto de prioridad o falla al ejecutarse. Cada una tiene su diagnóstico y su solución.
🌐 Este vídeo es el original de Anthropic, en inglés. Para seguirlo en español, dale al play al audio 🎬 «Sigue el vídeo en español» de aquí abajo — es la traducción exacta de lo que se dice.
Sigue el vídeo en español
Escucha la lección
Empieza siempre por el validador
Antes de depurar cualquier otra cosa, ejecuta claude --debug. Detecta problemas en segundos y te ahorra buscar en el lugar equivocado. Busca mensajes que mencionen el nombre de tu habilidad — a veces eso solo ya te dice exactamente dónde está el fallo.
Problema 1: la habilidad no se activa
Existe y pasa la validación, pero Claude no la usa cuando la esperas. La causa casi siempre es la descripción: Claude usa coincidencia semántica, así que tu petición debe coincidir con su significado.
Cómo solucionarlo: compara tu descripción con cómo pides las cosas de verdad; añade frases que la gente diría ("ayúdame a analizar esto", "¿por qué es lento?", "haz esto más rápido"); y si una variación no la activa, añade esas palabras a la descripción.
Problema 2: la habilidad no se carga
Si no aparece cuando preguntas "¿qué habilidades hay disponibles?", revisa la estructura:
- ›El SKILL.md debe estar dentro de una carpeta con nombre, no suelto en la raíz de habilidades.
- ›El nombre del archivo debe ser exactamente SKILL.md (SKILL en mayúsculas, md en minúsculas).
- ›Comprueba que el encabezado está bien formado, entre guiones.
Correcto: ~/.claude/skills/mi-habilidad/SKILL.md · Incorrecto: ~/.claude/skills/SKILL.md
Problema 3: se activa la habilidad equivocada
Claude usa la habilidad incorrecta o se confunde entre varias: las descripciones son demasiado parecidas. Hazlas más distintas. Ser específico no solo ayuda a Claude a elegir — también evita conflictos con otras de nombre similar.
Problema 4: conflictos de prioridad
Tu habilidad personal se está ignorando: probablemente una de mayor prioridad tiene el mismo nombre. Recuerda el orden: Empresa › Personal › Proyecto › Plugins.
Opciones: cambia el nombre de la tuya por algo más específico (lo más fácil), o habla con tu administrador si crees que hay un conflicto legítimo.
Problema 5: errores al ejecutarse
La habilidad se carga pero falla durante la ejecución. Causas habituales:
- ›Dependencias faltantes: si usa paquetes externos, deben estar instalados. Añade esa información a la descripción.
- ›Permisos de script: los scripts necesitan permiso de ejecución (chmod +x).
- ›Separadores de ruta: usa barras diagonales en todas partes, incluso en Windows.
Lista de verificación rápida
| Síntoma | Solución |
|---|---|
| No se activa | Mejora la descripción con frases que de verdad uses |
| No se carga | Revisa la ruta, el nombre (SKILL.md) y el encabezado |
| Habilidad equivocada | Haz las descripciones más distintas entre sí |
| Ignorada por otra | Revisa la prioridad y cambia el nombre si hace falta |
| Plugin no aparece | Borra la caché y vuelve a instalarlo |
| Fallo al ejecutar | Comprueba dependencias, permisos y rutas |
¡Has completado el curso! Has aprendido a crear, configurar, compartir y resolver problemas con las Habilidades en Claude Code. Recuerda: las mejores habilidades surgen de los problemas reales — empieza por las instrucciones que más veces te encuentras repitiendo.
¿No programas? Te lo explico fácil · sin tecnicismos
Si una receta no funciona, casi siempre es por una de estas cosas. Te lo cuento fácil:
No salta cuando quieres
Casi siempre es la etiqueta (la descripción): no se parece a cómo lo pides. Ponle palabras como las que dirías tú de verdad.
No aparece en la lista
Suele ser que el archivo está mal colocado o mal nombrado: tiene que estar dentro de su carpeta y llamarse exactamente como toca.
Se lía entre dos parecidas
Si tienes dos recetas con etiquetas casi iguales, Claude duda. Diferéncialas bien.
Una le gana a la otra
Hay un orden de mando: empresa, tú, proyecto, plugins. Si te pisan la receta, renómbrala.
Salta pero falla al hacerla
Como cocinar sin un ingrediente: faltan piezas que tienen que estar instaladas, o falta un permiso.
En una frase: si algo no va, mira la etiqueta, dónde está el archivo, que no haya dos iguales, quién tiene prioridad y si están todas las piezas.
Glosario
claude --debug
Comando que arranca Claude Code en modo depuración y muestra errores de carga de habilidades.
Un modo que enseña los fallos por dentro; útil para ver por qué una habilidad no carga.
Coincidencia semántica
Claude empareja tu petición con la descripción de la habilidad por significado, no por palabras exactas.
Claude te entiende por el sentido, no por las palabras justas; por eso la descripción importa tanto.
Dependencias
Paquetes o programas externos que una habilidad necesita instalados para ejecutarse.
Las piezas de fuera que tienen que estar puestas para que la habilidad funcione.
Permiso de ejecución (chmod +x)
Marca que autoriza a ejecutar un script; sin ella, el sistema no lo deja correr.
El "permiso para funcionar" de una maquinita; sin él, no arranca.
Jerarquía de prioridades
Orden que decide qué habilidad gana si varias comparten nombre: empresa, personal, proyecto, plugins.
Quién manda si dos se llaman igual: empresa, luego tú, luego el proyecto, luego los plugins.
Fuentes oficiales de Anthropic