Skip to content
AI Dev Toolkit.
Esc
  • Loading…

AI glossary · Agents and tools

What is AGENTS.md?

Also called: AGENTS.md file, README for agents, agent instructions file

Definition

AGENTS.md is a plain Markdown file in a repository that tells AI coding agents how to work on the project, such as setup and test commands, code style and rules, in an open format that many different agents read.

Explained

How does AGENTS.md work?

Its site calls it “a README for agents”: README.md is for people, and AGENTS.md holds the build steps, tests and conventions an agent needs but a human reader doesn’t. There are no required fields or schema. It is ordinary Markdown, and the agent reads whatever headings you write.

OpenAI released it in August 2025, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. Tools that read it include OpenAI Codex, Cursor, GitHub Copilot’s cloud agent, Google’s Jules, Devin, Zed, Warp and VS Code. Gemini CLI reads it once you name it in its context.fileName setting.

In a monorepo you can add one per package. The site’s rule is that the closest AGENTS.md to the edited file wins, and an explicit instruction in chat overrides it. Tools apply this differently: Codex joins the files from the repository root down to your folder, up to 32 KiB by default.

Example

A short AGENTS.md

This file follows the sections the AGENTS.md site suggests: setup, testing, conventions and security. It is 111 tokens on OpenAI’s o200k_base tokenizer. Agents load it into context, so like a CLAUDE.md it is paid for on every request; list only what the agent can’t work out from the code.

The site says an agent will try to run the test commands you list and fix failures before finishing, which is why the commands come first.

AGENTS.md
# Acme API

## Setup
- `pnpm install`, then `pnpm dev` starts the API on http://localhost:4000

## Testing
- Run `pnpm test` before every commit and fix any failures.
- Add or update tests for the code you change.

## Conventions
- TypeScript strict mode; avoid `any`.
- Database changes go in a new file in `db/migrations/`; never edit an old one.

## Security
- Never commit `.env` files or print secrets in logs.

Cost and quality

Why use AGENTS.md instead of a file per tool?

One file serves every agent on a team, instead of a separate rules file per tool. Claude Code reads it from v2.1.277 when a project has no CLAUDE.md; to use both, put an @AGENTS.md import at the top of a short CLAUDE.md, so shared rules live in one place and Claude-only rules go below.

Don’t mix up

How is AGENTS.md different from README.md and CLAUDE.md?

AGENTS.md vs README.md
A README explains the project to people: what it is, how to install it, how to contribute. AGENTS.md adds the detail agents need, such as exact commands and rules, that would clutter a README. Keep both.
AGENTS.md vs CLAUDE.md
CLAUDE.md is Claude Code’s own instructions file and can import other files with @path. AGENTS.md is the tool-neutral one. Claude Code reads AGENTS.md only when there’s no CLAUDE.md or CLAUDE.local.md in your folder or above it, unless you import it.

FAQ

Questions people ask

Which coding agents support AGENTS.md?

The AGENTS.md site lists, among others, OpenAI Codex, Cursor, GitHub Copilot’s coding agent, Google’s Jules and Gemini CLI, Devin, Windsurf, Zed, Warp, VS Code, Aider, goose, opencode, Amp and Junie. Claude Code reads it from v2.1.277 when there’s no CLAUDE.md. Some need a setting: Gemini CLI uses context.fileName and Aider a read: AGENTS.md line.

Where do you put an AGENTS.md file?

At the root of the repository, next to the README. In a monorepo, add another inside each package that needs its own rules: agents read the nearest one to the files they edit. Codex also reads a personal file from its home folder (~/.codex/AGENTS.md), which applies to all your projects.

Can I rename my existing agent rules file to AGENTS.md?

Yes. The AGENTS.md site suggests renaming the old file and leaving a symbolic link with the old name so tools that expect it still work, for example mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. On Windows, symlinks can check out as plain text files, so for Claude Code use an @AGENTS.md import in CLAUDE.md instead.

Go deeper

Try it and read more

Related

All 41 terms in the AI glossary

Keep exploring