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

## Veille

AGENTS.md supera skills nelle valutazioni degli agenti 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, valutazione degli agenti IA, contesto passivo, recupero attivo, Next.js 16, Vercel, dati di addestramento obsoleti, documentazione compressa, system prompt, agentic coding, use cache, connection(), forbidden()

## Authors

Jude Gao (Vercel)

## Ton

**Profilo**: Post tecnico empirico, registro analitico e fattuale, livello tecnico avanzato

**Descrizione**: Post di blog ingegneristico che adotta un approccio scientifico rigoroso con protocollo di valutazione, tabelle di risultati quantificati e analisi comparativa. Il tono è quello di un ingegnere che condivide risultati sperimentali con trasparenza, inclusi i fallimenti (skills non invocate nel 56% dei casi). L'argomentazione è basata sui dati con percentuali precise. Il pubblico di riferimento è composto da sviluppatori e maintainer di framework che cercano di ottimizzare l'esperienza dei loro utenti con gli agenti di codifica IA.

## Pense-betes

- **Problema di fondo**: i modelli IA hanno dati di addestramento obsoleti. Next.js 16 introduce API (`use cache`, `connection()`, `forbidden()`) assenti dai dati di addestramento, causando codice errato
- **Due approcci testati**:
- **Skills**: standard aperto per impacchettare conoscenza, invocabile su richiesta dall'agente
- **AGENTS.md**: file markdown statico che fornisce contesto persistente a ogni interazione
- **Risultati chiave**:
- Senza documentazione: tasso di successo del 53%
- Skills (comportamento predefinito): 53% (+0pp, nessun guadagno!)
- Skills con istruzioni esplicite: 79% (+26pp)
- **AGENTS.md con indice: 100% (+47pp)**
- **Fragilità delle skills**: nel 56% dei casi di valutazione, la skill non è mai stata invocata dall'agente
- **Anche con istruzioni esplicite**: l'invocazione delle skill è salita oltre il 95%, ma il successo dipendeva fortemente dalla formulazione esatta
- **Compressione riuscita**: documentazione compressa da 40 KB a 8 KB (riduzione dell'80%) con un formato delimitato da pipe, senza perdita di prestazioni
- **Teoria dei 3 vantaggi del contesto passivo**: 1. Nessun punto decisionale (informazione disponibile senza una scelta da fare) 2. Disponibilità costante (AGENTS.md nel system prompt a ogni turno) 3. Nessun problema di ordinamento (nessuna sequenza di azioni)
- **Raccomandazioni pratiche**: non attendere che le skills migliorino, comprimere aggressivamente gli indici, costruire valutazioni mirate alle API esterne ai dati di addestramento
- **Installazione**: `npx @next/codemod@canary agents-md` rileva la versione, scarica la documentazione e inietta l'indice in AGENTS.md
- **Sfumatura importante**: le skills restano utili per flussi di lavoro d'azione specifici attivati esplicitamente, ma per la conoscenza generale di un framework il contesto passivo prevale

## RésuméDe400mots

Jude Gao di Vercel presenta i risultati di una valutazione comparativa tra due approcci per trasmettere conoscenze specifiche di un framework agli agenti IA: skills (recupero attivo) e AGENTS.md (contesto passivo). Il risultato è inequivocabile: il metodo più semplice supera nettamente quello più sofisticato.

**Il problema**: Next.js 16 introduce nuove API (`use cache`, `connection()`, `forbidden()`) assenti dai dati di addestramento dei modelli IA. Senza documentazione aggiornata, gli agenti generano codice errato nel 47% dei casi.

**Skills: il fallimento del recupero attivo**: Le skills, uno standard aperto per impacchettare conoscenza invocabile su richiesta, si rivelano fragili. Nel 56% dei casi di valutazione, l'agente non ha mai invocato la skill disponibile, producendo un tasso di successo identico al riferimento di base (53%). Anche aggiungendo istruzioni esplicite che forzano l'invocazione (tasso di invocazione superiore al 95%), il tasso di successo sale solo al 79%, e i risultati variano drasticamente a seconda della formulazione esatta delle istruzioni.

**AGENTS.md: la vittoria del contesto passivo**: Un file markdown statico iniettato nel system prompt a ogni turno raggiunge un tasso di successo del 100% (build, lint e test). Questo approccio elimina tre fonti di fragilità: il punto decisionale (l'agente non deve scegliere di invocare), i problemi di disponibilità (l'informazione è sempre presente) e le questioni di ordinamento (nessuna sequenza di azioni richiesta).

**Compressione aggressiva**: Il team Vercel è riuscito a comprimere 40 KB di documentazione in un indice di 8 KB (una riduzione dell'80%) utilizzando un formato delimitato da pipe, mantenendo il tasso di successo del 100%. Questa compressione è essenziale poiché AGENTS.md consuma finestra di contesto a ogni interazione.

**Implicazioni per l'ecosistema**: I risultati suggeriscono che, per la conoscenza generale di un framework, il contesto passivo (sempre disponibile) supera il recupero attivo (su richiesta). Le skills conservano comunque la loro utilità per i flussi di lavoro d'azione espliciti. Vercel fornisce un comando di installazione (`npx @next/codemod@canary agents-md`) che rileva automaticamente la versione di Next.js e genera l'AGENTS.md corrispondente.

**Raccomandazioni**: Non attendere che le skills migliorino, comprimere aggressivamente la documentazione in indici e costruire valutazioni che mirino specificamente alle API assenti dai dati di addestramento. Questi risultati hanno implicazioni dirette per tutti i maintainer di framework e librerie che cercano di ottimizzare la compatibilità con gli agenti di codifica 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/it/fiches/gao-vercel-agents-md-outperforms-skills-evals-2026-01-27/