Solución de problemas de skills

Solución de problemas de skills

Puntos clave

• Comienza con la herramienta validadora de skills — detecta problemas estructurales antes de que dediques tiempo a depurar otras cosas
• Si una skill no se activa, la causa casi siempre es la descripción — agrega frases de activación que coincidan con cómo realmente formulas tus solicitudes
• Si una skill no se carga, verifica que SKILL.md esté dentro de un directorio con nombre (no en la raíz de skills) y que el nombre del archivo sea exactamente SKILL.md
• Si se usa la skill incorrecta, tus descripciones son demasiado similares — hazlas más distintivas
• Para errores en tiempo de ejecución, verifica las dependencias, los permisos de archivo (chmod +x) y los separadores de ruta (usa barras diagonales en todas partes)

Cuando las skills no funcionan, el problema generalmente se encuentra en una de algunas categorías: la skill no se activa, no se carga, tiene conflictos o falla en tiempo de ejecución. La buena noticia es que la mayoría de las soluciones son bastante sencillas.

Usa el validador de skills

Lo primero que debes probar es el comando claude plugin validate. En tu shell, ejecuta claude plugin validate ~/.claude/skills para skills personales o claude plugin validate .claude/skills para skills de proyecto. Requiere Claude Code v2.1.233 o posterior.

El validador encuentra archivos SKILL.md cuyo frontmatter no se puede analizar, para que detectes ese problema antes de dedicar tiempo a depurar otras cosas. El video anterior muestra un verificador independiente que se instala con uv.

La skill no se activa

Tu skill existe y pasa la validación, pero Claude no la usa cuando esperas. La causa casi siempre es la descripción.

Claude usa coincidencia semántica, por lo que tu solicitud necesita coincidir con el significado de la descripción. Si no hay suficiente coincidencia, no hay activación. Esto es lo que debes hacer:

• Compara tu descripción con cómo realmente formulas tus solicitudes
• Agrega frases de activación que los usuarios realmente dirían
• Prueba con variaciones como "ayúdame a perfilar esto", "¿por qué esto es lento?", "haz esto más rápido"
• Si alguna variación no logra activarla, agrega esas palabras clave a tu descripción

La skill no se carga

Si tu skill no aparece cuando le preguntas a Claude "qué skills están disponibles", verifica estos requisitos estructurales:

• El archivo SKILL.md debe estar dentro de un directorio con nombre, no en la raíz de skills
• El nombre del archivo debe ser exactamente SKILL.md — todo en mayúsculas para "SKILL", minúsculas para "md"

Ejecuta claude --debug para ver errores de carga. Busca mensajes que mencionen el nombre de tu skill. A veces esto por sí solo te llevará directamente al problema.

Se usa la skill incorrecta

Si Claude usa la skill incorrecta o parece confundirse entre skills, tus descripciones probablemente sean demasiado similares. Hazlas distintivas. Ser lo más específico posible no solo ayuda a Claude a decidir cuándo usar tu skill, sino que también evita conflictos con otras skills de nombre similar.

Conflictos de prioridad de skills

Si tu skill personal está siendo ignorada, es posible que una skill empresarial o de mayor prioridad tenga el mismo nombre.



Por ejemplo, si existe una skill empresarial "code-review" y también tienes una skill personal "code-review", la empresarial gana siempre. Tus opciones:

1. Cambia el nombre de tu skill a algo más distintivo (esta suele ser la opción más fácil)
2. Habla con tu administrador sobre la skill empresarial

Las skills del plugin no aparecen

¿Instalaste un plugin pero no puedes ver sus skills? Ejecuta /plugin y verifica que el plugin aparezca en la lista y esté habilitado en Installed, luego revisa la pestaña Errors. Si lo instalaste durante esta sesión, ejecuta /reload-plugins.

Si las skills aún no aparecen después de eso, la estructura del plugin podría ser incorrecta. Las skills se cargan desde un directorio skills/ en la raíz del plugin, no desde dentro de .claude-plugin/. En tu shell, ejecuta claude plugin validate en el directorio del plugin para verificar su manifiesto y el frontmatter de cada skill.

Errores en tiempo de ejecución

La skill se carga pero falla durante la ejecución. Algunas causas comunes:

• Dependencias faltantes: Si tu skill usa paquetes externos, estos deben estar instalados. Agrega información sobre las dependencias a la descripción de tu skill para que Claude sepa qué se necesita.
• Problemas de permisos: Los scripts necesitan permiso de ejecución. Ejecuta chmod +x en cualquier script al que haga referencia tu skill.
• Separadores de ruta: Usa barras diagonales en todas partes, incluso en Windows.

Lista rápida de solución de problemas

• ¿No se activa? Mejora tu descripción y agrega frases de activación.
• ¿No se carga? Verifica tu ruta, el nombre del archivo y la sintaxis YAML.
• ¿Se usa la skill incorrecta? Haz que las descripciones sean más distintivas entre sí.
• ¿Está siendo eclipsada? Verifica la jerarquía de prioridad y cambia el nombre si es necesario.
• ¿Faltan skills del plugin? Verifica /plugin en busca de errores, luego ejecuta /reload-plugins.
• ¿Falla en tiempo de ejecución? Verifica las dependencias, los permisos y las rutas.

Reflexión de la lección

• ¿Te has encontrado con alguno de estos escenarios de solución de problemas en tu propio trabajo? ¿Qué solución te habría ahorrado más tiempo?
• ¿Cómo establecerías un proceso para validar las skills antes de compartirlas con tu equipo?

Cierre del curso

¡Felicidades por completar Introducción a Agent Skills! Has aprendido a crear, configurar, compartir y solucionar problemas de skills en Claude Code. A medida que comiences a crear skills para tus propios flujos de trabajo, recuerda que las mejores skills surgen de puntos de dolor reales — comienza con las instrucciones que te encuentras repitiendo con más frecuencia.