Skills de agente: anatomía y criterio

Guía interna de IAcademy. No es bibliografía ajena: es el material que acompaña al módulo ADE16 · Agent Skills.

¿Qué es una skill?

Una skill es una carpeta de instrucciones que enseña al agente un procedimiento que ya sabes hacer, para que lo repita igual la próxima vez. No es un prompt largo guardado: es una unidad con nombre, con disparador y con material de apoyo, que el agente activa solo cuando la tarea encaja con lo que declara.

La diferencia práctica se ve en tres cosas: se activa por contexto (no la pegas cada vez), viaja contigo (vive en el repositorio o en tu configuración, no en una conversación), y tiene presupuesto de contexto (lo que cargas de más se paga en cada activación).

Anatomía de una skill

El estándar lo define un fichero obligatorio y tres carpetas opcionales:

mi-skill/
├── SKILL.md        # obligatorio: frontmatter YAML + instrucciones
├── scripts/        # opcional: código que se ejecuta sin entrar al contexto
├── references/     # opcional: documentación que solo se lee si hace falta
└── assets/         # opcional: plantillas, imágenes, datos

El SKILL.md lleva un encabezado con dos campos obligatorios: name (hasta 64 caracteres, en minúsculas, números y guiones, sin espacios ni marcas ajenas) y description (hasta 1.024 caracteres, y aquí está la clave: describe qué hace y cuándo usarla). Además admite allowed-tools, compatibility, license y metadata. Nada más: restringirse a esos campos evita que la skill deje de ser portable.

La description es el 80% del trabajo. Un agente decide activar o no una skill leyendo esa línea; si escribes «ayuda con despliegues», no se activará cuando toque, y sí cuando no toque. Escribe el disparador: «usar cuando haya que preparar un despliegue a producción en este repositorio».

Divulgación progresiva: lo que de verdad separa una skill de un prompt

Cuando la skill se activa, el agente carga el cuerpo entero del SKILL.md. Todo lo que no hayas movido a references/ se queda en la ventana de contexto cada vez que la skill entra en juego. Por eso la regla es: en el SKILL.md, el procedimiento; en references/, el detalle que solo hace falta a veces; en scripts/, lo que se ejecuta sin gastar contexto (una validación, una consulta, un formateo).

Si tu skill tiene 900 líneas porque metiste el manual entero, no has hecho una skill: has hecho un prompt caro que se activa solo.

Escribir una skill, en orden

  1. Escribe el procedimiento en prosa y hazlo bien una vez a mano. Si no funciona como instrucción escrita, como skill tampoco.
  2. Separa lo determinista: lo que no debe decidir el modelo va a un script, no a un párrafo.
  3. Corta el detalle a references/ y deja en el cuerpo el flujo y los criterios de parada.
  4. Nombra y describe para el disparador, no para ti: nombre en gerundio («desplegando-a-produccion»), descripción con el cuándo.
  5. Pruébala con un caso que no sea el tuyo. Si solo cubre tu repositorio, aún es una nota personal.

Errores que se repiten

Los límites de una skill

Si el procedimiento cambia cada vez, si depende de datos que solo existen en la conversación, o si vive de la creatividad del modelo, una skill te va a estorbar. Ahí lo correcto es un buen prompt o, directamente, hacerlo a mano. La prueba: ¿podrías enseñárselo a una persona nueva en una página? Entonces sí es una skill.

Seguir