AGENTS.md explained: one instructions file for many AI coding tools

Every AI coding tool wants a briefing about your project: how to run it, what style to follow, what to leave alone. Each one invented its own file for this. AGENTS.md is an attempt at a shared, tool-neutral version.

What AGENTS.md is

The project's site, agents.md, calls it a simple, open format for guiding coding agents, and "a README for agents". Your README.md is for people. AGENTS.md holds the extra detail an agent needs, such as build steps and conventions, so the README stays readable.

Key facts from the site:

• It's plain Markdown. There are no required fields. Use any headings you like.
• Nested files are allowed. In a big project you can add another AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence.
• Chat comes first. The FAQ says the closest file to the edited file wins, and explicit instructions in your chat override everything.
• It has a home. The site says AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation.

A small example

# AGENTS.md

## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`

## Conventions
- Use British English in visible text.
- Keep CSS in `src/styles/`.

## Rules
- Never edit files in `src/generated/`.
- Ask before adding a new dependency.

Keep it short and specific, and never put passwords or API keys in it, since it is usually committed to Git.

Which tools read it

Tool behaviour changes quickly. Which Copilot surfaces read the file, for example, is listed on a separate GitHub page, so check each tool's docs for your version.

AGENTS.md vs CLAUDE.md vs Cursor rules

Our guides cover the other two in depth: Teach Claude Code your project with CLAUDE.md and Give Cursor standing instructions with project rules. Cursor's docs add that it supports plain AGENTS.md as a simple alternative to its rules folder.

Using AGENTS.md with Claude Code

Claude Code's memory docs say it can read AGENTS.md natively in recent versions (they mention 2.1.277 or later), but by default only when you have no CLAUDE.md in your working directory or above it. If you want both, the docs recommend a CLAUDE.md next to your AGENTS.md that imports it:

@AGENTS.md

## Claude Code
- Anything specific to Claude Code goes here.

The docs also mention a symlink (ln -s AGENTS.md CLAUDE.md) but warn that Claude's Edit and Write tools refuse to write through it and that Windows checkouts can break it, so they suggest the import there. The docs note that AGENTS.local.md and AGENTS.override.md are not read by Claude Code.

Using it with Gemini CLI

Add this to .gemini/settings.json, as shown in the agents.md FAQ:

{ "context": { "fileName": "AGENTS.md" } }

We couldn't confirm the setting in Google's own configuration docs, so test that it takes effect. See Get started with Gemini CLI.

A sensible setup

1. Put the shared basics, such as commands, conventions and off-limits folders, in AGENTS.md.
2. If you use Claude Code, add a CLAUDE.md that starts with @AGENTS.md, then adds anything Claude-specific.
3. If you use Cursor, keep Cursor-only or file-scoped guidance in .cursor/rules and let it read the shared file.
4. Update the file when you catch yourself correcting an agent twice.

Limits to remember

• It's guidance, not a lock. An instruction can be ignored. Use each tool's permission settings for hard rules.
• Keep it short. Every line costs working memory in each session.
• Avoid contradictions between files, since different tools may read different ones.
• It's committed. Treat it as public to your team, and keep secrets out.

Where to go next

• Teach Claude Code your project with CLAUDE.md
• Give Cursor standing instructions with project rules
• Get started with Devin Desktop