# gao-vercel-agents-md-outperforms-skills-evals-2026-01-27

## Veille

AGENTS.md supera a skills en las evaluaciones de agentes de Vercel/Next.js

## Titre Article

AGENTS.md outperforms skills in our agent evals

## Date

2026-01-27

## URL

https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals

## Keywords

AGENTS.md, skills, evaluación de agentes de IA, contexto pasivo, recuperación activa, Next.js 16, Vercel, datos de entrenamiento desactualizados, documentación comprimida, system prompt, codificación agéntica, use cache, connection(), forbidden()

## Authors

Jude Gao (Vercel)

## Ton

**Perfil**: Publicación técnica empírica, registro analítico y factual, nivel técnico avanzado

**Descripción**: Publicación de blog de ingeniería que adopta un enfoque científico riguroso con un protocolo de evaluación, tablas de resultados cuantificados y análisis comparativo. El tono es el de un ingeniero que comparte resultados experimentales con transparencia, incluidos los fracasos (skills no invocado en el 56 % de los casos). La argumentación se basa en datos, con porcentajes precisos. El público objetivo son desarrolladores y mantenedores de frameworks que buscan optimizar la experiencia de sus usuarios con agentes de codificación de IA.

## Pense-betes

- **Problema subyacente**: los modelos de IA tienen datos de entrenamiento desactualizados. Next.js 16 introduce API (`use cache`, `connection()`, `forbidden()`) ausentes de los datos de entrenamiento, lo que provoca código incorrecto
- **Dos enfoques evaluados**:
- **Skills**: estándar abierto para empaquetar conocimiento, invocable bajo demanda por el agente
- **AGENTS.md**: archivo markdown estático que proporciona contexto persistente en cada interacción
- **Resultados clave**:
- Sin documentación: tasa de éxito del 53 %
- Skills (comportamiento por defecto): 53 % (+0 pp, ¡sin ganancia!)
- Skills con instrucciones explícitas: 79 % (+26 pp)
- **AGENTS.md con índice: 100 % (+47 pp)**
- **Fragilidad de skills**: en el 56 % de los casos de evaluación, el agente nunca invocó el skill
- **Incluso con instrucciones explícitas**: la invocación de skills subió a más del 95 %, pero el éxito dependía en gran medida de la redacción exacta
- **Compresión exitosa**: documentación comprimida de 40 KB a 8 KB (reducción del 80 %) con un formato delimitado por barras verticales, sin pérdida de rendimiento
- **Teoría de las 3 ventajas del contexto pasivo**: 1. Sin punto de decisión (información disponible sin necesidad de elegir) 2. Disponibilidad constante (AGENTS.md en el system prompt en cada turno) 3. Sin problemas de orden (no requiere secuenciación de acciones)
- **Recomendaciones prácticas**: no esperar a que skills mejore, comprimir índices agresivamente, construir evaluaciones dirigidas a API fuera de los datos de entrenamiento
- **Instalación**: `npx @next/codemod@canary agents-md` detecta la versión, descarga la documentación e inyecta el índice en AGENTS.md
- **Matiz importante**: skills sigue siendo útil para flujos de trabajo de acción específica activados explícitamente, pero para el conocimiento general de un framework, el contexto pasivo es superior

## RésuméDe400mots

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.

## GrapheDeConnaissance

- Jude Gao —publie→ AGENTS.md outperforms skills in our agent evals (DOCUMENT, 0.99)
- Jude Gao —travaille_chez→ Vercel (ORGANISATION, 0.98)
- AGENTS.md —mesure→ taux de réussite 100% (MESURE, 0.99)
- skills —mesure→ taux de réussite 79% (avec instructions explicites) (MESURE, 0.99)
- skills —surpasse→ baseline sans documentation (CONCEPT, 0.97)
- AGENTS.md —surpasse→ skills (TECHNOLOGIE, 0.99)
- contexte passif —réduit→ point de décision agent (CONCEPT, 0.95)
- use cache —fait_partie_de→ Next.js 16 (TECHNOLOGIE, 0.98)
- connection() —fait_partie_de→ Next.js 16 (TECHNOLOGIE, 0.98)
- forbidden() —fait_partie_de→ Next.js 16 (TECHNOLOGIE, 0.98)
- Vercel —a_créé→ Next.js 16 (METHODOLOGIE, 0.97)
- documentation compressée —réduit→ contexte de 40 Ko à 8 Ko (CONCEPT, 0.99)
- skills —mesure→ non-invocation dans 56% des cas d'évaluation (MESURE, 0.99)
- CLAUDE.md —est_variante_de→ AGENTS.md (TECHNOLOGIE, 0.96)

---
Canonical: https://www.thekb.eu/es/fiches/gao-vercel-agents-md-outperforms-skills-evals-2026-01-27/