A simple text file beats complex skill systems for AI coding agents

In practice, that didn't happen. According to Vercel, the agent never called the skill in 56 percent of cases. It had access to the documentation but simply didn't use it. The pass rate with skills was identical to the baseline without any documentation at all: 53 percent.

Only explicit instructions telling the agent to use the skill pushed the trigger rate above 95 percent and the pass rate to 79 percent. But this created a new problem: the exact wording made a dramatic difference. "You MUST invoke the skill" caused the agent to miss project context, while "Explore project first, then invoke skill" produced better results.

Passive context delivered a perfect score

The alternative was dead simple. Instead of relying on the agent's judgment, the team embedded a compressed documentation index directly into the AGENTS.md file. This Markdown file sits in the project root and gives the agent persistent context on every turn, without the agent having to actively decide anything.

The original 40-kilobyte documentation index was compressed down to 8 kilobytes with no drop in success rate. The agent knows where to find specific docs without needing the full content in context.

Vercel's team points to three reasons the passive approach won out. First, there's no decision point, since the information is already there. Second, availability is consistent because AGENTS.md content gets included in the system prompt on every turn. Third, there are no sequencing issues like the ones that caused inconsistent results with skills.

Vercel is clear that skills aren't useless. The company says they're better suited for vertical, action-specific workflows like "upgrade my Next.js version." For general framework knowledge, though, passive context currently outperforms on-demand retrieval.

For Next.js projects, Vercel provides a command that automates the setup: npx @next/codemod@canary agents-md detects the installed version, pulls the right documentation, and injects the compressed index.

AGENTS.md is becoming part of a broader industry standard

Vercel's findings highlight the growing importance of AGENTS.md, which has become part of a wider industry push. In December 2025, the Linux Foundation launched the Agentic AI Foundation (AAIF), bringing direct competitors like OpenAI, Anthropic, Google, and Microsoft together to build open standards for AI agents.

Three open-source projects make up the core. Anthropic's Model Context Protocol (MCP) connects models with external data, Block's Goose serves as a framework for agent workflows, and OpenAI's AGENTS.md sets standards for coding instructions. According to the Linux Foundation, AGENTS.md has already been adopted by more than 60,000 open-source projects and is natively supported by agent frameworks like Cursor, Devin, GitHub Copilot, and Gemini CLI.

The Skill system Vercel tested is an open standard that Anthropic also uses in its Claude products. In October 2025, the company rolled out Skills as a modular system where Claude figures out on its own which specialized instructions and resources a given task needs.