CLAUDE.md vs AGENTS.md and which agent reads each

Claude Code reads CLAUDE.md. Nearly every other coding agent reads AGENTS.md, a plain Markdown file of instructions at the root of a repository. Claude Code reads AGENTS.md too, but only when there’s no CLAUDE.md in the folder it starts in or any folder above it.

So if you use more than one agent, keep your rules in one AGENTS.md. If you also need a CLAUDE.md, make its first line @AGENTS.md so it pulls the shared file in. The reasons for that advice follow, agent by agent.

Agents often change how they load these files. Copilot code review started reading CLAUDE.md and GEMINI.md in July 2026, according to GitHub’s changelog. In June, Antigravity CLI replaced Gemini CLI for unpaid and Google One users, as a notice on Google’s Gemini CLI docs says. Every agent’s behaviour below was checked against its own documentation on 11 October 2026, so treat that date as part of the answer.

Which file each agent reads

An instruction file is a Markdown file that an agent adds to its context without being asked. Context here means the text the agent sends the model along with your request. The table covers the eleven agent options Prickles builds rule packs for. The last of them covers ten agents that all read AGENTS.md, so they share a row.

Some agents can load a rule only when they work on a file that matches a pattern, a glob such as **/*.spec.ts. The pattern sits in the rule’s frontmatter, the block of settings between --- lines at the top of the file. Sizes are in whatever unit each vendor uses, whether lines, bytes, characters or tokens (the chunks of text a model reads and is billed by).

Agent names link to their docs, all read on 11 October 2026.

Ten agents that share a row

These agents treat AGENTS.md as their main file, with differences that matter when a repository holds other agents’ files too. Each name links to that agent’s own docs page, as it stood on 11 October 2026.

• Amp always includes AGENTS.md from the folder you start in and every folder above it. It falls back to AGENT.md or CLAUDE.md only in a folder that has no AGENTS.md.
• Zed reads only the first file it finds from a list. .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md and AGENT.md all come before AGENTS.md, so any of them hides it.
• Warp uses AGENTS.md unless a WARP.md sits in the same folder.
• goose looks for AGENTS.md and then .goosehints.
• opencode walks up from the current folder and uses CLAUDE.md only where there’s no AGENTS.md.
• Kilo Code always loads the root AGENTS.md, which can’t be switched off on its own, and falls back to AGENT.md.
• Factory searches from the current folder up to the Git root and reads CLAUDE.md for compatibility.
• Augment lists CLAUDE.md ahead of AGENTS.md in its CLI’s order of precedence.
• Kiro always includes AGENTS.md, from the workspace root and from subfolders. Its own steering files can load by file pattern with inclusion: fileMatch.
• Jules looks for AGENTS.md in the root of the repository.

Amp has a file-pattern loader of its own. If AGENTS.md mentions a file with @ and the file has globs: in its frontmatter, it loads only once Amp has read a matching file. A mentioned file without globs: always loads.

How Claude Code picks CLAUDE.md or AGENTS.md

Anthropic’s How Claude remembers your project (2026) sets out the rule. From version 2.1.277, Claude Code reads AGENTS.md only when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder it starts in or any folder above it. Your personal ~/.claude/CLAUDE.md, an organisation’s managed CLAUDE.md and .claude/rules files don’t count. They keep loading beside AGENTS.md.

CLAUDE.local.md counts as well. It holds your own notes and stays out of version control, so adding one stops Claude Code reading AGENTS.md in your sessions alone.

A team can commit an import instead. A CLAUDE.md can pull in another file with @ and a path, and Claude Code expands it when the session starts:

@AGENTS.md

## Claude Code only

- Use plan mode before changing anything in `db/migrations/`.

Claude reads the imported AGENTS.md first, then the Claude Code-only lines below it. Anthropic’s docs say the import never causes a second read of AGENTS.md, whatever the setting. Imported files load in full at launch, so an import organises a file without making it any cheaper. This site’s own repository works this way. Its CLAUDE.md holds the single line @AGENTS.md.

Two alternatives work less well. A CLAUDE.md that asks Claude in words to read AGENTS.md depends on Claude deciding to open the file. The other is a symlink.

Is there a CLAUDE.md equivalent for Codex?

Yes, AGENTS.md is Codex’s own file. OpenAI’s Custom instructions with AGENTS.md (2026) describes the order it reads its files in. First comes a global file in ~/.codex. Then Codex walks from the project root, usually the Git root, down to the folder you started in, and takes at most one file from each folder. In each folder, AGENTS.override.md wins over AGENTS.md.

Codex stops adding files once their combined size reaches project_doc_max_bytes, 32 KiB unless you raise it. It starts from the root, so a long root file leaves less room for the files nearer your work.

If your rules already live in CLAUDE.md, Codex can read that instead. Its config takes a list of fallback names to check in any folder that has no AGENTS.md:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]

That works for a team that uses only Claude Code and Codex. For a wider mix, AGENTS.md makes the better source, because most of the table reads it without any setup.

Cursor rules vs AGENTS.md

Cursor keeps its own rules as project rules, .mdc files in .cursor/rules. Cursor’s Rules docs (2026) say it ignores a plain .md file in that folder. Frontmatter decides when a rule applies:

• alwaysApply: true puts the rule in every chat.
• globs: attaches it when a matching file is in context.
• A description on its own lets the agent decide whether to pull it in.
• With none of these, the rule loads only when you @-mention it.

Cursor also reads AGENTS.md at the root and in subfolders, where nested files combine with their parents and the more specific one wins. Cursor’s help page on rules (2026) adds that it reads CLAUDE.md the same way and always applies it, whatever its frontmatter says. A repository with both files therefore gives Cursor both.

Use .mdc rules for what AGENTS.md can’t do, such as a rule that attaches only to matching files or one the agent pulls in by its description. Anything that applies to every task can sit in AGENTS.md. Either way, Cursor’s rules reach only its agent chat, and Tab completion, Inline Edit and Bugbot reviews don’t see them.

Copilot instructions vs AGENTS.md

GitHub Copilot’s own file is .github/copilot-instructions.md, for rules that cover the whole repository. Path-specific files live in .github/instructions, end in .instructions.md and apply when their applyTo glob matches. GitHub’s Adding repository custom instructions for GitHub Copilot (2026) says that when both kinds match, Copilot uses both. Copilot also reads AGENTS.md files anywhere in the repository, with the nearest one taking precedence, or a single CLAUDE.md or GEMINI.md at the root.

Which Copilot surface reads which file varies, and GitHub’s support table (2026) sets it out. The cloud agent, the Copilot CLI and code review on GitHub.com read AGENTS.md, CLAUDE.md and GEMINI.md. Chat in VS Code reads AGENTS.md but not the other two. Chat on GitHub.com and in Visual Studio, JetBrains IDEs, Eclipse and Xcode reads none of them, and neither does code review in any IDE. If anyone on your team uses Copilot there, AGENTS.md alone won’t reach them.

Copilot’s reviewer on GitHub.com reads more files than any other surface. Using GitHub Copilot code review on GitHub (2026) lists copilot-instructions.md, AGENTS.md, the path-specific files, CLAUDE.md, GEMINI.md and REVIEW.md. Since 17 July 2026, GitHub’s changelog says, code review reads them from the pull request’s own branch.

AGENTS.md vs SKILL.md

A skill is a folder holding a SKILL.md file. The Agent Skills specification (2026) requires two frontmatter fields in it, a name and a description. An agent loads every skill’s name and description when it starts, about 100 tokens each by the specification’s estimate. It loads the rest of the file only when it decides the skill is relevant, or when you call it.

An instruction file loads in full every time. Anthropic’s memory docs draw the line for Claude Code. Facts Claude should hold in every session go in CLAUDE.md. A multi-step procedure, or anything that matters for only one part of the codebase, goes in a skill or a path-scoped rule. The same line works for AGENTS.md.

Skills live in different folders for different agents:

• Claude Code reads .claude/skills, and Anthropic’s Extend Claude with skills (2026) doesn’t mention .agents/skills.
• Codex reads .agents/skills, according to OpenAI’s Build skills (2026).
• Copilot reads .github/skills, .claude/skills and .agents/skills, according to GitHub’s About agent skills (2026).
• Cursor reads .agents/skills and .cursor/skills, plus .claude/skills and .codex/skills for compatibility, according to its Agent Skills page (2026).

A skill only helps if the agent chooses to load it. Jude Gao’s AGENTS.md outperforms skills in our agent evals (Vercel, 2026) tested agents on Next.js 16 APIs that aren’t in models’ training data.

Left to its default behaviour, the skill was never invoked in 56% of cases and scored 53%, the same as giving the agent no docs. Told explicitly to use the skill, the agent reached 79%. A compressed docs index in AGENTS.md reached 100%. The post doesn’t name the agent or the model, or say how many cases it ran.

On that evidence, keep anything that must shape every change in the always-loaded file, and save skills for occasional procedures such as a release checklist.

How copies of the same rules drift apart

Copies drift when one of them changes and the others don’t. Here is one rule after the convention for test files moves from .test.ts to .spec.ts and only AGENTS.md is updated. AGENTS.md says:

- Name test files `*.spec.ts` and keep each one next to the file it tests.

But .github/copilot-instructions.md still says:

- Name test files `*.test.ts` and keep each one next to the file it tests.

Nothing fails when this happens. Copilot Chat in Visual Studio reads only the second file, so it follows the old rule. Code review on GitHub.com reads both, and so does the Copilot CLI, whose docs say it defines no general order of precedence between them.

Applicable instruction sources are additive.

Microsoft’s guide also advises against relying on any order to settle a conflict, and tells you to remove the duplicate at its source. Anthropic’s memory docs warn that when two instructions contradict each other, Claude may follow either.

A stale copy keeps working without any error, so the only sign is code that follows the old rule. F3 Don’t Repeat Yourself gives every fact one home. AI2 Persistent Brief keeps an agent’s context in instruction files, so they deserve the same care as code, with one copy of each rule changed in one place.

Token cost of two instruction files

Instruction files are paid for in tokens. Anthropic’s Manage costs effectively (2026) says token costs scale with context size and that CLAUDE.md is loaded at the start of a session. Each agent’s docs say how often the files go with a request:

• Claude Code sends the full conversation with every request, according to the same page.
• Gemini CLI sends its GEMINI.md files with every prompt, as Google’s Gemini CLI docs say.
• Antigravity and Devin Desktop put always-on rules into the system prompt on every turn.

So when an agent loads two overlapping files, the model gets both with every request. Prompt caching makes the repeats cheaper, and Anthropic’s costs page says Claude Code re-reads cached history at the lower cached rate. The second copy is still in every request.

Claude Code avoids the problem for its own pair, because by default it reads CLAUDE.md or AGENTS.md and the import doesn’t read AGENTS.md twice. Other agents read several files side by side. Cursor reads AGENTS.md and CLAUDE.md alongside its own rules, Copilot code review reads every file listed above and the Copilot CLI removes only identical copies.

To keep the always-loaded text small, split the rules across files and keep only what applies to every task in the always-loaded file. Move a rule that matters for one kind of file into a rule scoped by file pattern. A scoped rule loads only when the agent works on a matching file. The setting that scopes a rule is:

• paths: in Claude Code and Cline
• globs: in Cursor
• applyTo: in Copilot
• trigger: glob in Antigravity and Devin

AI3 Working Context asks for that text to stay short.

Prickles builds each agent’s pack from one canon, the single text every pack is generated from, so each rule still has one home. The implementation page shows what each agent gets.

How to keep CLAUDE.md, AGENTS.md and the rest in step

1. Write the rules once, in AGENTS.md at the root of the repository.
2. For Claude Code, nothing more is needed if the repository has no CLAUDE.md. If it has one, make @AGENTS.md its first line, as above.
3. For Gemini CLI, list AGENTS.md in context.fileName in .gemini/settings.json, as Google’s Gemini CLI docs and agents.md both show. Antigravity reads AGENTS.md without it.
4. For Aider, add AGENTS.md under read: in .aider.conf.yml, as Aider’s conventions page (2026) shows for any conventions file.
5. For Copilot surfaces that don’t read AGENTS.md, copy it to .github/copilot-instructions.md with a script, and fail a check in CI when the two differ.
6. Don’t create a .junie/AGENTS.md, because Junie reads it instead of the root AGENTS.md and .junie/rules.

The Gemini CLI setting lists both files, so GEMINI.md still loads:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

The Aider config is one line:

read: AGENTS.md

The Copilot copy comes from AGENTS.md, and cmp exits with an error when the two files differ:

# Generate the copy from AGENTS.md
mkdir -p .github
cp AGENTS.md .github/copilot-instructions.md

# In CI, fail when the copy has drifted
cmp AGENTS.md .github/copilot-instructions.md

That copy has a cost. Surfaces that read both files may get the rules twice, so make it only if someone uses Copilot where AGENTS.md doesn’t reach. In Zed, .github/copilot-instructions.md comes before AGENTS.md in the list, so Zed reads the copy. That does no harm while the two match.

For an agent that isn’t in the table, check whether its docs say it reads AGENTS.md and what it does with a second instruction file.