Una skill que nunca se ejecuta rara vez tiene un problema de sintaxis. Carga, aparece en la lista y jamás se elige, porque su descripción no dice cuándo aplica, o lo dice con palabras que nadie usaría. Ese fallo es silencioso por diseño: no hay error, ni aviso, ni señal alguna de que algo va mal. Este linter lee el archivo igual que el cargador, informa de lo que esté malformado y luego dedica casi toda su atención a la descripción: si nombra un disparador, si es lo bastante larga para que haya coincidencia y si empieza repitiendo que es una skill. También señala los campos que el cargador ignora, porque una errata en una clave tiene exactamente el mismo aspecto que un archivo correcto.
Características
Lee el frontmatter con un analizador YAML real e indica dónde falla
Señala campos que el cargador no lee: el aspecto que tiene una errata en una clave
Revisa la descripción en busca de una cláusula de disparo y de longitud suficiente
Informa del número de caracteres de la descripción frente al límite
Comprueba que las instrucciones superen la longitud por debajo de la cual no ayudan
Puntuación con los errores por encima de las sugerencias
Suelta un archivo o pégalo
Un ejemplo roto a propósito para ver qué detecta
Cómo usar Linter de skills
Suelta un SKILL.md o pega su contenido
Lee los hallazgos, de peor a mejor
Corrige la descripción si aparece señalada: es la que importa
Vuelve a comprobar hasta que la puntuación esté limpia
Ejemplo
Entrada
description: Helps with PDFs
Salida
Warning: says what the skill is, but not when to use it
El motivo más habitual de que una skill no se elija nunca.
Errores comunes y solución de problemas
Dice que no hay frontmatter, pero claramente lo hay. — Los tres guiones tienen que ser la primerísima línea: sin línea en blanco, sin comentario, sin nada encima.
El YAML falla con una descripción larga. — Una descripción con dos puntos seguidos de espacio debe ir entrecomillada, o YAML la lee como otra clave.
Señala un campo que uso a propósito. — Los campos desconocidos se informan como notas, no como errores. El cargador los ignora; la nota está porque una clave mal escrita es idéntica a una correcta.
La puntuación sigue baja sin errores listados. — Los avisos también restan. La pareja habitual es una descripción sin cláusula de disparo e instrucciones demasiado breves.
Preguntas frecuentes
¿Por qué mi skill carga pero nunca se elige?
La descripción se compara con la tarea, así que si solo describe el tema —«trabaja con hojas de cálculo»— no hay nada con lo que emparejar una petición. Añadir una cláusula que nombre la situación, los tipos de archivo o las palabras que usaría una persona suele bastar.
¿Qué cuenta como cláusula de disparo?
Cualquier cosa que nombre el momento en que la skill aplica: «Úsala cuando el usuario pida…», «Siempre que cambie un archivo de migración…», «Para tareas relacionadas con…». El linter busca esa forma y avisa cuando no aparece.
¿Es malo que la descripción sea larga?
En sí no: el límite es generoso y el recuento se muestra. Lo que perjudica es una descripción larga que aun así nunca dice cuándo usar la skill, una combinación sorprendentemente frecuente.
¿Puedo analizar una skill que no he escrito yo?
Es un buen uso. Al soltar una skill de otro sitio se ve enseguida si su descripción competirá con las tuyas y si declara herramientas que no esperabas.
¿Un resultado limpio garantiza que la skill funcione?
No. Significa que el archivo cargará y que la descripción tiene la forma que se compara. Si las instrucciones son buenas es un juicio que ningún linter emite.
Herramientas relacionadas
Constructor de skills — Escribe un SKILL.md con el frontmatter revisado mientras escribes.
Constructor de subagentes — Crea el archivo de definición de un subagente con sus herramientas y modelo.
Linter de prompts — Encuentra contradicciones, instrucciones muertas y marcadores sin rellenar.