AGENTS.md is the shared convention for telling coding agents how your repository works: one plain-markdown file at the root with build commands, conventions and gotchas. Over 60,000 open-source projects already ship one, and every major agent - Cursor, Copilot, Windsurf, Zed, Aider, Gemini CLI and more - reads it natively.

What you get

  • A portable context file. Write your conventions once; they work in every tool and travel with the repo.
  • A scaffold, not a spec. No required fields - headings and short imperative lines are the whole format.
  • Monorepo support. Nested AGENTS.md files per package; agents read the nearest one, so subprojects carry their own rules.

How to use it

  1. Ask your agent to scaffold an AGENTS.md from your repo - it will draft most of it correctly.
  2. Keep five sections: what this is, commands, conventions, forbidden moves, definition of done.
  3. Every time the agent repeats a mistake, add one line under the right heading. The file is a cache of your corrections.
  4. Stay under ~100 lines. If a rule needs a paragraph, split it.

Good to know

Migrating from .cursorrules or CLAUDE.md? Merge their content into AGENTS.md and point the old files at it. The site has 60k+ real examples to steal structure from - reading three good ones is the fastest way to learn the format.