| Síntoma | Causa más probable | Qué cambiar |
|---|---|---|
| La skill nunca se activa, ni siquiera en la tarea para la que se escribió. | La descripción está escrita con el vocabulario del autor, así que no coincide con cómo se formula la petición. | Reescribe la descripción con las palabras que usaría un compañero y añade la parte cuándo de forma explícita. Prueba pidiendo la tarea con la formulación de otra persona, no la tuya. |
| Se activa en tareas con las que no tiene nada que ver. | La descripción es amplia o genérica, así que coincide con mucho más de lo que debería. | Acota la descripción al artefacto o la situación concretos. Nombra el formato, el sistema o el tipo de documento en vez de la actividad general. |
| Se carga, pero el agente sigue solo la primera parte. | El cuerpo es largo y las instrucciones que importan quedan enterradas tras contexto que el modelo no necesita. | Quita el contexto. Mueve el detalle a references/ y deja en el cuerpo procedimiento, puntos de decisión y forma del resultado. |
| El comportamiento cambia entre sesiones sin que tú cambies nada. | Otra skill instalada instruye al agente sobre la misma decisión, y cuál gana no es estable. | Consulta el mapa de compatibilidad y quita una de las dos. Dos metodologías para un trabajo es un conflicto, no redundancia. |
| Las sesiones pesan más desde que instalaste un conjunto de skills. | Cada skill instalada paga sus metadatos al inicio, y los cuerpos enormes vuelven a pagar al activarse. | Borra las skills que nadie activa y divide las que pasan de unas 500 líneas. El coste es por sesión, así que se acumula. |
| A ti te funciona y a un compañero no. | O la skill no está instalada de su lado, o depende de algo de tu entorno que la skill nunca declara. | Declara los requisitos reales de entorno en compatibility y comprueba si la skill asume herramientas, rutas o credenciales que solo tienes tú. |
| El validador pasa pero no ocurre absolutamente nada. | La validación comprueba el archivo, no el montaje. El nombre de la carpeta puede no coincidir con el campo name, o la skill puede no estar donde el agente carga. | Confirma que la carpeta se llama exactamente igual que name y después que la skill está instalada donde tu agente lee las skills. |
Por qué todo esto falla en silencio
Una skill que no coincide no es un error. Desde el lado del agente no pasó nada: se leyeron los metadatos, no coincidieron con la tarea y la ejecución siguió con normalidad. Por eso estos problemas duran semanas y por eso la descripción es lo primero que hay que mirar, siempre.
El orden en el que conviene comprobar
Ir de arriba abajo cuesta minutos. Ir de abajo arriba, reescribiendo primero el cuerpo, es como se pierde una tarde.
- ¿Está la skill donde el agente lee, y coincide el nombre de la carpeta con el campo name?
- ¿Contiene la descripción las palabras que otra persona usaría para esta tarea?
- ¿Dice la descripción cuándo usarla, y no solo qué hace?
- ¿Hay otra skill instruyendo la misma decisión?
- ¿Es el cuerpo lo bastante corto para que lo importante no quede enterrado?