AGENTS.md: what it is, which agents read it, and a template

What is AGENTS.md?

AGENTS.md is a Markdown file at the root of your repo that tells AI coding agents how to work on your project. The agents.md site calls it "a README for agents": the place for build steps, test commands and conventions that would clutter a human README.

It is an open format, not tied to one company, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. There is no schema and no required fields. As the site puts it, "AGENTS.md is just standard Markdown."

Which agents read AGENTS.md?

Many coding agents read AGENTS.md, including Codex, Cursor and Claude Code. The agents.md site lists the tools that support the format. Among them:

• OpenAI Codex
• Cursor
• GitHub Copilot's coding agent
• Gemini CLI and Jules from Google
• VS Code, Zed and Warp
• Windsurf and Devin from Cognition
• Junie from JetBrains
• Aider, goose, opencode, Amp, Factory, RooCode, Kilo Code and Augment Code

Claude Code reads it too. Its memory docs say Claude Code "can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md." By default it does this only when there is no CLAUDE.md in your working directory or above it. More on that below.

A couple of tools need a setting. The agents.md FAQ says Aider needs read: AGENTS.md in .aider.conf.yml, and Gemini CLI needs "fileName": "AGENTS.md" under context in .gemini/settings.json.

Where does AGENTS.md go?

Put one AGENTS.md at the root of your repo. In a monorepo, add more inside each package or service:

repo/
  AGENTS.md              shared rules for the whole repo
  packages/
    web/
      AGENTS.md          rules for the web app
    api/
      AGENTS.md          rules for the API

The general rule from agents.md: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." Each tool implements this a little differently:

• Codex walks from the project root down to your current directory and checks each folder for AGENTS.override.md, then AGENTS.md. It uses at most one file per folder, joins them root first, so files closer to you come later and take priority. It stops adding files at a size limit set by project_doc_max_bytes, 32 KiB by default. You can also keep personal defaults in ~/.codex/AGENTS.md. Details are in the Codex AGENTS.md guide.
• Cursor reads AGENTS.md at the project root and in subfolders. Instructions from nested files are combined with their parents, "with more specific instructions taking precedence."
• Claude Code reads every AGENTS.md from your working directory up at session start, and a subfolder's AGENTS.md when it opens a file in that folder.

Codex also lets you add other filenames to look for:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

What to put in it

The agents.md site suggests a project overview, build and test commands, code style, testing instructions and security notes, and adds that "anything you'd tell a new teammate belongs here too." In practice, the best files are short and specific:

• Commands the agent can run. Exact install, dev, test and lint commands. An agent that knows how to run your tests will check its own work.
• Rules it can't guess. "Use pnpm, not npm." "Never edit files in src/generated." "Dates are stored in UTC."
• Where things are. One line per important folder.
• How to finish. What must pass before a change is done, and how commits or pull requests should look.

Leave out what the agent already knows or can read from the code, like general language style or a list of every file.

A copy-ready template

Fill in the parts in angle brackets and delete what doesn't apply.

# AGENTS.md

## Project
<One or two sentences: what this repo is and who uses it.>

## Setup
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Environment: copy `.env.example` to `.env.local`. Never commit secrets.

## Checks (run before you say a task is done)
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Tests: `pnpm test`

## Layout
- `src/app/`: routes and pages
- `src/lib/`: shared helpers, no UI code
- `src/generated/`: generated code, do not edit by hand

## Code style
- TypeScript strict mode. No `any` without a comment explaining why.
- Prefer small functions and early returns.
- <Any house rule a new teammate would get wrong.>

## Commits and pull requests
- One logical change per commit, message in the imperative mood.
- PR title format: [<area>] <short summary>
- List what you tested in the PR description.

## Don'ts
- Do not add new dependencies without asking.
- Do not change public API signatures without updating the docs.

Codex has a shortcut for a first draft: run /init in the Codex CLI and it scaffolds an AGENTS.md in the current folder. OpenAI's best practices page recommends editing the result to match how your team actually builds, tests and ships.

AGENTS.md vs CLAUDE.md vs skills

These three solve different problems, and they work well together.

AGENTS.md or CLAUDE.md? Claude Code's default is to read CLAUDE.md if you have one and AGENTS.md if you don't. If your team uses several agents, the simplest setup is one shared AGENTS.md. When you need Claude-specific notes, create a CLAUDE.md next to it that imports the shared file:

@AGENTS.md

## Claude Code
- Use plan mode for changes that touch more than three files.

Claude Code reads the imported file first, then the rest. You can also change this behavior with the Project instructions setting in /config, for example to always read both. See the CLAUDE.md guide for more.

When to use a skill instead. Instructions files load every session, so they should stay short. Anything that is a procedure for one kind of task, like writing release notes, reviewing a pull request or adding a migration, is better as a skill. Skills load only when needed, and the same folder works across Codex, Claude Code and Cursor. In Codex, repo skills go in .agents/skills/; in Claude Code, .claude/skills/.

Moving to AGENTS.md from another file

If your repo already has a tool-specific instructions file, you don't have to keep two copies:

1. Move the shared content into AGENTS.md at the repo root.
2. For Claude Code, delete a CLAUDE.md that held only that content, or replace its body with @AGENTS.md.
3. For Cursor, move plain project facts out of .cursor/rules/ and keep only rules that need file patterns there. See Cursor rules.
4. For an old filename some tool still expects, agents.md suggests a symlink, for example ln -s AGENTS.md AGENT.md.

Keep the procedures as skills you own

Once your AGENTS.md is lean, the task-by-task instructions need a home. Kipt keeps prompts and skills in your own private GitHub repo: paste a prompt to save it, use Promote to skill to turn it into a SKILL.md, and install your whole library into Codex or Claude Code with npx skills add https://github.com/<you>/<repo>.git. For a single prompt, the free SKILL.md generator does the conversion in your browser.