AGENTS.md is a simple markdown file placed in your project root that gives AI coding agents persistent context about your codebase. Think of it as a README for AI agents — a single, predictable place where tools like Cursor, Claude Code, GitHub Copilot, and others can find your project's rules, conventions, and documentation pointers without you repeating instructions every session.
In January 2026, Vercel published eval results that shocked the AI coding community: an 8KB compressed docs index embedded in AGENTS.md achieved a 100% pass rate on their Next.js 16 evaluation suite — while the more sophisticated "skills" approach maxed out at 79%. Here's what happened, why it matters, and how you can use AGENTS.md to dramatically improve your own AI coding workflow.
The Problem: AI Agents Use Outdated Training Data
AI coding agents rely on training data that becomes outdated. When Next.js 16 introduced new APIs like use cache, connection(), and forbidden(), those APIs weren't in current model training data. Agents would generate incorrect code or fall back to older patterns.
This is a universal problem. Whether you're using Claude Code, Cursor, or GitHub Copilot, the model's training cutoff means it doesn't know about your framework's latest features, your team's coding conventions, or your project's specific architecture. And if you're working with tools that use AI coding agents daily, outdated context is costing you time and quality.
Vercel's Experiment: Skills vs. AGENTS.md
Vercel tested two approaches to solve this problem:
- Skills — an open standard for packaging domain knowledge that agents can invoke on demand. The agent recognizes when it needs framework help, invokes the skill, and gets relevant docs.
- AGENTS.md — a markdown file in the project root that provides persistent context to coding agents. Whatever you put in AGENTS.md is available on every turn, without the agent deciding to load it.
They built a Next.js docs skill and an AGENTS.md docs index, then ran them through a hardened eval suite targeting Next.js 16 APIs that aren't in model training data.
The Results: 53% to 100%
Here are Vercel's final pass rates across all four configurations:
| Configuration | Pass Rate | vs Baseline |
|---|---|---|
| Baseline (no docs) | 53% | — |
| Skill (default behavior) | 53% | +0pp |
| Skill + explicit instructions | 79% | +26pp |
| AGENTS.md docs index | 100% | +47pp |
On the detailed Build/Lint/Test breakdown, AGENTS.md achieved perfect scores across all three categories:
| Configuration | Build | Lint | Test |
|---|---|---|---|
| Baseline | 84% | 95% | 63% |
| Skill (default) | 84% | 89% | 58% |
| Skill + instructions | 95% | 100% | 84% |
| AGENTS.md | 100% | 100% | 100% |
The "dumb" approach — a static markdown file — completely outperformed the more sophisticated skill-based retrieval system.
Why Skills Failed: The 56% Problem
In 56% of eval cases, the skill was never invoked. The agent had access to the documentation but simply didn't use it. Adding the skill produced zero improvement over baseline — and actually performed worse on some metrics (58% vs 63% on tests), suggesting unused skills in the environment may introduce noise or distraction.
This isn't unique to Vercel's setup. Agents not reliably using available tools is a known limitation of current models. Even when Vercel added explicit instructions telling the agent to use the skill, wording changes produced dramatically different outcomes. The instruction "You MUST invoke the skill" caused the agent to anchor too heavily on docs and miss project context, while "Explore project first, then invoke skill" worked better.
This fragility is exactly why AGENTS.md works so well — it removes the decision entirely.
Why Passive Context Beats On-Demand Retrieval
Vercel's working theory comes down to three factors:
- No decision point. With AGENTS.md, there's no moment where the agent must decide "should I look this up?" The information is already present in context.
- Consistent availability. Skills load asynchronously and only when invoked. AGENTS.md content is in the system prompt for every turn.
- No ordering issues. Skills create sequencing decisions (read docs first vs. explore project first). Passive context avoids this entirely.
This is a critical insight for anyone building with AI agents in 2026. The more you can pre-load relevant context — rather than relying on the agent to fetch it — the better your results will be. At Serenities AI, we've seen this same pattern play out across different AI coding tools: agents perform dramatically better when they have upfront context about what they're working with.
How to Structure an AGENTS.md File
An AGENTS.md file is just plain markdown — no JSON schema, no YAML, no special syntax. Here's a practical template you can adapt for any project:
# AGENTS.md
## Project Overview
- Framework: Next.js 16 (App Router)
- Language: TypeScript 5.x
- Package Manager: pnpm
- Node.js: 20+
## Build & Dev Commands
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
## Code Conventions
- Use async/await over callbacks
- Prefer named exports
- Use TypeScript strict mode
- Components go in src/components/
- API routes go in src/app/api/
## Important Rules
- NEVER commit API keys or secrets
- Always use environment variables for config
- Prefer retrieval-led reasoning over pre-training-led reasoning
- Run lint before committing
## Framework-Specific Notes
- Use 'use cache' directive for static data
- Use connection() for dynamic rendering
- Use forbidden() and unauthorized() for auth
- Async cookies() and headers() in App Router
The key sections that deliver the biggest impact are: preferred language/runtime versions, exact build/test/lint commands, naming and formatting conventions, testing expectations, and explicit boundaries ("never commit credentials," "prefer async in this module").
The Pipe-Delimited Compression Technique
One of the most clever insights from Vercel's experiment is how they handled context window bloat. The initial docs injection was around 40KB. They compressed it down to 8KB — an 80% reduction — while maintaining the 100% pass rate.
The compressed format uses a pipe-delimited structure:
[Next.js Docs Index]|root: ./.next-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}
Each line maps a directory path to the doc files it contains. The agent knows where to find docs without having the full content in context. When it needs specific information, it reads the relevant file from the .next-docs/ directory.
This is essentially an index, not the full documentation. The agent gets a roadmap of what's available and can pull up specific files on demand. It's the best of both worlds: minimal context overhead with maximum discoverability.
Retrieval-Led vs. Pre-Training-Led Reasoning
A key instruction embedded in Vercel's AGENTS.md was: "IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks."
This single line tells the agent to consult the provided docs rather than rely on potentially outdated training data. It's a simple but powerful distinction:
| Approach | How It Works | Best For |
|---|---|---|
| Pre-training-led | Agent relies on training data | Stable, well-known APIs |
| Retrieval-led | Agent consults provided docs first | New APIs, custom conventions |
For any framework or library that's actively evolving — which is most of them in 2026 — retrieval-led reasoning should be your default. Your AGENTS.md file is the mechanism to make that happen reliably.
How to Set Up AGENTS.md for Next.js
If you're working with Next.js, Vercel made setup trivial with a single command:
npx @next/codemod@canary agents-mdThis command detects your Next.js version, downloads matching documentation to .next-docs/, and injects the compressed index into your AGENTS.md. If you're using an agent that respects AGENTS.md (Cursor, Claude Code, GitHub Copilot, and others), the agent will automatically pick up the context.
For non-Next.js projects, you'll need to create AGENTS.md manually. But the principle is the same: give your agent a compressed index of where to find version-matched documentation, and tell it to prefer retrieval over training data. This approach works for any AI coding agent that reads project-root markdown files.
Best Practices for Your AGENTS.md
- Don't wait for skills to improve. The gap may close as models get better at tool use, but results matter now. AGENTS.md delivers today.
- Compress aggressively. You don't need full docs in context. An index pointing to retrievable files works just as well — and keeps your token usage down.
- Test with evals. Build evals targeting APIs not in training data. That's where doc access matters most.
- Design for retrieval. Structure your docs so agents can find and read specific files rather than needing everything upfront.
- Include explicit instructions. Tell the agent to prefer retrieval-led reasoning. A single line can significantly change behavior.
- Keep it updated. AGENTS.md is only useful if it reflects your current project state. Treat it like documentation — update it when your stack changes.
What This Means for the Industry
Vercel's findings validate something many developers have intuited: AI agents work better when you give them context upfront rather than expecting them to find it. Over 60,000 repositories now contain AGENTS.md, and that number is growing fast.
The implications extend beyond just Next.js. Any framework author who wants AI coding agents to generate correct code should consider providing an AGENTS.md snippet that users can add to their projects. And any development team using AI tools should invest 10 minutes creating an AGENTS.md — the ROI, based on Vercel's data, is a near-doubling of agent accuracy.
Skills aren't useless — they work well for vertical, action-specific workflows like "upgrade my Next.js version" or "migrate to the App Router." But for general framework knowledge, passive context currently outperforms on-demand retrieval. The two approaches complement each other, and the smart move is to use both.
Frequently Asked Questions
What tools support AGENTS.md?
As of February 2026, AGENTS.md is supported by Cursor, Claude Code (which uses CLAUDE.md for the same purpose), GitHub Copilot agent mode, Continue.dev, Aider, OpenHands, and Windsurf. Most tools now fall back to reading AGENTS.md when their proprietary config file is missing. The format is just markdown, so any tool that reads project-root files can use it.
Does AGENTS.md replace .cursorrules or CLAUDE.md?
AGENTS.md is meant to be a universal, tool-agnostic standard. You can still use tool-specific files (.cursorrules, CLAUDE.md, .gemini), but AGENTS.md serves as a single source of truth that works across all agents. Many teams are migrating to AGENTS.md to avoid maintaining multiple overlapping config files.
How big should my AGENTS.md file be?
Vercel showed that a compressed 8KB docs index achieved 100% pass rates. For most projects, your AGENTS.md should be between 2KB and 10KB. Focus on the essentials: build commands, code conventions, framework notes, and a docs index if applicable. Use the pipe-delimited compression technique if you need to reference large documentation sets.
Will skills catch up to AGENTS.md performance?
Possibly. As AI models improve at tool use, skills may become more reliably triggered. But for now, passive context consistently outperforms on-demand retrieval. Vercel recommends using both approaches — AGENTS.md for broad horizontal improvements and skills for specific vertical workflows.
Can I use AGENTS.md for non-JavaScript projects?
Absolutely. AGENTS.md is language-agnostic. The format works for Python, Go, Rust, or any other language. The key is providing your agent with project-specific context: build commands, conventions, framework docs, and explicit instructions about how you want code written.