Jude Gao from Vercel presents the results of a comparative evaluation between two approaches for conveying framework-specific knowledge to AI agents: skills (active retrieval) and AGENTS.md (passive context). The finding is unambiguous: the simpler method significantly outperforms the more sophisticated one.

The problem: Next.js 16 introduces new APIs (use cache, connection(), forbidden()) absent from AI models' training data. Without updated documentation, agents generate incorrect code in 47% of cases.

Skills: the failure of active retrieval: Skills, an open standard for packaging knowledge invocable on demand, prove fragile. In 56% of evaluation cases, the agent never invoked the available skill, producing a success rate identical to the baseline (53%). Even when adding explicit instructions forcing invocation (95%+ invocation rate), the success rate only rises to 79%, and results vary dramatically depending on the exact wording of the instructions.

AGENTS.md: the victory of passive context: A static markdown file injected into the system prompt on every turn achieves a 100% success rate (build, lint, and tests). This approach eliminates three sources of fragility: the decision point (the agent does not have to choose to invoke), availability issues (the information is always present), and ordering concerns (no action sequencing required).

Aggressive compression: The Vercel team managed to compress 40 KB of documentation into an 8 KB index (an 80% reduction) using a pipe-delimited format, while maintaining the 100% success rate. This compression is essential because AGENTS.md consumes context window on every interaction.

Implications for the ecosystem: The results suggest that for general framework knowledge, passive context (always available) outperforms active retrieval (on demand). Skills nonetheless retain their usefulness for explicit action workflows. Vercel provides an installation command (npx @next/codemod@canary agents-md) that automatically detects the Next.js version and generates the corresponding AGENTS.md.

Recommendations: Do not wait for skills to improve, compress documentation aggressively into indexes, and build evaluations that specifically target APIs absent from training data. These results have direct implications for all framework and library maintainers seeking to optimize compatibility with AI coding agents.