.cursorrules vs AGENTS.md vs CLAUDE.md: Which Actually Works?

Vercel's eval data shocked the AI coding community: a simple AGENTS.md file achieved a 100% pass rate while Skills — the hot new standard everyone was betting on — 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.

This guide breaks down every major approach — AGENTS.md, custom instructions, skills, and rules files — with real data, a detailed comparison table, and clear recommendations for when to use each one.

What Are the Different Approaches?

Before 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?

AGENTS.md (Passive Context Files)

AGENTS.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 — coding standards, architecture rules, API documentation, framework-specific patterns — is automatically available without the agent needing to decide to load it.

Claude 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:

• Always loaded — no decision-making required by the agent
• Project-specific — lives in the repo, version-controlled
• Low overhead — just a markdown file, no infrastructure
• Limited by context window — everything must fit in the token budget

Custom Instructions (Platform-Level Rules)

Custom 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.

Unlike AGENTS.md, custom instructions aren't project-specific — 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.

Skills (On-Demand Knowledge Retrieval)

Skills 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.

Think 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.

The theory is elegant: less context waste, modular knowledge, community-shareable packages. The practice, as Vercel discovered, is more complicated.

Rules Files (.cursorrules, .clinerules, etc.)

Tool-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.

Vercel's Data: AGENTS.md Wins Decisively

Vercel built a hardened eval suite targeting Next.js 16 APIs that aren't in any model's training data — connection(), 'use cache', cacheLife(), forbidden(), and more. They tested four configurations and the results were unambiguous:

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.

Even when Vercel added explicit instructions telling the agent to use skills, the results were fragile. Different wordings produced dramatically different outcomes — \"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.

The 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.

Full Comparison: Every Approach Side by Side

When to Use Each Approach

Use AGENTS.md When...

• You need consistent, reliable behavior across every agent interaction
• Your project uses frameworks with APIs outside model training data
• Multiple team members use different AI coding tools
• You want project context that's version-controlled and code-reviewed
• The critical context fits within ~8-15KB (compressed)

Use Custom Instructions When...

• You have personal coding preferences that apply across all projects
• Your organization enforces standards across every repo
• You want rules that follow you, not the project
• Examples: code style, language preferences, response format

Use Skills When...

• You have deep specialized knowledge that's too large for AGENTS.md
• The knowledge is only relevant to specific task types
• You want to share packaged expertise with the community
• You're willing to add explicit invocation instructions to your AGENTS.md

Use Rules Files When...

• You're locked into a single tool (Cursor, Cline, Windsurf)
• You need tool-specific configurations that AGENTS.md doesn't support
• You're gradually migrating to AGENTS.md (use both during transition)

The Best Strategy: Layer Them Together

The real power move isn't choosing one approach — it's layering them strategically. Here's the stack that top engineering teams are using in 2026:

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%.

So 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 — using AGENTS.md as the \"router\" that ensures agents always have baseline context while skills provide supplementary depth on demand.

The Paradigm Shift: From On-Demand to Passive Context

Vercel's findings represent a broader shift in how we think about AI agent context. The industry bet heavily on on-demand retrieval — RAG systems, tool calls, skills — assuming agents would intelligently fetch what they need. The data tells a different story.

Current 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 — it's a fundamental challenge with how LLMs handle tool-use decisions.

The 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.

This parallels what we're seeing across the AI tooling ecosystem. The simplest approaches — flat files, direct context injection, minimal abstraction — 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.

How to Set Up AGENTS.md Today

Based on Vercel's approach, here's a practical setup:

1. Create AGENTS.md in your project root
2. Add a compressed docs index — not full documentation, but an index pointing to doc files in your repo
3. Include the key instruction: \"Prefer retrieval-led reasoning over pre-training-led reasoning\"
4. Keep it under 8-15KB — Vercel's winning file was just 8KB compressed
5. Version-match your docs — include only documentation for the framework versions your project actually uses
6. Add skill triggers — if you use skills, explicitly tell the agent when to invoke them

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.

FAQ

Does AGENTS.md work with all AI coding tools?

Most 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?

Yes, passive context uses tokens every turn — 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.

Are Skills dead after Vercel's findings?

No. 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 — with explicit instructions in AGENTS.md telling the agent when to invoke them.

Can I use AGENTS.md and custom instructions together?

Absolutely — 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.

How often should I update my AGENTS.md file?

Treat 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.