Esta semana me topé con un experimento del equipo de Vercel que me dejó dándole vueltas un buen rato. Estaban enseñando a sus agentes de código a usar las APIs nuevas de Next.js 16, cosas que no aparecen en los datos con los que se entrenaron los modelos. Montaron dos maneras de hacerlo, las midieron con evals y ganó la más aburrida de las dos.
Dos maneras de meterle documentación en la cabeza a un agente
La primera era empaquetar la documentación en una skill. La idea es preciosa: el agente detecta que está ante una tarea de Next.js, invoca la skill y se carga justo los documentos que necesita. Contexto mínimo, solo lo relevante, separación limpia de responsabilidades.
La segunda era un AGENTS.md en la raíz del proyecto con un índice de documentación comprimido en 8 KB. Un archivo de texto plano, siempre presente, sin que el agente tenga que decidir nada. Ni invocación, ni detección, ni nada.
Los números
Sin documentación, el agente pasaba el 53% de los tests. Con la skill disponible y sin más, el 53% otra vez: cero mejora. La skill existía, el agente podía usarla, y simplemente no la usó.
Añadiendo una instrucción explícita en el AGENTS.md del tipo "usa la skill antes de escribir código", la cosa subió al 79%. Y con el índice de 8 KB directamente en el contexto, al 100%. En los tests concretos de comportamiento, del 63% a la perfección absoluta.
Mismo modelo, mismos tests, misma documentación. Lo único que cambiaba era cómo le llegaba la información. Y en un caso, también cuándo.
Por qué gana lo simple
El propio equipo de Vercel da tres razones, y las tres me suenan de haberlas sufrido. La primera: con AGENTS.md no existe el momento de decidir. Nadie se pregunta "¿debería consultar esto?". La información ya está ahí.
La segunda es la disponibilidad: las skills se cargan cuando se invocan, mientras que el AGENTS.md está en el prompt en cada turno. Y la tercera, que es la que más me interesa, es el orden. Las skills crean secuencias: ¿leo primero la documentación o exploro primero el proyecto?
El detalle que me hizo gracia: con la misma skill y los mismos documentos, "invoca la skill" y "explora primero, luego invoca la skill" daban resultados distintos. La primera escribía bien un archivo y se dejaba fuera la configuración. La segunda acertaba los dos. Esa fragilidad ante un simple cambio de redacción es justo lo que me hace desconfiar de los sistemas demasiado listos.
Lo reconozco en mis propios agentes
Yo tengo varios agentes corriendo con sus skills, sus tareas programadas y sus prompts. Y el patrón me suena muchísimo. Las skills que no nombro explícitamente se quedan ahí, mirando. Hay prompts míos con frases escritas en mayúsculas del tipo "no uses esto, no uses aquello", no porque me guste dar órdenes, sino porque si no lo digo, el agente hace justo lo que le apetece.
Y hay un dato de los evals que confirma esa sospecha: la versión con la skill disponible pero sin invocar puntuó peor que no tener documentación ninguna. Una pieza que no se usa no es neutra. Es ruido.
Las skills no están muertas
Tampoco es eso. El mismo análisis lo dice: las skills funcionan bien para flujos concretos que el usuario lanza a propósito, tipo "migra mi proyecto al App Router" o "actualiza esta versión". El contexto pasivo gana para el conocimiento general que el agente necesita siempre. Una cosa no quita la otra.
La regla que me llevo es sencilla: lo que quieres que esté siempre presente, va al contexto. Lo que se activa a demanda por una acción concreta, va a una skill.
Conclusión
Lo que midió Vercel es algo que llevaba tiempo intuyendo: los agentes no fallan por falta de información, fallan porque hay que dársela en el momento, el formato y el orden correctos. Y muchas veces la solución no es más ingeniería, es un archivo de texto bien puesto. Menos piezas que decidan por su cuenta. Más claridad donde el agente mira siempre. Instruir bien un agente sigue siendo, sobre todo, un oficio de escribir claro.