AGENTS.md outperforms skills in our agent evals
By Steven Van ·
In Next.js 16 evals, an 8KB AGENTS.md docs index scored 100% versus 79% for Agent Skills, even with explicit instructions to use them.
Vercel benchmarked two ways of teaching coding agents about Next.js 16 APIs, like 'use cache', connection(), and forbidden(), that aren't in current model training data: Agent Skills, and a documentation index embedded directly in AGENTS.md.
An 8KB docs index placed in AGENTS.md, which loads into an agent's context on every turn without it having to decide to fetch anything, reached a 100% pass rate in Vercel's evals. A Next.js docs skill, which the agent has to recognize and invoke on its own, maxed out at 79%, and only when explicitly told to use it. Without that instruction, the skill performed no better than giving the agent no documentation at all.
Vercel published the setup and results in AGENTS.md outperforms skills in our agent evals, along with how to add a version-matched docs index to AGENTS.md for a Next.js project.