- En una evaluación dirigida a la API de Next.js 16, el índice de documentación
AGENTS.md incluido en la raíz del proyecto registró una precisión mayor que el enfoque basado en skills
- Los skills son paquetes de conocimiento de dominio que el agente invoca cuando los necesita, pero como su activación es inestable, en la configuración predeterminada solo lograron una tasa de aprobación del 53%
- En cambio, el índice
AGENTS.md comprimido a 8 KB alcanzó una tasa de aprobación del 100% en todas las pruebas (Build, Lint, Test)
- Este enfoque mostró resultados más estables que la invocación activa debido a la eliminación de puntos de decisión, disponibilidad permanente y resolución de problemas de orden
- Los mantenedores de frameworks pueden incluir en AGENTS.md un índice de documentación alineado con la versión para mejorar la precisión en la generación de código
Contexto del problema
- Los agentes de programación con IA tienen la limitación de que sus datos de entrenamiento se basan en APIs de versiones anteriores, por lo que no manejan con precisión frameworks recientes
- Elementos como
'use cache', connection() y forbidden() de Next.js 16 no existen en los datos de entrenamiento previos del modelo
- A la inversa, en proyectos con versiones antiguas también ocurre que el modelo propone APIs nuevas que en realidad no existen
- Para resolver esto, se experimentó con un enfoque de acceso a documentación alineada con la versión
Dos enfoques
- Skills: un paquete de estándar abierto que agrupa prompts, herramientas y documentación, y que el agente invoca cuando hace falta
AGENTS.md: un archivo de contexto persistente ubicado en la raíz del proyecto, siempre disponible en todos los turnos de la conversación- Se evaluaron ambos métodos comparándolos sobre la misma documentación de Next.js
Limitaciones del enfoque con Skills
- Según la evaluación, en el 56% de las pruebas el skill no fue invocado, y la tasa base de aprobación se mantuvo en 53%, sin mejoras
- En algunos casos incluso registró resultados peores que la línea base (por ejemplo, Test 58% vs 63%)
- Esto se señala como una limitación de los modelos actuales, que todavía no logran usar herramientas de forma confiable
Experimento con instrucciones explícitas
- Al añadir a
AGENTS.md una instrucción explícita de “invoca el skill antes de escribir código”, la tasa de aprobación subió a 79%
- Sin embargo, pequeñas diferencias en la redacción de la instrucción afectaron mucho el resultado
- “Invoca primero el skill” → el modelo se fijó en patrones de la documentación y omitió el contexto del proyecto
- “Explora el proyecto y luego invoca el skill” → mejores resultados
- Debido a esta fragilidad lingüística, la confiabilidad en uso real sigue siendo baja
Construcción de una evaluación confiable
- Las pruebas iniciales tenían poca confiabilidad por prompts ambiguos y problemas de validación duplicada
- Esto se mejoró reforzando la evaluación con verificación basada en comportamiento y pruebas centradas en APIs de Next.js 16 fuera del entrenamiento del modelo
- Principales APIs evaluadas:
connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() y otras
Experimento con el enfoque AGENTS.md
- Se eliminó el proceso de elección del agente y se insertó directamente el índice de documentación en AGENTS.md
- El índice no contenía la documentación completa, sino una lista de rutas de documentación por versión
- Instrucción adicional:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
- Esto orienta al modelo a priorizar el razonamiento basado en documentación en lugar de sus datos de entrenamiento previos
Resultados de la evaluación
- Insertar el índice en AGENTS.md logró una tasa de aprobación del 100%
- Build, Lint y Test obtuvieron resultados perfectos
- Estadísticas comparativas:
- Baseline 53%, Skill predeterminado 53%, Skill + instrucción 79%, AGENTS.md 100%
- Razones por las que el contexto pasivo supera a la invocación activa
- No hay punto de decisión: la información siempre está presente
- Disponibilidad consistente: se incluye en el prompt del sistema en cada turno
- Elimina problemas de orden: no depende del orden de exploración de la documentación
Resolución del problema de capacidad de contexto
- El índice inicial era de 40 KB, pero se redujo a 8 KB mediante compresión (80% menos)
- Con una estructura separada por pipes (
|), se almacenaron rutas y nombres de archivo ocupando el mínimo espacio
- El agente lee solo los archivos necesarios del directorio
.next-docs/ para usar información precisa de la versión correspondiente
Cómo aplicarlo
Implicaciones para desarrolladores de frameworks
- Los skills siguen siendo útiles, pero para mejorar la precisión general en generación de código, el enfoque con AGENTS.md resulta más efectivo
- Los skills son adecuados para flujos de trabajo centrados en tareas específicas, como “actualización de versión” o “migración a App Router”
- Recomendaciones:
- no esperar a que mejoren los skills y usar AGENTS.md de inmediato
- incluir solo el índice de documentación para minimizar el contexto
- validar con evaluaciones centradas en APIs que no estén en los datos de entrenamiento
- diseñar la documentación con una estructura de búsqueda granular
- El objetivo es pasar de un razonamiento centrado en el preentrenamiento a uno basado en recuperación, y
AGENTS.md es la forma más estable de implementarlo
4 comentarios
> Los agentes de codificación con IA tienen la limitación de que, al estar basados en datos de entrenamiento con APIs antiguas, no pueden manejar con precisión los frameworks más recientes.
Usando Context7, ese problema se puede resolver hasta cierto punto.
https://context7.com
Se usan los dos métodos de arriba porque context7 es ineficiente...
Entiendo lo que quiere decir, pero aun así no me parece tan mala opción usar context7 como apoyo, en vez de tener que ir organizando y agregando una por una en AGENTS.md o Skills los enlaces a la documentación más reciente de todos los frameworks y bibliotecas que se están usando actualmente cada vez.
Además, ni en GeekNews ni en el artículo de Vercel se menciona context7. Le dejo esta respuesta porque me parece que usted interpretó el contenido medio paso por delante.
(Como referencia, es un hecho bien conocido —y yo también lo sé bien— que con Skills o AGENTS.md bien redactados se puede ahorrar tokens.)
Comentarios en Hacker News
El modelo no es AGI. Es solo un generador de texto, entrenado para producir efectos como editar archivos o llamar herramientas
No es que el modelo “entienda” y use las skills del usuario, sino que genera ese tipo de texto gracias al aprendizaje por refuerzo (RL) basado en ejemplos y registros de uso creados por humanos
La razón por la que no siempre usa las skills es que todavía no ha aprendido suficientes casos así. Forzarlo con RL podría incluso volver más tonto al modelo
Ahora mismo estamos acumulando registros de uso de skills para que los modelos futuros aprendan mejor cuándo deben usarlas
AGENTS.md simplemente es contexto. El modelo ha sido entrenado desde el principio para seguir el contexto
El frontmatter de las skills también termina incluido en el contexto, así que si AGENTS.md funciona mejor, se debe a la diferencia en cómo se extrae e inyecta la información de las skills
Algunos agentes incluso podrían usar modelos pequeños (por ejemplo, Haiku) para decidir qué información de skills pasar a modelos grandes (por ejemplo, Sonnet, Opus)
Al final, lo esencial es qué información entra en el “prompt crudo”
Es útil, pero no perfecto. La tecnología GPT en sí parece haber entrado ya en una meseta de rendimiento
Lo que probablemente mejore de aquí en adelante son sistemas auxiliares como las skills. Pero la implementación actual de skills es peor que usar directamente AGENTS.md
En la evaluación, hubo un resultado según el cual en el 56% de los casos nunca se llamó a ninguna skill. Eso significa que tenía la documentación, pero no la usó. De ahí salió la broma de “Bueno, sí pasó la prueba de Turing…”
La diferencia es que la IA acepta instrucciones de corrección sin orgullo
Aún no está al nivel de un desarrollador senior, pero sigue mejor las instrucciones que un junior
El hallazgo clave es que la compresión (compression) de punteros a documentos resulta efectiva
Para humanos es difícil de leer, pero para un LLM es una estructura de referencia directa y eficiente
Más adelante, en lugar de heurísticas como agents.md/claude.md/skills.md, es muy posible que se estandarice un formato de índice comprimido que siempre se cargue
Incluso podría reutilizarse una suite de pruebas de API para verificar el rendimiento de código generado por LLM
A medida que crezca la adopción de LLM, las bibliotecas y APIs también tendrán que evolucionar en esa dirección
En Antigravity (= basado en GEMINI.md) hicieron que siguiera las reglas de AGENTS.md, pero las ignoró
En cambio, el prompt “verifica si hay un AGENTS.md en el proyecto” siempre funcionó
Es un fenómeno curioso, como cuando antes “let’s think step by step” inducía chain-of-thought
Si se incluye AGENTS.md directamente en el prompt del sistema, siempre entra al contexto
Pero incluir todas las skills en cada ocasión es un desperdicio. Por eso hace falta un enfoque como el advanced tool use de Anthropic, donde se cargan solo cuando se necesitan
Al final, es un problema de equilibrio entre contexto y costo. Si hay margen, comprimirlo en AGENTS.md resulta eficiente
Parece que este tipo de agentes con autogestión de contexto va a avanzar mucho este año
Claude tiene una baja tasa de cumplimiento de skills
Yo también trabajo en un área parecida. Quiero evaluar cómo la estructura de scaffolding del proyecto afecta los resultados de Claude Code/Opencode
Pero como la metodología de prueba de Vercel no está clara, es difícil comparar
AGENTS.md no es algo completamente distinto de las skills, sino una forma simplificada de skill
El punto clave es la calidad del diseño de las skills: minimizar la cantidad de pasos que la IA debe seguir para encontrar la información correcta
Cuantos menos pasos haya, menor es la acumulación de errores
Y para reducir el desperdicio de tokens, los archivos grandes los pongo solo una vez en el prompt del sistema
Cuando en blogs comparan prompt engineering, siempre me pregunto si lo ejecutaron una sola vez o varias veces
Los resultados de los LLM no son consistentes ni siquiera con la misma entrada
Da la impresión de que la mayoría son datos anecdóticos disfrazados de ciencia
Pero cuando haces benchmarks con cuidado, tienen pocas vistas; si lo haces a la carrera, el tráfico del blog sube 9 veces
El problema es la estructura de incentivos distorsionada
También hay una forma mejor que AGENTS.md
Consiste en crear una carpeta
.context, meter ahí enlaces simbólicos a documentos del proyecto (README, documentación de dependencias, etc.) y hacer que siempre se carguen en el contextoAsí el LLM tiene toda la información necesaria desde el inicio, lo que permite mejorar el rendimiento y reducir costos
_vendorAsí el LLM puede analizar directamente el código y entender cómo funciona
Esta es una experiencia que obtuve al crear mi agente personalizado
Cambié
read/write_filepara ponerlo en el estado y hacer que aparezca en el prompt del sistema, y funcionó mucho mejorAhora estoy intentando demostrarlo con evaluaciones cuantitativas (evals). Mi impresión es que el rendimiento es muy bueno