AGENTS.md vs Skills: What Vercel Learned
January 30, 2026
Vercel recently published research that challenges assumptions about how we should give agents access to framework knowledge. The TL;DR: passive context beats active retrieval.
The Key Finding
In evals focused on Next.js 16 APIs, Vercel compared two approaches:
That last row is striking: skills with default behavior performed no better than having no documentation at all.
Why Skills Underperformed
In 56% of eval cases, the agent never invoked the skill. It had access to the documentation but chose not to use it.
This isn't a bug in Vercel's setup — it's a known limitation of current models. Agents don't reliably use available tools, even when those tools would help.
Even with explicit instructions ("Before writing code, invoke the nextjs-doc skill"), the wording was fragile:
- "You MUST invoke the skill first" → agent reads docs, misses project context
- "Explore project first, then invoke skill" → better results
Same skill. Same docs. Different outcomes from subtle wording changes.
The Passive Context Advantage
AGENTS.md takes a different approach: embed the knowledge directly in the context window. The agent doesn't need to decide to look something up — it's already there on every turn.
Vercel compressed their Next.js 16 docs into an 8KB index that lives in AGENTS.md. Result: 100% pass rate on their evals.
The insight: the WHAT matters more than the HOW. If you give the agent the right information passively, it performs better than if you make it actively retrieve that information.
When to Use Each
Use AGENTS.md for:
- Framework/library knowledge the agent needs constantly
- Project-specific conventions and patterns
- Critical context that applies across most tasks
- Knowledge small enough to fit in context (~10-50KB)
Use Skills for:
- Specialized tasks that need tools/scripts
- Large reference documentation (too big for context)
- Capabilities that require external actions
- Knowledge needed only occasionally
Setting Up AGENTS.md
Create an AGENTS.md file in your project root:
# AGENTS.md
## Project Overview
Next.js 16 app with App Router, TypeScript, Tailwind.
## Key APIs
- Use `connection()` for dynamic rendering
- Use `'use cache'` directive for caching
- `cookies()` and `headers()` are async in Next.js 16
## Conventions
- Server Components by default
- Colocate data fetching with components
- Use dynamic imports for heavy client components
Most coding agents (Claude Code, Cursor, Codex) will automatically read this file.
The Bigger Picture
This research suggests we may be over-engineering agent knowledge systems. Before building complex skill retrieval pipelines, try the simple thing: write down what the agent needs to know and put it in context.
As Vercel put it: "Context that's always available beats context that requires a decision to access."
Sources
- AGENTS.md outperforms skills in our agent evals — Vercel Blog
- Agent Skills Specification — Open standard
- agents.md — Community convention