Vercel's eval data shocked the AI coding community: a simple AGENTS.md file achieved a 100% pass rate while Skills \u2014 the hot new standard everyone was betting on \u2014 topped out at just 53% without explicit instructions. If you're trying to figure out the best way to guide AI coding agents in 2026, you're not alone. The landscape of context-delivery methods has exploded, and choosing wrong means wasted tokens, inconsistent output, and frustrated developers.
\n\nThis guide breaks down every major approach \u2014 AGENTS.md, custom instructions, skills, and rules files \u2014 with real data, a detailed comparison table, and clear recommendations for when to use each one.
\n\nWhat Are the Different Approaches?
\n\nBefore diving into which method wins, let's define what we're comparing. Each approach solves the same fundamental problem: how do you give an AI coding agent the right context to produce correct code?
\n\nAGENTS.md (Passive Context Files)
\n\nAGENTS.md is a markdown file placed in your project root that provides persistent context to AI coding agents on every turn. Whatever you put in this file \u2014 coding standards, architecture rules, API documentation, framework-specific patterns \u2014 is automatically available without the agent needing to decide to load it.
\n\nClaude Code uses CLAUDE.md for the same purpose. Cursor supports .cursorrules. The concept is identical: a static file that the agent reads at the start of every session.
Key characteristics:
\n- \n
- Always loaded \u2014 no decision-making required by the agent \n
- Project-specific \u2014 lives in the repo, version-controlled \n
- Low overhead \u2014 just a markdown file, no infrastructure \n
- Limited by context window \u2014 everything must fit in the token budget \n
Custom Instructions (Platform-Level Rules)
\n\nCustom instructions are user or organization-level rules set within an AI platform. ChatGPT's \"Custom Instructions,\" Claude's system prompts, and Copilot's organization-wide settings all fall into this category.
\n\nUnlike AGENTS.md, custom instructions aren't project-specific \u2014 they follow you across every conversation. They're ideal for personal coding preferences (like \"always use TypeScript strict mode\" or \"prefer functional components\") but lack the granularity of project-level context.
\n\nSkills (On-Demand Knowledge Retrieval)
\n\nSkills are an open standard for packaging domain knowledge that coding agents can invoke on demand. A skill bundles prompts, tools, and documentation into a folder that the agent discovers and loads only when relevant.
\n\nThink of skills as \"lazy loading for context.\" The agent scans skill descriptions, then loads full content only when it determines a skill matches the current task. GitHub Copilot, VS Code, and Claude Code all support the Agent Skills standard.
\n\nThe theory is elegant: less context waste, modular knowledge, community-shareable packages. The practice, as Vercel discovered, is more complicated.
\n\nRules Files (.cursorrules, .clinerules, etc.)
\n\nTool-specific rules files serve the same purpose as AGENTS.md but are locked to a particular tool. .cursorrules only works in Cursor. .clinerules only works in Cline. .windsurfrules only works in Windsurf.
These were the first generation of passive context files. AGENTS.md emerged as the cross-tool standard that works across Claude Code, Cursor, GitHub Copilot, and more. If you're still using tool-specific rules files, it's worth migrating to AGENTS.md for portability. For a deeper look at how AI coding agents are reshaping development workflows, check out our guide on AI coding agents replacing traditional frameworks in 2026.
\n\nVercel's Data: AGENTS.md Wins Decisively
\n\nVercel built a hardened eval suite targeting Next.js 16 APIs that aren't in any model's training data \u2014 connection(), 'use cache', cacheLife(), forbidden(), and more. They tested four configurations and the results were unambiguous:
| Configuration | \nPass Rate | \nvs Baseline | \n
|---|---|---|
| Baseline (no docs) | \n53% | \n\u2014 | \n
| Skill (default) | \n53% | \n+0pp | \n
| Skill + explicit instructions | \n79% | \n+26pp | \n
| AGENTS.md docs index | \n100% | \n+47pp | \n
The most striking finding: skills with default behavior performed no better than having no documentation at all. In 56% of eval cases, the agent never even invoked the skill. The knowledge was available but the agent chose not to use it.
\n\nEven when Vercel added explicit instructions telling the agent to use skills, the results were fragile. Different wordings produced dramatically different outcomes \u2014 \"You MUST invoke the skill\" caused the agent to anchor on docs and miss project context, while \"Explore project first, then invoke skill\" worked better. Same skill, same docs, wildly different results based on subtle phrasing.
\n\nThe AGENTS.md approach eliminated this decision entirely. By embedding a compressed 8KB docs index directly in the file, the agent always had the right context without needing to decide to fetch it.
\n\nFull Comparison: Every Approach Side by Side
\n\n| Feature | \nAGENTS.md | \nCustom Instructions | \nSkills | \nRules Files | \n
|---|---|---|---|---|
| Context delivery | \nPassive (always loaded) | \nPassive (always loaded) | \nOn-demand (agent decides) | \nPassive (always loaded) | \n
| Scope | \nProject-level | \nUser/org-level | \nTask-level | \nProject-level | \n
| Cross-tool support | \n\u2705 Universal standard | \n\u274c Platform-locked | \n\u2705 Open standard | \n\u274c Tool-specific | \n
| Version controlled | \n\u2705 In repo | \n\u274c In platform | \n\u2705 In repo | \n\u2705 In repo | \n
| Reliability (Vercel evals) | \n100% pass rate | \nNot tested | \n53-79% pass rate | \nSimilar to AGENTS.md | \n
| Context efficiency | \nUses tokens every turn | \nUses tokens every turn | \nOnly when invoked | \nUses tokens every turn | \n
| Setup complexity | \nDrop a file in repo root | \nPlatform settings UI | \nFolder structure + metadata | \nDrop a file in repo root | \n
| Shareable | \nVia repo | \nManual copy | \n\u2705 Via skills.sh registry | \nVia repo | \n
| Best for | \nProject standards, framework docs | \nPersonal preferences | \nSpecialized domain knowledge | \nLegacy tool-specific configs | \n
When to Use Each Approach
\n\nUse AGENTS.md When...
\n- \n
- You need consistent, reliable behavior across every agent interaction \n
- Your project uses frameworks with APIs outside model training data \n
- Multiple team members use different AI coding tools \n
- You want project context that's version-controlled and code-reviewed \n
- The critical context fits within ~8-15KB (compressed) \n
Use Custom Instructions When...
\n- \n
- You have personal coding preferences that apply across all projects \n
- Your organization enforces standards across every repo \n
- You want rules that follow you, not the project \n
- Examples: code style, language preferences, response format \n
Use Skills When...
\n- \n
- You have deep specialized knowledge that's too large for AGENTS.md \n
- The knowledge is only relevant to specific task types \n
- You want to share packaged expertise with the community \n
- You're willing to add explicit invocation instructions to your AGENTS.md \n
Use Rules Files When...
\n- \n
- You're locked into a single tool (Cursor, Cline, Windsurf) \n
- You need tool-specific configurations that AGENTS.md doesn't support \n
- You're gradually migrating to AGENTS.md (use both during transition) \n
The Best Strategy: Layer Them Together
\n\nThe real power move isn't choosing one approach \u2014 it's layering them strategically. Here's the stack that top engineering teams are using in 2026:
\n\n| Layer | \nMethod | \nWhat Goes Here | \n
|---|---|---|
| 1. Personal | \nCustom Instructions | \nYour coding style, language, response format | \n
| 2. Project | \nAGENTS.md | \nArchitecture rules, framework docs index, testing standards | \n
| 3. Specialized | \nSkills (with AGENTS.md triggers) | \nDeep domain knowledge, large reference docs | \n
The critical insight from Vercel's research: skills work best when AGENTS.md tells the agent to use them. Without explicit instructions in AGENTS.md, skills were ignored 56% of the time. With instructions, pass rates jumped from 53% to 79%.
\n\nSo the winning pattern is: put your most important context directly in AGENTS.md, then use AGENTS.md to point to skills for deeper dives. At Serenities AI, we've seen teams adopt exactly this layered approach \u2014 using AGENTS.md as the \"router\" that ensures agents always have baseline context while skills provide supplementary depth on demand.
\n\nThe Paradigm Shift: From On-Demand to Passive Context
\n\nVercel's findings represent a broader shift in how we think about AI agent context. The industry bet heavily on on-demand retrieval \u2014 RAG systems, tool calls, skills \u2014 assuming agents would intelligently fetch what they need. The data tells a different story.
\n\nCurrent AI models aren't reliable at deciding when to invoke external knowledge. They skip available tools, get confused by subtle wording differences, and sometimes perform worse with tools available than without them. This isn't a temporary limitation \u2014 it's a fundamental challenge with how LLMs handle tool-use decisions.
\n\nThe solution? Remove the decision. Passive context (AGENTS.md) works because the agent never has to decide whether to use it. The information is just there, every time, like a developer's cheat sheet pinned to their monitor.
\n\nThis parallels what we're seeing across the AI tooling ecosystem. The simplest approaches \u2014 flat files, direct context injection, minimal abstraction \u2014 consistently outperform complex architectures. As we covered in our Claude Code tips and tricks guide, the most effective power users focus on clear, direct context rather than elaborate tool chains.
\n\nHow to Set Up AGENTS.md Today
\n\nBased on Vercel's approach, here's a practical setup:
\n\n- \n
- Create AGENTS.md in your project root \n
- Add a compressed docs index \u2014 not full documentation, but an index pointing to doc files in your repo \n
- Include the key instruction: \"Prefer retrieval-led reasoning over pre-training-led reasoning\" \n
- Keep it under 8-15KB \u2014 Vercel's winning file was just 8KB compressed \n
- Version-match your docs \u2014 include only documentation for the framework versions your project actually uses \n
- Add skill triggers \u2014 if you use skills, explicitly tell the agent when to invoke them \n
For teams using tools like Claude Code or Codex CLI, AGENTS.md works out of the box. Both tools automatically read the file at session start.
\n\nFAQ
\n\nDoes AGENTS.md work with all AI coding tools?
\nMost major AI coding tools support AGENTS.md or an equivalent in 2026. Claude Code reads CLAUDE.md, Cursor reads .cursorrules and AGENTS.md, GitHub Copilot reads AGENTS.md, and VS Code agent mode supports it natively. The AGENTS.md standard is rapidly becoming universal.
Won't AGENTS.md waste tokens on irrelevant context?
\nYes, passive context uses tokens every turn \u2014 that's the tradeoff. But Vercel's data shows the reliability gain far outweighs the token cost. An 8KB file is roughly 2,000 tokens, which is negligible with modern 200K+ context windows. The cost of wrong code from missing context is far higher than a few extra tokens.
\n\nAre Skills dead after Vercel's findings?
\nNo. Skills still have value for deep, specialized knowledge that's too large for AGENTS.md. The key lesson is that skills shouldn't be your primary context delivery method. Use AGENTS.md as the foundation and layer skills on top for specialized tasks \u2014 with explicit instructions in AGENTS.md telling the agent when to invoke them.
\n\nCan I use AGENTS.md and custom instructions together?
\nAbsolutely \u2014 and you should. Custom instructions handle your personal preferences (coding style, language, format). AGENTS.md handles project-specific context (architecture, framework docs, team standards). They operate at different scopes and complement each other perfectly.
\n\nHow often should I update my AGENTS.md file?
\nTreat AGENTS.md like any other configuration file in your repo. Update it when you upgrade frameworks, change architectural patterns, or adopt new conventions. Since it's version-controlled, you can track changes through pull requests just like code. Many teams review their AGENTS.md quarterly or whenever they bump major dependencies.
\n"