On this page
AGENTS.md Explained: The New Standard for AI Coding Agents
AGENTS.md is a vendor-neutral Markdown standard that provides AI coding agents with project-specific context, cutting token waste by up to 17% and runtime by nearly 29%. Following the June 2026 billing reset that eliminated free tier subsidies for most major AI coding tools, it has become a critical cost-control and security artifact for engineering teams.
A single Markdown file is quietly determining whether your AI coding budget doubles overnight. That file is AGENTS.md, and if your team adopted one of the major coding tools after June 2026 without writing one, you’re likely burning 16-20% more tokens than necessary — with zero productivity gain to show for it.
The June billing reset changed everything. Four platforms — OpenAI, GitHub, Anthropic, and Google — reset their pricing models within eighteen days of each other, converting what were effectively generosity subsidies into hard usage-based billing. Teams that sized their workflows around free tiers and unlimited trials are now watching variable costs spike with no warning. The organizations surviving this transition share one trait: they treat context engineering as a cost-control discipline, and AGENTS.md is the primary tool for doing that.
What AGENTS.md Actually Is
AGENTS.md is a plain Markdown file placed at the root of a repository that provides AI coding agents with project-specific instructions, context, and conventions. Think of it as a README written for machines — same format, completely different audience. It was originated by OpenAI in August 2025 for Codex CLI and donated to the Linux Foundation’s Agentic AI Foundation in December 2025, placing it alongside MCP as a vendor-neutral standard.
As of June 2026, the file is read natively by 28-30+ major AI coding tools and ships in over 60,000 open-source repositories. That includes Codex, Cursor, Copilot, Windsurf, Aider, Devin, Gemini CLI, and most of the serious tools in the market. The spec itself has no required fields or schema — just recommended sections covering project overview, build/test commands, code style, testing, security, and commit/PR rules.
The simplicity is the point. One file replaces the fragmented mess of .cursorrules, CLAUDE.md, .github/copilot-instructions.md, GEMINI.md, and CONVENTIONS.md that teams were maintaining in parallel. If you’ve been writing the same build instructions five times for five tools, AGENTS.md is the exit ramp.
The Numbers That Justify It
Here’s where this stops being a documentation nicety and starts being a budget line item. An academic study of 10 repositories and 124 pull requests found that the presence of AGENTS.md is associated with a 28.64% lower median runtime and 16.58% reduced output token consumption during agent execution. That’s not a marginal improvement — that’s the difference between a task finishing in four minutes versus six, and between a thousand tokens and eight hundred thirty.
Under the June 2026 billing models, those token savings translate directly into dollars. Claude Code’s Agent SDK credit pools now bill at API rates — $20/month for Pro, $100 for Max 5x, $200 for Max 20x — and unused credits don’t roll over. GitHub Copilot’s AI Credits work the same way: Pro subscribers get $15 in credits (1,000 base + 500 flex), and agent interactions draw from that pool. Every wasted token is a token you’re not getting back.
Some developers report that without AGENTS.md, agents can burn approximately 20% extra tokens on unnecessary information. Anthropic’s internal benchmarks suggest that CLAUDE.md/AGENTS.md context can reduce wrong-pattern rewrites by 40-60%. That second number matters more than it sounds — wrong-pattern rewrites don’t just waste tokens on the initial generation, they waste tokens on the correction cycle, the code review back-and-forth, and the second attempt.
The June 2026 Billing Reset Changed the Calculus
The synchronized pricing shift across platforms wasn’t coordinated, but the effect is the same as if it were. The June 2026 billing reset included four simultaneous changes: expiration of OpenAI’s Pro 5x boost (June 1), GitHub Copilot’s shift to AI Credits (June 1), Anthropic’s Claude Code credit pool split (June 15), and Google’s Gemini CLI shutdown (June 18).
Before this reset, the cost of context inefficiency was hidden. Free tiers absorbed the waste. Unlimited trials masked the bloat. Temporary boosts — like OpenAI’s Pro 5x promotion that effectively doubled limits — let teams run sloppy agent workflows without seeing the bill. Those subsidies are gone.
The practical impact is stark. Claude Fable 5, which outperformed everything on SWE-Bench Pro at 80.3%, is now API-only at $10/$50 per million tokens after its claude.ai access ended June 22. Teams running agentic loops against that model without tight context control are watching their credit pools drain at a rate their budgets weren’t built for.
For a deeper look at how these billing changes affect specific tools, see our AI coding tools cost analysis and the best AI coding agents in 2026 comparison.
What a Good AGENTS.md Contains
The specification recommends six sections, and the research on what makes them effective is clear: GitHub’s analysis of 2,500+ repositories found that the best files prioritize copy-pasteable commands, real code snippets over descriptive prose, and explicit boundaries over implicit assumptions.
Here’s the structure that works:
- Project overview — one sentence on what the project is, primary language and framework with versions
- Build and test commands — exact commands with flags, not vague tool names (
uv run pytest tests/unit/ -v, not “run tests”) - Code style — only rules that differ from language defaults; don’t repeat what your linter enforces
- Testing instructions — how to run the suite, a single test, what to mock
- Security considerations — secrets handling, files the agent should never read or commit
- Commit and PR guidelines — branch naming, commit format, merge strategy
In monorepos, you can place AGENTS.md files in each package directory. The nearest file to the edited file takes precedence, so each subproject ships tailored instructions. OpenAI’s own Codex repository uses 88 AGENTS.md files across its directory tree.
The key insight from the research: lead with commands, not prose. An agent that can copy-paste a build command saves thirty tokens of exploration. Multiply that across every task in a session, and you’re looking at the 16.58% reduction the study measured.
The Security Tradeoff Nobody’s Talking About
AGENTS.md solves a context problem, but it creates a control problem. NVIDIA’s security researchers published an AGENTS.md injection scenario on April 20, 2026 demonstrating that compromised dependencies can alter AGENTS.md files to steer autonomous agent behavior. The attack path is specific: if an attacker already has code execution through a malicious dependency, they can modify your AGENTS.md to redirect agent behavior — even when the user prompt looks completely benign.
This is a supply-chain risk that didn’t exist before agentic workflows. Your package.json has always been a trust boundary, but AGENTS.md turns it into a control plane. The file that tells agents how to build your code can be weaponized to tell them to exfiltrate it.
The mitigation isn’t to avoid AGENTS.md — that’s not realistic given the token savings at stake. It’s to treat the file as a security artifact. Pin it in your review process. Audit changes to it with the same scrutiny you’d apply to CI configuration. And if you’re running agents in CI/CD, make sure the AGENTS.md they read is the one you committed, not one injected by a compromised build step.
For teams running multi-agent setups through tools like GitHub Agent HQ, this governance layer becomes even more critical — each agent session burns variable API credits with no hard cap, and a poisoned instruction file compounds that cost across every agent simultaneously.
The Tool Compatibility Question
AGENTS.md is the closest thing to a universal standard, but “universal” overstates the case. As of June 2026, the landscape looks like this:
| Tool | Reads AGENTS.md | Native Format | Notes |
|---|---|---|---|
| OpenAI Codex CLI | Yes | AGENTS.md | Originated the spec |
| GitHub Copilot | Yes (code review, as of June 18) | .github/copilot-instructions.md | Repo-level support added June 18 |
| Cursor | Yes | .cursor/rules/*.mdc | Uses YAML frontmatter for glob-scoped activation |
| Claude Code | Yes (as of June 2026) | CLAUDE.md | CLAUDE.md remains richer with 3-layer memory |
| Gemini CLI | No (uses GEMINI.md) | GEMINI.md | Sunset June 18; migration to Antigravity CLI |
| Windsurf | Yes | AGENTS.md | Full native support |
| Aider | Yes | AGENTS.md | Full native support |
The practical setup: put shared instructions in AGENTS.md for cross-tool compatibility, then use tool-specific files for capabilities that the standard doesn’t cover. If your team is Claude Code only, CLAUDE.md’s 3-layer memory model is genuinely richer. But if you’re running even two tools — which most serious engineering organizations are — AGENTS.md is the single source of truth that prevents drift.
Cloudflare’s internal case study shows what this looks like at scale: AGENTS.md in roughly 3,900 repositories, with 3,683 internal users of AI coding tools in a 30-day window. When an organization that ships infrastructure software dogfoods a pattern across nearly four thousand repos, it’s worth paying attention.
The Bottom Line
AGENTS.md isn’t a documentation nicety. It’s a cost-control mechanism that happens to also improve code quality. The 16.58% token reduction and 28.64% runtime improvement from the academic study aren’t theoretical — they’re the difference between a Claude Code Agent SDK credit pool lasting the month or running out in three weeks.
The June 2026 billing reset exposed that most teams have been operating on generosity subsidies. The free tiers, unlimited trials, and temporary boosts that masked context inefficiency are gone. Teams without an AGENTS.md file will see their agent spend increase 30-50% overnight with no productivity gain, because the end of free tiers removes the slack that was hiding context waste.
Write the file. Put it at your repo root. Lead with copy-pasteable commands, not prose. Treat it as a security artifact, not just documentation. And update it every time your agent does something wrong — because the file gets smarter over time, and so does your budget.