AGENTS.md: What It Is, How It Differs From CLAUDE.md, and How to Write One

AGENTS.md is a plain Markdown file, no required schema, no frontmatter, that sits at a repository root and gives AI coding agents the context a README is written for humans, not agents, to skip: build commands, test invocation, code style, and project-specific conventions. The agents.md site frames the split directly: keep READMEs "concise and focused on human contributors" and give agents "a clear, predictable place for instructions" instead.

It launched in August 2025, backed jointly by OpenAI, Google's Jules team, Cursor, Factory, and Amp. Community tracking of path:AGENTS.md on GitHub put adoption at roughly 20,000 projects within days of launch; by the time this guide was written, agents.md put that figure at over 60,000. In December 2025, the Linux Foundation formed the Agentic AI Foundation (AAIF) to steward it long-term, alongside Anthropic's Model Context Protocol and Block's goose, with Anthropic, AWS, Google, Microsoft, and OpenAI as platinum members.

More than 25 tools read it today, including OpenAI Codex, GitHub Copilot, Cursor, Google's Gemini CLI and Jules, JetBrains Junie, Zed, Warp, Aider, and Cognition's Devin and Windsurf. A minimal file looks like this:

For monorepos, nested AGENTS.md files inside subprojects take precedence over the root file for that subtree, the same override model most tool-specific formats already use.

Every major coding agent shipped its own file before AGENTS.md existed, and most still default to reading their own first. The practical problem shows up the moment a repository has contributors on different tools: instructions written for one agent are invisible to the others unless someone duplicates them by hand.

The last row is worth separating out on its own, since it's a common point of confusion (it's the second-most-common autocomplete pairing after AGENTS.md vs CLAUDE.md): a SKILL.md packages a specific, repeatable workflow that Claude Code loads only when it decides that workflow is relevant to the current task. AGENTS.md and CLAUDE.md are the opposite, both load in full at the start of every session, whether or not the current task needs them. Skills are for "how to do X"; AGENTS.md is for "what you need to know before doing anything here."

This is the part worth getting precise about, because the honest answer is more interesting than "it just works now."

Claude Code still reads only CLAUDE.md at session start. As of Claude Code's current documentation, it does not parse AGENTS.md natively. What changed is that Anthropic officially documented and endorsed two ways to bridge the gap, and shipped a third:

1. The `@AGENTS.md` import. Create a CLAUDE.md whose entire content is @AGENTS.md, and Claude Code loads the imported file's full contents at launch. Tool-specific instructions can go below the import line.
2. A symlink. ln -s AGENTS.md CLAUDE.md works on macOS and Linux with no Claude-specific content needed. Windows requires Administrator privileges or Developer Mode for symlinks, so the @AGENTS.md import is the documented fallback there.
3. The `/import` command, shipped in Claude Code v2.1.213, reads a supported coding agent's configuration, AGENTS.md included, and carries over not just instructions but MCP servers, commands, subagents, and skills into their Claude Code equivalents. Separately, running /init with CLAUDE_CODE_NEW_INIT=1 set also reads AGENTS.md (along with .devin/rules/, .windsurf/rules/, and .clinerules) when generating a new CLAUDE.md.

That's the whole shape of the current answer: interop by convention and tooling, not by the runtime reading a second file format. It's enough to close the original request, though. GitHub issue #6235, "Feature Request: Support AGENTS.md.", was opened on August 21, 2025, three days after AGENTS.md itself launched. It ran for 369 comments, including a community member posting the exact @AGENTS.md workaround above within the first three days as the practical fix people were already shipping. Anthropic closed it as completed on August 17, 2026, almost exactly one year later.

What the closure doesn't mean: a narrower, more literal version of the same ask, issue #34235, "support AGENTS.md as a native context file alongside CLAUDE.md" opened March 14, 2026, remains open. The distinction the two threads draw is real: #6235 asked for interoperability and got it through import tooling; #34235 asks for Claude Code's own file-discovery step to read AGENTS.md directly, with no CLAUDE.md in the loop at all, and that hasn't shipped.

The format has no required fields, so the risk isn't getting the syntax wrong, it's writing something too generic to change agent behavior. Anthropic's own advice for CLAUDE.md, which loads through the identical context mechanism, applies just as directly here: specific, concise, verifiable instructions outperform vague ones. "Use 2-space indentation" changes behavior; "format code properly" doesn't.

Start from what a new contributor would actually ask

Write down what you'd otherwise re-explain to a human joining the project this week: exact build and test commands, where a specific kind of code lives, the PR title convention, anything a code review has caught the same mistake on twice.

Keep it short and let nested files carry the rest

A single sprawling root file loses adherence the same way an oversized CLAUDE.md does. In a monorepo, put shared conventions at the root and package-specific detail in nested AGENTS.md files, they override the root for their own subtree.

Cover the sections that generalize across tools

Since 25+ tools read this file, avoid instructions specific to one agent's UI or command set. Dev environment setup, test invocation, lint/format commands, and commit or PR conventions read the same regardless of which agent opens the file.

Wire it into Claude Code explicitly

Neither AGENTS.md nor CLAUDE.md appears automatically for the other tool. Add the @AGENTS.md import (or the symlink) so Claude Code actually loads it, see the next section for the exact pattern.

Confirm it loaded before trusting it

Run /context in a Claude Code session and check the Memory files list. If CLAUDE.md isn't there, the import silently didn't happen, and the instructions you just wrote aren't reaching the model.

If a CLAUDE.md already exists and carries content other tools would also benefit from, move the tool-agnostic parts into AGENTS.md and leave CLAUDE.md as a thin wrapper: the import, plus anything genuinely Claude Code-specific underneath it. This is the exact pattern from Anthropic's own documentation:

Three steps to get there from an existing, single-tool CLAUDE.md:

1. Copy the tool-agnostic sections, dev environment, testing, PR conventions, into a new AGENTS.md at the repo root.
2. Replace CLAUDE.md's content with @AGENTS.md, followed by anything that only makes sense for Claude Code specifically (plan-mode rules, subagent configuration, hook references).
3. Run /context to confirm CLAUDE.md still appears under Memory files, then open the file with /memory to spot-check that the imported content rendered as expected.

The same repository that backs this guide does exactly this: its CLAUDE.md is the single line @AGENTS.md, and the actual build rules, the Next.js version notes, the GEO content requirements for new posts, live in AGENTS.md where Cursor, Codex, or any other AGENTS.md-reading tool can see them too.