Claude Code reads AGENTS.md now. Here's what that does and doesn't fix.

On 18 September, Claude Code 2.1.277 shipped one line:

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)

The reaction treated this as one instruction file for every tool, finally. It is a real step and it retires a pile of symlink and @AGENTS.md include hacks. It is also narrower than it sounded, and the parts it does not touch are the parts that actually hurt.

I maintain a config-sync tool, so I had a reason to read the docs properly rather than the headline. Here is what I found.

It is a fallback, not a merge

This matters because most repos that care already have both files.

By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.

If both exist, AGENTS.md is ignored. Not appended, not merged. What counts as "above it" is broader than people expect — a CLAUDE.md in any parent directory, including outside the repository, disables it.

The one that will cost somebody an afternoon: CLAUDE.local.md also disables it. That file is personal and usually gitignored. One teammate having one means their Claude Code stops reading the AGENTS.md everyone else relies on, with nothing reported. Meanwhile ~/.claude/CLAUDE.md, your organisation's managed file, and .claude/rules/ all load alongside AGENTS.md rather than replacing it.

Five things it does not do

1. There is no user-level AGENTS.md. ~/.claude/CLAUDE.md has no cross-tool equivalent.
2. There is no managed or enterprise AGENTS.md. Under a managed-only policy every AGENTS.md is left out.
3. Nothing under .agents/ is read. Not AGENTS.local.md, not AGENTS.override.md.
4. Directories added with --add-dir do not contribute one.
5. It is invisible to tooling: not listed in /memory or /context, and InstructionsLoaded hooks do not fire for it.

It is also unavailable on Bedrock, Vertex and Foundry, in any session that skips feature-flag fetching (including DISABLE_TELEMETRY and DO_NOT_TRACK), and in the first session after an install or upgrade. If your team is on a cloud provider, you get CLAUDE.md behaviour no matter what your repository contains.

You can turn on merging, but not for your repo

The behaviour is a built-in mod with an instructionFiles option — claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md, or managed-only.

The catch is where it is honored: ~/.claude/settings.json, --settings, or managed settings. It is explicitly ignored in project and local settings. So a repository cannot ask its contributors to read both files. Every developer opts in on their own machine, or an administrator does it for everyone.

What AGENTS.md actually standardises

Less than its adoption implies. agents.md is a website and an FAQ, not a versioned specification — no version number, no date, no normative language. Its own framing:

Think of AGENTS.md as a README for agents.

No required fields, plain Markdown, nearest file wins. That is the contract. And for what it covers it works: of the 33 tools I generate config for, 17 read a root AGENTS.md, and Claude Code now makes 18.

Rules were always the easy part.

The part nobody has standardised

Agent Plugins 1.0.0, with maintainers from Amazon, Cursor, Microsoft, OpenAI and Vercel, is the most serious attempt at a portable package format. It defines exactly two component types — skills and MCP servers — and is unusually direct about why it stops there:

Other proposed component types — such as commands, hooks, agents, rules, and LSP servers — remain too client-specific for a stable portable contract and are outside the v1 format until their formats converge.

Permissions are excluded separately: v1.0.0 "does not define a trust model, permission system, or sandboxing requirements."

So the map looks like this:

Surface	Cross-tool standard
Instructions / rules	AGENTS.md, informal but widely read
Skills	Agent Skills (SKILL.md)
MCP servers	MCP, plus Agent Plugins v1 packaging
Slash commands	None — explicitly out of scope
Subagents	None — explicitly out of scope
Hooks	None — explicitly out of scope
Permissions	None — explicitly deferred
Ignore files	None

Even the solved rows have holes. Agent Skills standardises the SKILL.md format but not where skills live on disk. I had assumed .agents/skills/ was settled; it is not. That proposal is still open, which is why Claude Code reads .claude/skills/.

How fragmented is the rest, concretely

Counting native support across the 33 tools I support:

Feature	Native support
Rules	33 of 33
Skills	31 of 33
MCP servers	27 of 33
Subagents	21 of 33
Hooks	18 of 33
Permissions	11 of 33

Permissions are the clearest case. Claude Code has a real allow/deny model. Most tools have something weaker, differently shaped, or nothing. There is no portable way to write "never run terraform apply" and have every assistant on the team honour it.

What I would actually do

Independently of any tooling:

• Pick one instruction file and delete the other. Since the default is a fallback, keeping both means the AGENTS.md is dead weight that reads as though it were live.
• Go looking for stray CLAUDE.local.md files when someone reports the agent ignoring a rule everybody else sees.
• Don't assume your cloud deployment matches your laptop.
• Treat hooks, permissions, subagents and commands as per-tool, and keep them somewhere you can regenerate from, because their formats will keep moving.

The tool, briefly

I build AgentsMesh, which exists for the rows with "None" in them: one canonical directory holding rules, commands, subagents, skills, MCP servers, hooks, permissions and ignore patterns, generating each tool's native files.

If your fragmentation is only instructions, you genuinely may not need it — one AGENTS.md is enough for a lot of teams now, and that is a good outcome for everyone. If you maintain hooks or permissions across more than one assistant, none of that is standardised, and something has to keep the copies honest.