AGENTS.md: a shared instruction format for coding agents

AGENTS.md is a file naming convention — not a library, not a runtime. Place a file called AGENTS.md at the root of your project, and a growing list of coding agents will pick it up automatically.

Why I starred it

Every agent has its own convention. Claude Code reads CLAUDE.md. OpenAI Codex reads AGENTS.md. Cursor reads .cursorrules. Copilot reads files configured in copilot-instructions.md. If you use more than one tool on the same repo, you end up maintaining multiple instruction files with nearly identical content.

AGENTS.md is a push to normalize on one filename. The pitch is simple: if enough tools converge on the same convention, you write your project instructions once and every agent that opens the repo knows what to do.

That's a coordination problem, not a technical one. And the repo's star count (~20k at time of writing) suggests the idea landed.

How it works

There's no parser, no SDK, no schema. The repo is a Next.js marketing site (pages/index.tsx) plus an AGENTS.md file that eats its own cooking — the instructions in that file guide agents working on the site itself.

The actual spec is in the README: place a Markdown file named AGENTS.md in your repo root or in subdirectories. The FAQ section (encoded in components/FAQSection.tsx) explains the few behaviors that are standardized:

• No required fields. It's plain Markdown. Use whatever headings make sense.
• Closest file wins. If you have AGENTS.md at root and another in packages/api/, an agent editing files under packages/api/ should prefer the closer one.
• Explicit chat overrides everything. Instructions in-session beat any file-level rule.

The CompatibilitySection.tsx component is the most informative file in the repo. It contains the full list of supporting tools as a TypeScript array:

const agents: AgentEntry[] = [
  { name: "Codex", url: "https://openai.com/codex/", from: "OpenAI", imageSrc: "/logos/codex.svg" },
  { name: "Cursor", url: "https://cursor.com", imageSrc: "/logos/cursor.svg" },
  { name: "Gemini CLI", url: "...", from: "Google", imageSrc: "/logos/gemini.svg" },
  { name: "GitHub Copilot", url: "https://gh.io/coding-agent-docs", imageSrc: "/logos/copilot.svg" },
  { name: "Windsurf", from: "Cognition", url: "https://windsurf.com", ... },
  // 20+ more entries
];

As of the latest commit, 24 tools are listed — Codex, Amp, Jules, Cursor, Factory, RooCode, Aider, Gemini CLI, goose, Kilo Code, opencode, Phoenix, Zed, Semgrep, Warp, GitHub Copilot, VS Code, Ona, Devin, Windsurf, UiPath, Augment Code, and Junie. The list grows via PRs: the most recent commits are almost all additions to this array. That's a reasonable signal that adoption is spreading.

The repo's own AGENTS.md is a good reference for what reasonable instructions look like — it covers which dev commands to use, how to run tests, coding conventions, and what not to run inside an agent session (no production builds during development).

Using it

Drop this in your repo root:

# AGENTS.md

## Dev environment
- Use `pnpm` for all package management
- Run `pnpm dev` to start the dev server — do NOT run `pnpm build` during a session

## Testing
- Run `pnpm test` before committing
- Fix all type errors before opening a PR

## Code conventions
- TypeScript for all new files
- Components go in `src/components/`, hooks in `src/hooks/`
- No default exports from utility files

For tools that don't natively support the AGENTS.md filename, the FAQ has a workaround for Aider (add read: AGENTS.md to .aider.conf.yml) and Gemini CLI (set context.fileName in .gemini/settings.json). Not every tool converges cleanly.

If you're already maintaining a CLAUDE.md or .cursorrules, migration is a rename plus a symlink:

mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md

Rough edges

The spec is thin by design, but that creates real ambiguity. "Closest file wins" is documented in the FAQ but not formally specified anywhere. Different agents might implement the proximity lookup differently. There's no test suite that validates agent behavior against the spec.

The repo itself has no formal spec document — just the README and the FAQ component. The instructions live scattered across a React component (FAQSection.tsx) rather than a versioned, linkable specification. If you're building a tool and want to implement support, you're reading JSX to understand the rules.

There's also a namespace collision with Claude Code's existing CLAUDE.md convention. Neither is going away. Claude Code continues to read CLAUDE.md natively; you'd need the symlink approach to bridge them. The agents.md site acknowledges this by listing Copilot, VS Code, and Claude-adjacent tools separately without claiming full native support for all of them.

The site itself is old-style Next.js Pages Router, not App Router — a minor irony given the audience.

Bottom line

If you use multiple AI coding tools on the same codebase, consolidating into one AGENTS.md is a practical win. The convention is gaining enough adoption that it's worth naming your instructions file this way today, even if your primary tool reads a different filename — the symlink cost is low and the cross-tool benefit is real.