AGENTS.md vs CLAUDE.md vs skills: what goes where

AGENTS.md is a plain markdown file at the root of your repository that tells coding agents how to work in your project: how to build it, how to run the tests, what conventions to follow, what to leave alone. No schema, no required sections, no registry. The whole standard fits in one sentence: put a file called AGENTS.md in your repo, and agents that support the convention will read it before they touch your code.

People call it the “README for agents,” and the analogy holds up. A README explains your project to humans who just arrived. AGENTS.md explains it to software that just arrived. The difference is that the agent will actually follow the instructions, so vague ones cost real money in wasted tokens and wrong edits.

We test agent tooling for a living at SkillProof, and we’ve watched this file go from an OpenAI side project to the closest thing agentic coding has to a shared standard. This post covers how it relates to CLAUDE.md and the other tool dialects, and where skills fit, because they solve a different problem than most people assume.

What AGENTS.md is, and who actually reads it

The convention came out of OpenAI’s Codex team in mid-2025 and was quickly co-signed by Google’s Jules, Cursor, Factory, Amp and others. The pitch was simple: every agent vendor had invented its own instruction file, and repository roots were filling up with near-identical markdown addressed to different robots. AGENTS.md proposed one filename that everyone reads.

Adoption since then has been real but uneven. Here’s the honest map as we see it in mid-2026:

Tool	Reads AGENTS.md	Native dialect
OpenAI Codex	Yes, native	None, AGENTS.md is the format
GitHub Copilot (coding agent, VS Code)	Yes	.github/copilot-instructions.md
Cursor	Yes	.cursor/rules/*.mdc
Google Jules	Yes, native	None
Gemini CLI	Yes, via config	GEMINI.md
Claude Code	Not natively	CLAUDE.md
Zed	Yes	None
Amp	Yes	None
Aider	No	CONVENTIONS.md
Windsurf	No	.windsurf/rules/

Two things stand out in that table. First, the column of “yes” answers is long and keeps getting longer; when a new agent ships in 2026, AGENTS.md support is usually in the launch notes. Second, the dialects have not gone away. Copilot still reads its own instructions file, Cursor still has rules with globs and trigger modes that AGENTS.md can’t express, and Claude Code, the tool we spend the most time with, still wants a CLAUDE.md.

So the practical situation is this: AGENTS.md is the lingua franca, the dialects are where tool-specific power lives, and any team running more than one agent needs a policy for keeping them in sync. That policy is most of this article.

What goes in the file is less contested than the filename was. The AGENTS.md files that work cover setup and build commands, how to run tests, code style notes the linter can’t catch, and architectural boundaries (“payments logic lives in packages/billing, don’t put it anywhere else”). The files that don’t work read like mission statements. An agent doesn’t need to know that you value clean code. It needs the command that checks whether the code is clean.

AGENTS.md vs CLAUDE.md

These two files do nearly the same job for different readers. Both are project-level instruction files. Both load into context at the start of a session. Both should be short, because every line costs tokens on every request. If you’ve already written a good CLAUDE.md, you already know how to write a good AGENTS.md, and our advice in CLAUDE.md best practices transfers almost line for line.

The differences are worth knowing before you unify them:

Audience. CLAUDE.md is read by exactly one tool. That means it can safely reference Claude-specific machinery: skills, hooks, subagents, MCP servers, permission settings. An AGENTS.md that says “use the systematic-debugging skill before proposing a fix” is noise to Codex and Copilot, which have no idea what a skill is.

Hierarchy and imports. Claude Code merges CLAUDE.md files from several levels (user-global, project root, subdirectories) and supports @path/to/file imports inside them. AGENTS.md supports nesting too, with the nearest file taking precedence, but the import syntax is Claude’s own.

Enforcement. Neither file is enforced. Both are suggestions to a language model. Anything that must happen every time belongs in a hook or CI, not in either file. This disappoints people equally across all tools.

If your team uses Claude Code alongside anything else, you need both files, and the failure mode is obvious: two files saying almost the same thing, drifting apart until an agent follows the stale one. Two patterns prevent that, and we’ve tested both.

The symlink. Make AGENTS.md the real file and let CLAUDE.md point at it:

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code follows the symlink and reads the content as if it were its own file. This is the zero-maintenance option, and it’s the right one when you have nothing Claude-specific to say. Its limit is exact identity: both readers get every word, including the ones only relevant to the other.

The thin wrapper. Keep AGENTS.md as the shared source, and make CLAUDE.md a small file that imports it and adds Claude-only lines:

# CLAUDE.md
@AGENTS.md

## Claude-specific
- Use the git-workflow skill for commits and PRs.
- Never edit files under infra/ without asking.

This is what we run in our own repos. The shared facts live once, the Claude extras live where only Claude will see them, and a diff to AGENTS.md updates every tool at the same moment. The same shape works in reverse for other dialects: keep .github/copilot-instructions.md and Cursor rule files down to a few lines that defer to AGENTS.md for anything both tools need. We compared those dialects in detail in Claude skills vs Cursor rules and Claude skills vs Copilot instructions.

One warning from our testing: whichever pattern you pick, pick one. Repos that carry a full CLAUDE.md and a full AGENTS.md with independently edited content are the drift scenario with extra steps.

AGENTS.md vs skills: different layers entirely

This is the comparison people actually search for, and it’s the one built on a category error. AGENTS.md and skills are not competing formats. They sit on different layers of the stack and answer different questions.

AGENTS.md answers: what should any agent know about this project? It’s facts about a place. It travels with the repository, applies to whichever agent shows up, and says nothing about how the agent does its job beyond local rules.

A skill answers: how should this agent perform this kind of task? It’s a behavior, packaged in a folder with a SKILL.md, loaded on demand when the task matches its description. It travels with you, not with the repo. Install a debugging skill once and it works in every project you open, whether or not that project has ever heard of you. We covered the mechanics in What are Claude skills?, but the load model is the key difference: AGENTS.md content sits in context for the whole session, while a skill costs about a hundred tokens of metadata until the moment a task triggers it.

Here’s the full stack as we draw it on whiteboards:

Layer	Lives in	Scoped to	Loaded	Question it answers
AGENTS.md	Repo root	The project, any agent	Every session	What is this place?
Tool dialect (CLAUDE.md, rules)	Repo or user config	The project, one tool	Every session	What should this tool do here?
Skills	~/.claude/skills/ or .claude/skills/	One agent, any project	On demand	How is this kind of task done?
MCP servers	Tool config	One machine or team	Tool definitions always in context	What can the agent reach?

Read it top to bottom as widening capability and narrowing portability. The standard file is universal and dumb. The dialect is tool-bound and slightly smarter. Skills are behavior-rich but currently agent-bound. MCP is live infrastructure with credentials and processes.

A concrete example makes the boundary obvious. “Run pnpm test --filter=changed before committing” is an AGENTS.md line: it’s a fact about your repo, true for every agent. “When debugging, reproduce the failure before proposing a fix, and never claim a fix works without rerunning the failing test” is a skill, and in fact it’s one we’ve tested and listed: systematic-debugging. It has nothing to do with any particular repo. Putting it in AGENTS.md means copying it into every project and paying its token cost in every session, including sessions where nobody is debugging anything.

The rule of thumb we give teams: if you’d copy a line into a second repo unchanged, it’s not project context, it’s behavior, and it belongs in a skill. If a line only makes sense in this repo, it’s context, and it belongs in AGENTS.md.

The strategy for teams running multiple AI tools

Most teams we talk to in 2026 are not single-agent shops. A typical mix is Claude Code for heavier work, Copilot in the editor, and Cursor on a few holdouts’ machines. Here’s the configuration that survives contact with that:

1. Write AGENTS.md as the source of truth. One file, at the repo root, owned like code. Put every fact that any agent needs into it: commands, conventions, boundaries, warnings. Review changes to it in PRs, because a wrong instruction here misleads every agent your team runs.

2. Keep the dialects thin. CLAUDE.md imports AGENTS.md and adds only Claude-specific lines. Copilot instructions and Cursor rules get the same treatment: a pointer plus whatever genuinely can’t be expressed in the shared file. Our test for “thin enough” is blunt: if a dialect file exceeds a screen, something in it probably belongs in AGENTS.md or in a skill.

3. Put reusable behavior in skills. Debugging discipline, commit and PR habits, test-writing standards, document formatting. These don’t belong in any per-repo file because they aren’t per-repo. Install them once per agent and they follow you everywhere. Our tested picks for coding work are collected in the best coding skills, and git-workflow is the one we’d install first on any team that cares about commit hygiene.

4. Enforce with hooks and CI, not prose. Anything that must happen 100% of the time cannot live in a markdown file read by a probabilistic system. Formatting on save is a hook. Tests before merge are CI. The markdown layers are for judgment, not enforcement.

This layout has a property worth naming: each layer changes at its own pace. AGENTS.md changes when the project changes, skills change when your team’s craft changes, and no agent reads anything addressed to a different agent.

Will one standard win?

Our take, wearing the standards-watcher hat: the file convention will converge, and the behavior layer won’t.

The file layer converges because the incentives all point one way. A context file is low surface area, vendors gain compatibility for the cost of one filename check, and repo owners are visibly tired of instruction-file sprawl. We expect native AGENTS.md support in Claude Code eventually, because the pressure is public and the cost of supporting it is a file lookup. When that happens, the symlink pattern above becomes a no-op you can delete.

The behavior layer is a different story. Skills-like mechanisms are appearing everywhere: Claude’s skills, Cursor’s rule modes, Copilot’s prompt files, assorted “playbook” features across smaller agents. They rhyme, but each encodes its vendor’s own ideas about triggering and scoping. A skill’s trigger description and progressive loading map onto a Cursor rule glob about as well as a symphony maps onto a ringtone. Behavior formats are where vendors differentiate, so they have every reason to keep diverging.

And here’s the part vendors don’t put in launch posts: portability of format is not portability of quality. An untested behavior file fails the same way on every tool that loads it. It triggers when it shouldn’t, or it never triggers at all. Roughly half of the community skills we pull from GitHub fail our first test pass, and the failure causes are format-independent: vague trigger descriptions, and instructions the author never verified against a real tool. We wrote up the pattern in why half of Claude skills don’t work, and everything in it applies to whatever your other agent calls its version of skills. A converged standard would give us one filename and the same old defect rate.

So: standardize your facts, because the ecosystem is standardizing with you. Then be picky about your behaviors, because nobody is standardizing quality.

FAQ

Does Claude Code read AGENTS.md?

Not natively as of mid-2026. Claude Code looks for CLAUDE.md. The standard workarounds are a symlink (ln -s AGENTS.md CLAUDE.md) or a thin CLAUDE.md that imports the shared file with @AGENTS.md. Both work; the import version also gives you a place for Claude-only instructions.

Should AGENTS.md replace my CLAUDE.md?

Replace its content, keep the file. Move everything tool-agnostic into AGENTS.md, then shrink CLAUDE.md to an import plus Claude-specific lines about skills, hooks and permissions. Deleting CLAUDE.md outright only makes sense with the symlink approach, where the two are literally the same bytes.

Can I put skill-like instructions in AGENTS.md instead of installing skills?

You can, and for a single small repo it’s fine. The costs show up at scale: the instructions load in every session whether relevant or not, and they don’t follow you to other projects. Other agents reading the file also get behavior guidance written for Claude. Behavior you’d reuse across repos belongs in a skill.

How long should an AGENTS.md be?

Short enough that every line earns its context cost. Most good ones we’ve reviewed are 30 to 80 lines. If yours is several hundred, it’s probably carrying behavior content that belongs in skills, or reference material that should be a linked doc the agent reads on demand.

Do subdirectory AGENTS.md files work?

Yes, the convention supports nesting: the file closest to the code being edited wins for that area. Monorepos use this to give packages their own build and test commands. Keep the root file for repo-wide facts and push package specifics down. Claude Code applies the same nearest-file logic to CLAUDE.md, so the wrapper pattern nests cleanly too.