AGENTS.md: One File for Every AI Coding Agent

What is AGENTS.md?

AGENTS.mdis a standardized Markdown file that acts as a README written for AI agents instead of humans. It’s the predictable place to put the things that would clutter a human-facing README: how to set up the project, the exact build and test commands, code conventions, and the norms an agent should follow. Per the spec, it’s “just standard Markdown — use any headings you like; the agent simply parses the text you provide.”

That simplicity is the point. There’s no schema to learn, no frontmatter to get wrong, and nothing tool-specific. You write what you want the agent to know, and every agent that supports the standard reads it.

Who’s behind it

AGENTS.mddidn’t come from one vendor trying to own a format. It emerged from collaboration across OpenAI Codex, Amp (Sourcegraph), Google Jules, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. By 2026 the official site reports usage in more than 60,000 open-source repositories and native support across two dozen-plus tools. That neutral governance is exactly why it has a shot at being the standard rather than one more format.

The format

There’s no required structure — these headings are just a common convention:

# AGENTS.md

## Setup
- Install deps: `pnpm install`
- Copy `.env.example` to `.env.local`

## Build & test
- Build: `pnpm build`
- Test: `pnpm test` (must pass before any commit)
- Lint: `pnpm lint`

## Conventions
- TypeScript strict mode; prefer named exports
- Components are typed function components, no default exports
- Files under 800 lines, functions under 50

## Don't
- Don't add a dependency without flagging it
- Don't touch the generated `/dist` directory

Nested files for monorepos

In a monorepo you can place an AGENTS.md in any subdirectory. The resolution rule is simple: the closest AGENTS.md to the file being edited wins, and an explicit instruction in chat overrides everything. OpenAI Codex, the reference implementation, merges files from the Git root down to the working directory, with closer files taking precedence.

Which tools support AGENTS.md

AGENTS.md vs CLAUDE.md vs .cursorrules

AGENTS.md is the portable lowest common denominator. The tool-native formats trade portability for power:

For the full five-way breakdown including SKILL.md and Copilot instructions, see SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md.

How to write a good AGENTS.md

• Lead with commands. The single highest-value content is the exact setup, build, and test commands — an agent that can run your tests can verify its own work.
• State conventions as rules, not essays. “Prefer named exports” beats three sentences about module philosophy.
• Include a “Don’t” section.Negative constraints (don’t touch generated files, don’t add deps silently) prevent the most expensive mistakes.
• Keep it current. A stale AGENTS.md actively misleads every agent that reads it.

Why a cross-tool standard is a big deal

Before AGENTS.md, encoding your project’s norms meant maintaining the same content in .cursorrules, CLAUDE.md, and copilot-instructions.md— and watching them drift. A shared standard collapses most of that into one file. That’s also exactly the thesis behind Skillwright: keep your rules and skills in one canonical library, treat AGENTS.mdas a first-class output, and compile to the tool-specific formats (including Claude Code’s CLAUDE.md and Cursor’s .mdc) so nothing drifts.

If you’re adopting AGENTS.md across a stack of tools, read how to manage AI coding rules across tools next.

Frequently asked questions