Guía: escribe descripciones de skills para agentes en tres frases
Las descripciones largas hacen que un agente no lea la skill. Escribe tres frases: cuándo aplicarla, cuándo usarla y qué hace.
Cuando un agente de IA tiene que elegir entre cientos de skills, decide por la descripción, no por el contenido. Una skill con una descripción interminable, repleta de parámetros y casos límite, suele terminar ignorada: el router gasta tiempo y tokens en leerla y ni siquiera sabe si aplica. El consejo que circula en la comunidad de desarrollo es drástico: toda descripción de skill debería caber en tres frases. La primera indica cuándo hay que leerla (el disparador), la segunda especifica la situación exacta de uso y la tercera dice qué hace, sin más.
La regla nace de un fallo corriente: se describen skills como si fueran manuales de API. El agente acaba sin reconocer cuándo debe abrirla. Y una skill que no se encuentra a tiempo es una skill que no tienes. Tres frases obligan a que el nombre y la primera línea coincidan en el detonante, de modo que el router decide en un vistazo. Es la misma idea que la divulgación progresiva: se aplaza el detalle hasta que el agente haya entrado en el fichero.
¿Por qué tres y no una o cinco? Una frase suele eliminar el cuándo; cinco recaen en el 'feature dump' que esta regla intenta matar. Tres es el número más pequeño que mantiene separadas las preguntas de cuándo, dónde y qué. La descripción se convierte en un filtro, no en un resumen.
Los beneficios se notan en cuanto empiezas a aplicarla: menos elecciones equivocadas porque cada skill tiene un disparador claro, menos contexto consumido porque las que no aplican nunca se abren, y una base de skills más fácil de mantener tras cada actualización del modelo. Si te cuesta condensar en tres frases, es síntoma de que la skill en sí hace demasiado y deberías dividirla.
No es una regla inflexible: una cuarta frase tiene sentido si añade una restricción genuina. Pero es un objetivo útil, y el propio nombre de la skill debe reforzar el disparador. Para quien trabaje con la plataforma de Claude, la documentación oficial sobre Agent Skills recoge cómo se definen estas piezas y qué papel juegan en el enrutamiento.
La conclusión es la misma de siempre: menos es más. Si una descripción no se comprime en tres frases, no entiendes bien qué hace la skill. El tiempo de edición extra se paga en menos tokens malgastados.
