AGENTS.md: The Complete Guide for Coding Agents

AGENTS.md is a plain markdown file at the root of your repository that gives AI coding agents persistent instructions about your project — the tech stack, build commands, conventions, and boundaries they should respect on every task. Think of it as a README written for agents instead of humans: predictable location, predictable purpose, no proprietary syntax.

If you've been maintaining a CLAUDE.md for Claude Code, a .cursorrules file for Cursor, and a .windsurf/rules/ directory for Windsurf — all saying roughly the same thing — AGENTS.md is the answer to that duplication. This guide covers the format, tool compatibility, monorepo precedence rules, and a step-by-step migration path.

What Is AGENTS.md and Why It Exists

Every agentic coding tool hit the same problem independently: agents need project context that survives across sessions, so each tool invented its own instructions file. Claude Code reads CLAUDE.md. Cursor used .cursorrules, then .cursor/rules/. Windsurf has .windsurf/rules/. Gemini CLI defaults to GEMINI.md. Aider reads CONVENTIONS.md by convention. Same idea, five spellings.

That fragmentation gets worse the moment a second tool shows up in your repo. Someone updates the build command in one file and forgets the other four. Rules drift, agents disagree, and nobody is sure which file is authoritative anymore.

AGENTS.md was introduced as a shared, open convention — backed by OpenAI, Google, Cursor, Factory, and others — so one file can serve every agent. There's no schema and no required sections. It's just markdown, which means:

• Any tool can adopt it without parsing anything new
• Humans can read and review it in a pull request like any other doc
• You can start with three lines and grow it as needed

The core answer to "what is agents.md" is simple: it's the cross-tool successor to per-tool rules files. One place for the instructions every agent needs, regardless of which agent your teammates happen to run. For a deeper look at how it relates to Claude Code's native file, see our AGENTS.md vs CLAUDE.md comparison.

Which Tools Support AGENTS.md: Compatibility Table

Adoption spread quickly. As of mid-2026, here's where the major tools stand:

Two practical takeaways. First, native support is broad enough that AGENTS.md should be the file you actually maintain. Second, the holdouts are all one config line or one symlink away — which is exactly what the migration section below walks through. If you want the full landscape of every tool's rules mechanism, we cover it in how AI coding rules work across tools.

The AGENTS.md Format: What to Put In — and What to Leave Out

There is no mandated agents.md format — no required headings, no frontmatter, no validation. That's deliberate. But in practice, the files that work well share a shape. Agents act on your file, so the highest-value content is anything that changes what the agent does: commands it should run, patterns it should follow, mistakes it should avoid.

A complete AGENTS.md example

Here's an agents.md example for a typical TypeScript monorepo app:

# my-app

TypeScript monorepo: Next.js web app + shared packages, pnpm workspaces.

## Setup and commands

- Install: pnpm install
- Dev server: pnpm dev (runs on :3000)
- Type check: pnpm type-check
- Tests: pnpm test (Vitest; run before every commit)
- Lint: pnpm lint

## Code conventions

- TypeScript strict mode; never use `any`
- Named exports only for components
- API routes return { data, error } — no throwing across route boundaries
- Database columns are snake_case; TS variables are camelCase
- New UI goes in src/components/, one component per file

## Testing

- Every new API route needs an integration test in tests/api/
- Use factories in tests/factories.ts, not inline fixtures

## Do NOT

- Do not edit generated files in src/gen/
- Do not add dependencies without checking packages/shared first
- Do not commit .env files or secrets

The sections that consistently earn their place:

1. Project overview — two sentences on what this is and how it's structured. Not marketing copy; orientation.
2. Commands — exact install, dev, test, lint, and build commands. Agents run these autonomously; wrong or missing commands waste entire turns.
3. Conventions — naming, file layout, error handling, patterns. Be concrete: "API routes return " beats "handle errors consistently."
4. Testing expectations — what must be tested and how to run the suite.
5. Boundaries — a "Do NOT" list for the mistakes agents actually make in your repo.

What to leave out

The most common AGENTS.md failure mode is bloat. Everything in the file is loaded into the agent's context on every session, so every paragraph competes with your actual task for attention. Leave out:

• Anything the agent can discover itself. Directory listings, dependency inventories, and restated package.json scripts go stale and add nothing.
• Human onboarding content. Architecture decision records, team history, links to Notion — that's README material.
• Generic advice. "Write clean code" and "follow best practices" change no agent behavior. Cut them.
• Secrets or environment values. The file is committed and read by tools; treat it as public within your org.
• Task-specific instructions. "Refactor the billing module" belongs in a prompt, not a persistent file.

A good rule of thumb: if deleting a line wouldn't change what an agent does, delete it.

Nested AGENTS.md in Monorepos: Precedence Rules

Monorepos are where a single root file breaks down — your Next.js app and your Go services don't share conventions. The convention supports nested AGENTS.md files, and the precedence rule is consistent across tools that implement it:

The closest AGENTS.md to the file being edited wins.

Concretely:

repo/
  AGENTS.md              <- global defaults: repo layout, shared commands
  apps/
    web/
      AGENTS.md          <- Next.js conventions, web-only commands
    api/
      AGENTS.md          <- Go conventions, api-only commands
  packages/
    shared/              <- no file: root AGENTS.md applies

When an agent works on apps/web/src/page.tsx, it uses apps/web/AGENTS.md; where instructions conflict with the root file, the nested one takes precedence. Files without a nearby AGENTS.md fall back to the root. And explicit instructions in your prompt override any file — these are defaults, not locks.

Three rules keep nested setups sane:

1. Root file stays generic. Workspace layout, install command, commit conventions — only what's true everywhere.
2. Nested files stay local. Don't repeat root content; only add what differs for that package.
3. Don't nest deeper than you need. One level (per app or per package) covers almost every real codebase. A file per directory is a maintenance liability.

The same pattern applies to per-package test commands and shared lint configs: state them once at the level where they're true, and let precedence do the rest.

Migrating from CLAUDE.md and .cursorrules

Here's the migration as concrete steps. The goal: AGENTS.md becomes the single source of truth, and every tool either reads it natively or is pointed at it.

Step 1: Inventory what you have.

find . -maxdepth 3 \
  -name "CLAUDE.md" -o -name ".cursorrules" \
  -o -path "*/.cursor/rules/*" -o -path "*/.windsurf/rules/*" \
  | grep -v node_modules

Step 2: Consolidate into AGENTS.md. Merge the overlapping content into one root AGENTS.md using the structure above. Deduplicate ruthlessly — most teams find 80% of their per-tool files say the same thing.

Step 3: Point Claude Code at it. Claude Code reads CLAUDE.md, and CLAUDE.md supports imports, so the cleanest bridge is a one-line file:

@AGENTS.md

A symlink works too:

ln -s AGENTS.md CLAUDE.md

Keep genuinely Claude-specific content (tool permissions, subagent notes) in CLAUDE.md below the import. The complete CLAUDE.md guide covers what belongs there.

Step 4: Retire .cursorrules. Cursor reads AGENTS.md natively, so delete the deprecated .cursorrules file. Keep .cursor/rules/ only for what AGENTS.md can't express — glob-scoped or auto-attached rules.

Step 5: Configure the stragglers. Gemini CLI:

{
  "contextFileName": "AGENTS.md"
}

Aider, in .aider.conf.yml:

read: ["AGENTS.md"]

Step 6: Delete what's left and commit. One file to review, one file to update. Rules drift stops here.

If your rules need to travel beyond one repository — shared conventions across every repo your team owns — a committed file per repo reintroduces the drift problem at the org level. That's the problem localskills.sh solves: publish your conventions once as a versioned skill, and localskills install writes each tool's native format (.claude/skills/, .cursor/rules/, .windsurf/rules/) in every repo, with versioning and rollback when conventions change. See AGENTS.md for teams for how that works in practice.

Keeping AGENTS.md Maintained as the Project Evolves

An outdated AGENTS.md is worse than none — agents will confidently run a renamed test command or follow a convention you abandoned in March. The agents.md best practices that keep the file honest:

• Treat it like code. It lives in git, so review changes to it in PRs like any other file. If a PR renames pnpm test to pnpm test:unit, the same PR updates AGENTS.md.
• Update it when an agent gets something wrong. Every time you correct an agent mid-session — "no, we use named exports" — that correction belongs in the file. This is the single highest-leverage habit.
• Prune quarterly. Delete rules for patterns that no longer exist and sections nobody can explain. Shorter files get followed more reliably.
• Watch for contradictions. As multiple people add rules, conflicts creep in ("prefer small PRs" vs. "include tests, types, and docs in every change"). Agents handle contradictions badly — pick one.
• Assign an owner. Files owned by everyone are maintained by no one. Add it to CODEOWNERS.

AGENTS.md FAQ

What is AGENTS.md used for?

AGENTS.md gives AI coding agents persistent, project-specific instructions: build and test commands, code conventions, architecture notes, and boundaries. Agents read it at the start of a session so you don't have to repeat project context in every prompt.

Is AGENTS.md an official standard?

It's an open convention rather than a formal specification — plain markdown with no required structure, backed by OpenAI, Google, Cursor, Factory, and other tool vendors. The lack of schema is intentional: any tool can adopt it without new parsing logic.

Does Claude Code read AGENTS.md?

Claude Code's native file is CLAUDE.md, but you can bridge them with a one-line CLAUDE.md containing @AGENTS.md (an import) or a symlink. Either way, AGENTS.md remains your single source of truth, and Claude-specific extras stay in CLAUDE.md.

Should AGENTS.md be committed to version control?

Yes. Committing it is the entire point — every teammate and every agent gets the same instructions, changes go through code review, and git blame tells you why a rule exists. Just never put secrets or environment values in it.

How long should an AGENTS.md file be?

As short as it can be while still changing agent behavior. Most effective files land between 30 and 150 lines. If yours is pushing several hundred, split per-package guidance into nested AGENTS.md files or move reusable conventions into installable skills.

---

Maintaining the same rules across repos and tools by hand doesn't scale. Sign up for localskills.sh to publish your conventions once and install them everywhere — Claude Code, Cursor, Windsurf, and more — with one command.

npm install -g @localskills/cli
localskills login
localskills install your-org/your-conventions --target cursor claude windsurf