Jude Gao, de Vercel, presenta los resultados de una evaluación comparativa entre dos enfoques para transmitir conocimiento específico de un framework a agentes de IA: skills (recuperación activa) y AGENTS.md (contexto pasivo). El hallazgo es inequívoco: el método más simple supera significativamente al más sofisticado.
El problema: Next.js 16 introduce nuevas API (use cache, connection(), forbidden()) ausentes de los datos de entrenamiento de los modelos de IA. Sin documentación actualizada, los agentes generan código incorrecto en el 47 % de los casos.
Skills: el fracaso de la recuperación activa: Skills, un estándar abierto para empaquetar conocimiento invocable bajo demanda, resulta frágil. En el 56 % de los casos de evaluación, el agente nunca invocó el skill disponible, produciendo una tasa de éxito idéntica a la línea base (53 %). Incluso al añadir instrucciones explícitas que fuerzan la invocación (tasa de invocación superior al 95 %), la tasa de éxito solo sube al 79 %, y los resultados varían drásticamente según la redacción exacta de las instrucciones.
AGENTS.md: la victoria del contexto pasivo: Un archivo markdown estático inyectado en el system prompt en cada turno logra una tasa de éxito del 100 % (build, lint y tests). Este enfoque elimina tres fuentes de fragilidad: el punto de decisión (el agente no tiene que elegir invocar), los problemas de disponibilidad (la información está siempre presente) y las cuestiones de orden (no requiere secuenciación de acciones).
Compresión agresiva: El equipo de Vercel logró comprimir 40 KB de documentación en un índice de 8 KB (una reducción del 80 %) usando un formato delimitado por barras verticales, manteniendo la tasa de éxito del 100 %. Esta compresión es esencial porque AGENTS.md consume ventana de contexto en cada interacción.
Implicaciones para el ecosistema: Los resultados sugieren que, para el conocimiento general de un framework, el contexto pasivo (siempre disponible) supera a la recuperación activa (bajo demanda). No obstante, skills conserva su utilidad para flujos de trabajo de acción explícita. Vercel proporciona un comando de instalación (npx @next/codemod@canary agents-md) que detecta automáticamente la versión de Next.js y genera el AGENTS.md correspondiente.
Recomendaciones: No esperar a que skills mejore, comprimir agresivamente la documentación en índices y construir evaluaciones dirigidas específicamente a las API ausentes de los datos de entrenamiento. Estos resultados tienen implicaciones directas para todos los mantenedores de frameworks y bibliotecas que buscan optimizar la compatibilidad con agentes de codificación de IA.