Compressed Agents.md > Agent Skills
12 days ago
- #Documentation
- #AI Coding Agents
- #Next.js
- Skills for teaching coding agents framework-specific knowledge in Next.js 16 APIs maxed out at 79% pass rate with explicit instructions, but performed no better than no documentation without them.
- A compressed 8KB docs index embedded in AGENTS.md achieved a 100% pass rate, outperforming skills by providing persistent context without requiring agent decision-making.
- The problem addressed was outdated training data in AI coding agents, leading to incorrect code generation for new Next.js 16 APIs like 'use cache', 'connection()', and 'forbidden()'.
- Two approaches were tested: Skills (on-demand retrieval of framework docs) and AGENTS.md (persistent context in a markdown file).
- Skills were not reliably triggered (56% of cases), and explicit instructions to use them improved pass rates to 79% but were fragile to wording changes.
- AGENTS.md with a compressed docs index and key instruction ('Prefer retrieval-led reasoning over pre-training-led reasoning') achieved perfect scores across Build, Lint, and Test.
- The success of AGENTS.md is attributed to no decision point for the agent, consistent availability, and no ordering issues compared to skills.
- A CLI command ('npx @next/codemod@canary agents-md') was provided to set up the AGENTS.md approach for any Next.js project, detecting the version and injecting the docs index.
- Recommendations for framework authors include using AGENTS.md for broad improvements, compressing docs aggressively, and designing for retrieval-led reasoning.