Subscribe
AI
5 min read

AGENTS.md Won the Filename. The Dialects Survived.

Fifteen months ago, if you wanted an AI coding agent to know how your repo builds and tests, you wrote the same file three times: CLAUDE.md for Claude Code, .cursorrules for Cursor, copilot-instructions.md for Copilot. Today there is one name for that file, AGENTS.md, and it is an official open standard under the Linux Foundation. What did not happen is the part everyone assumed would follow: one agreed meaning for what the file does. Each tool reads it differently, or not at all, or only as a

AGENTS.md Won the Filename. The Dialects Survived.

Fifteen months ago, if you wanted an AI coding agent to know how your repo builds and tests, you wrote the same file three times: CLAUDE.md for Claude Code, .cursorrules for Cursor, copilot-instructions.md for Copilot. Today there is one name for that file, AGENTS.md, and it is an official open standard under the Linux Foundation.

What did not happen is the part everyone assumed would follow: one agreed meaning for what the file does. Each tool reads it differently, or not at all, or only as a fallback. The instruction-file layer is now the clearest case study in how open AI standards actually consolidate, which is to say the filename wins first and the semantics take longer.

What the standard is, and what it is not

AGENTS.md started as an OpenAI Codex convention, released in August 2025, and was donated to the Agentic AI Foundation (AAIF), the Linux Foundation initiative Anthropic, Block and OpenAI co-founded in December 2025 with backing from Google, Microsoft, AWS, Bloomberg and Cloudflare. The spec fits in a paragraph: a plain Markdown file, no required fields, no frontmatter, placed at the repo root or in subdirectories. The agent reads the nearest file in the directory tree, and explicit chat instructions override everything. The ecosystem page lists roughly two dozen readers, including Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Devin, Windsurf, Zed, Aider, opencode, goose and Junie. The format claims adoption in more than 60,000 open-source projects, and OpenAI's own monorepo carries 88 nested AGENTS.md files.

That is the whole standard. Notably, it does not define what the text means to the model, when instructions are injected, how conflicts between nested files resolve beyond "nearest wins," or how scoping works. Those decisions were left implicit, and every vendor filled the gap with its own dialect.

The one number anyone has actually measured

Whether these files do anything measurable was, until this year, an article of faith. A January 2026 paper, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, ran OpenAI's Codex agent (gpt-5.2-codex) over 124 pull requests in 10 GitHub repositories, with and without an AGENTS.md file present. The files cut median runtime by about 28.6% and output-token consumption by about 16.6%, at comparable task-completion behavior. The authors' framing matters: instructions did not make the agent more correct, they made it stop exploring. A file that says "run pnpm test from the package root" deletes ten tool calls of archaeology from every session.

Read the result in the other direction and it also says something less flattering: before the file existed, the agent was burning roughly a quarter of its runtime rediscovering what any new hire would have been handed on day one. The gain is the price of the missing convention, not a capability boost.

Four tools, four readings of the same file

Four machine readers consuming one blank instruction sheet four different ways

Semantics aside, the divergences are concrete. The Cursor rules documentation treats AGENTS.md as the simple option in a two-tier system. Real Cursor rules live in .cursor/rules/ as .mdc files with frontmatter (description, globs, alwaysApply) that decide whether a rule applies always, to matching file paths, when the agent judges it relevant, or only when @-mentioned. AGENTS.md is positioned as a plain-Markdown alternative "for straightforward use cases," and a .md file dropped into .cursor/rules is ignored outright, because it has no frontmatter to scope it. Cursor's docs also recommend keeping rules under 500 lines and splitting them. Nothing in the cross-tool spec constrains length or scoping.

GitHub's custom instructions documentation runs three parallel mechanisms: .github/copilot-instructions.md for repo-wide guidance, .github/instructions/*.instructions.md for path-scoped rules, and AGENTS.md as "agent instructions," nearest file wins. Copilot also accepts a root CLAUDE.md or GEMINI.md in place of AGENTS.md, and reads instructions from the pull request's head branch, so you can test a changed instruction file in the same PR that edits it. Personal, repository and organization instruction layers all get supplied at once, with personal taking priority.

Gemini CLI defaults to GEMINI.md and does not read AGENTS.md until you point it there with a context.fileName entry in settings.json. One setting, but it is a setting.

Claude Code went the other way. Version 2.1.277, released September 18, 2026, added AGENTS.md support as a fallback: if a folder has no CLAUDE.md, Claude Code reads AGENTS.md instead. If both exist, CLAUDE.md wins and AGENTS.md is ignored. There is no merge. Support initially excluded Bedrock, Vertex AI and Foundry deployments, extended in 2.1.281 five days later. Anthropic adopted the competitor's filename while keeping its own file authoritative, which is about as candid an expression of vendor preference as a changelog line can get.

What did not standardize

Three things the ecosystem quietly declined to unify.

Semantics. Two tools can both "support" AGENTS.md while one injects the full text every turn and the other treats directives from a richer native format as inert prose. Claude-specific syntax that works in CLAUDE.md, like import directives, is not guaranteed to mean anything when the same text is read from AGENTS.md.

Conditioning. The genuinely useful feature everyone built privately is scoped, lazily-loaded instructions: Cursor's globs and agent-selected rules, Copilot's path-specific instruction files. The open format has no equivalent, so teams wanting that behavior stay in vendor files and maintain both.

Skills. Reusable on-demand expertise is the next layer up from project instructions, and it followed the same path on a separate track: Anthropic published the Agent Skills standard in December 2025 and donated it to AAIF with 70-plus platforms integrated, per Anthropic. SKILL.md and AGENTS.md solve different problems, always-injected repo context versus load-when-relevant task knowledge, but together they define the pattern: a handful of tiny open formats, each governed neutrally, each implemented with a vendor twist.

What to write, and where

For a repo where more than one agent is ever pointed, the current best practice is boring and consistent across every tool's docs. Put the durable, machine-checkable facts, build commands, test invocations, architecture notes, in a short root AGENTS.md, with nested files for subprojects. Keep vendor files only for what the open format cannot express: Cursor path-scoped rules, Copilot path instructions. If you are Claude-first and want Claude-first behavior, keep CLAUDE.md authoritative and do not assume the fallback is reading your AGENTS.md at all. And treat the instruction file as code: the same PR that changes the build should change the build command in AGENTS.md, because a stale instruction file is now measurably worse than none, it spends runtime on wrong directions.

The consolidation is real, and it is worth what it cost, which was one markdown filename and no hard feelings about the rest. The MCP crowd learned the same lesson one file format later: standards win on filenames first, and semantics are a longer, less photogenic war.

Sources

AILLMCoding Agents