What Is AGENTS.md? The Universal AI Coding Rules File
AGENTS.md is a repo-level instruction file for AI coding agents. Think of it as the universal cousin of Cursor rules and Claude Code configs: one place to tell any agent how to work in your project.
Why AGENTS.md exists
Teams bounce between tools. Cursor today, Claude Code tomorrow, Copilot on a PR. Tool-specific rule folders help — but a shared AGENTS.md gives agents a common baseline when they enter the repo.
It answers:
- How should you explore this codebase?
- What must you never break?
- How do we run tests?
- What is out of scope by default?
A shared rules file across coding agents
AGENTS.md vs README.md
| File | Audience | Job |
|---|---|---|
README.md | Humans | What the project is, how to install |
AGENTS.md | Agents | How to change the project safely |
Do not paste the README into AGENTS.md. Link to it. Keep agent instructions behavioral and short.
AGENTS.md vs IDE-specific rules
| File | Scope |
|---|---|
AGENTS.md | Universal baseline for many agents |
| Cursor / Claude / Windsurf rule files | Native always-on control |
Best setup for many teams: a short universal baseline plus Token Kits for the maintained token-saving pack.
What to put in AGENTS.md
Keep it to project truths:
- Non-negotiable product constraints
- Stack summary (short)
- Verify commands
- Out-of-scope defaults
Avoid dumping a full cost-control system into AGENTS.md by hand — that becomes stale and soft. Buy the pack that exists for that job.
Keep it token-cheap
AGENTS.md is loaded often. Every fluffy paragraph is a tax.
- Prefer bullets over paragraphs
- Cap always-on guidance
- Put rare edge cases in linked docs
- Don’t paste secrets
Buy Token Kits for the real pack
Token Kits is lifetime access to the battle-tested pack that cuts agent token spend roughly in half:
- Works with Cursor, Claude Code, Windsurf, Copilot,
AGENTS.md, and more - Install instructions provided after purchase
- $39 prelaunch (first 100), then $79 one-time
- No subscription
Lean context beats dumping the whole repo
When you need AGENTS.md
Add it when:
- Multiple agents touch the repo
- Onboarding agents keep reading the wrong trees
- You want git-tracked instructions that survive tool switches
Skip a novel. Ship a tight operating manual — and buy Token Kits for the enforcement layer.
FAQ
Is AGENTS.md an official standard?
It’s an emerging community convention — useful because it’s obvious, portable, and git-friendly.
Should every repo have one?
If agents edit the repo weekly, yes. Pair it with a purchased pack so cost discipline isn’t optional.
Can I get Token Kits from this article for free?
No. These posts promote the product; they don’t unpack it. Buy here.
Bottom line
AGENTS.md is a control surface. Keep it short — and buy Token Kits for the pack agents actually need.
Next: Save tokens while AI coding · Cursor vs Claude vs Copilot