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

## Veille

AGENTS.md übertrifft Skills bei Vercel/Next.js-Agentenbewertungen

## 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, KI-Agenten-Evaluation, passiver Kontext, aktiver Abruf, Next.js 16, Vercel, veraltete Trainingsdaten, komprimierte Dokumentation, System-Prompt, agentisches Coding, use cache, connection(), forbidden()

## Authors

Jude Gao (Vercel)

## Ton

**Profil**: Empirischer Fachbeitrag, analytisches und faktisches Register, fortgeschrittenes technisches Niveau

**Beschreibung**: Engineering-Blogbeitrag, der einen rigorosen wissenschaftlichen Ansatz mit Evaluationsprotokoll, Tabellen quantifizierter Ergebnisse und Vergleichsanalyse verfolgt. Der Ton ist der eines Ingenieurs, der experimentelle Ergebnisse transparent teilt, einschließlich Fehlschlägen (Skills in 56 % der Fälle nicht aufgerufen). Die Argumentation ist datengetrieben mit präzisen Prozentangaben. Die Zielgruppe besteht aus Entwicklern und Framework-Betreuern, die die Erfahrung ihrer Nutzer mit KI-Coding-Agenten optimieren möchten.

## Pense-betes

- **Zugrunde liegendes Problem**: KI-Modelle verfügen über veraltete Trainingsdaten. Next.js 16 führt APIs ein (`use cache`, `connection()`, `forbidden()`), die in den Trainingsdaten fehlen, was zu fehlerhaftem Code führt
- **Zwei getestete Ansätze**:
- **Skills**: offener Standard zur Verpackung von Wissen, vom Agenten auf Abruf aufrufbar
- **AGENTS.md**: statische Markdown-Datei, die bei jeder Interaktion persistenten Kontext liefert
- **Zentrale Ergebnisse**:
- Ohne Dokumentation: 53 % Erfolgsquote
- Skills (Standardverhalten): 53 % (+0 Prozentpunkte, kein Gewinn!)
- Skills mit expliziten Anweisungen: 79 % (+26 Prozentpunkte)
- **AGENTS.md mit Index: 100 % (+47 Prozentpunkte)**
- **Fragilität von Skills**: in 56 % der Evaluationsfälle wurde der Skill vom Agenten nie aufgerufen
- **Selbst mit expliziten Anweisungen**: der Skill-Aufruf stieg auf über 95 %, aber der Erfolg hing stark von der exakten Formulierung ab
- **Erfolgreiche Komprimierung**: Dokumentation von 40 KB auf 8 KB komprimiert (80 % Reduktion) mit einem Pipe-getrennten Format, ohne Leistungseinbußen
- **Theorie der 3 Vorteile des passiven Kontexts**: 1. Kein Entscheidungspunkt (Information verfügbar, ohne dass eine Wahl getroffen werden muss) 2. Konstante Verfügbarkeit (AGENTS.md bei jedem Turn im System-Prompt) 3. Keine Reihenfolgeprobleme (keine Handlungsabfolge)
- **Praktische Empfehlungen**: nicht auf eine Verbesserung der Skills warten, Indizes aggressiv komprimieren, Evaluationen erstellen, die auf APIs außerhalb der Trainingsdaten abzielen
- **Installation**: `npx @next/codemod@canary agents-md` erkennt die Version, lädt die Dokumentation herunter und fügt den Index in AGENTS.md ein
- **Wichtige Nuance**: Skills bleiben nützlich für explizit ausgelöste spezifische Aktions-Workflows, aber für allgemeines Framework-Wissen übertrifft passiver Kontext

## RésuméDe400mots

Jude Gao von Vercel stellt die Ergebnisse einer Vergleichsevaluation zwischen zwei Ansätzen zur Vermittlung frameworkspezifischen Wissens an KI-Agenten vor: Skills (aktiver Abruf) und AGENTS.md (passiver Kontext). Der Befund ist eindeutig: Die einfachere Methode übertrifft die ausgefeiltere deutlich.

**Das Problem**: Next.js 16 führt neue APIs ein (`use cache`, `connection()`, `forbidden()`), die in den Trainingsdaten der KI-Modelle fehlen. Ohne aktualisierte Dokumentation generieren Agenten in 47 % der Fälle fehlerhaften Code.

**Skills: das Scheitern des aktiven Abrufs**: Skills, ein offener Standard zur Verpackung von auf Abruf aufrufbarem Wissen, erweisen sich als fragil. In 56 % der Evaluationsfälle rief der Agent den verfügbaren Skill nie auf, was eine Erfolgsquote ergab, die mit der Baseline identisch war (53 %). Selbst nach Hinzufügen expliziter Anweisungen, die den Aufruf erzwingen (Aufrufrate über 95 %), steigt die Erfolgsquote nur auf 79 %, und die Ergebnisse schwanken erheblich je nach exakter Formulierung der Anweisungen.

**AGENTS.md: der Sieg des passiven Kontexts**: Eine statische Markdown-Datei, die bei jedem Turn in den System-Prompt eingefügt wird, erreicht eine Erfolgsquote von 100 % (Build, Lint und Tests). Dieser Ansatz beseitigt drei Fragilitätsquellen: den Entscheidungspunkt (der Agent muss sich nicht für einen Aufruf entscheiden), Verfügbarkeitsprobleme (die Information ist immer vorhanden) und Reihenfolgefragen (keine Handlungsabfolge erforderlich).

**Aggressive Komprimierung**: Dem Vercel-Team gelang es, 40 KB Dokumentation zu einem 8 KB großen Index zu komprimieren (eine Reduktion um 80 %) unter Verwendung eines Pipe-getrennten Formats, wobei die Erfolgsquote von 100 % erhalten blieb. Diese Komprimierung ist essenziell, da AGENTS.md bei jeder Interaktion Kontextfenster verbraucht.

**Implikationen für das Ökosystem**: Die Ergebnisse legen nahe, dass für allgemeines Framework-Wissen passiver Kontext (immer verfügbar) aktiven Abruf (auf Abruf) übertrifft. Skills behalten dennoch ihren Nutzen für explizite Aktions-Workflows. Vercel stellt einen Installationsbefehl bereit (`npx @next/codemod@canary agents-md`), der automatisch die Next.js-Version erkennt und die entsprechende AGENTS.md generiert.

**Empfehlungen**: Nicht auf eine Verbesserung der Skills warten, Dokumentation aggressiv zu Indizes komprimieren und Evaluationen erstellen, die gezielt auf APIs abzielen, die in den Trainingsdaten fehlen. Diese Ergebnisse haben direkte Implikationen für alle Framework- und Bibliotheksbetreuer, die die Kompatibilität mit KI-Coding-Agenten optimieren möchten.

## 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/de/fiches/gao-vercel-agents-md-outperforms-skills-evals-2026-01-27/