AGENTS.md: The Cross-Tool Standard

README for agents: the project contract every tool can read

What Is AGENTS.md

AGENTS.md is a convention file at the project root that gives coding agents operating context: how to install, build, test, what conventions to follow, and what not to touch. Think of it as a README for agents — a vendor-neutral, project-level contract.

It is read natively by 20+ tools: Cursor, Codex, Copilot, Windsurf, Gemini CLI, Aider, and more. Over 60,000 repositories already ship one. Governance sits with the Linux Foundation’s Agentic AI Foundation, keeping it tool-agnostic.

Why this matters for this wiki: AGENTS.md is the first-recommendation project-level carrier for conventions in 2026. Project Rules (.cursor/rules/) remain the best tool for path-level precision inside Cursor. The two coexist — see the composition example below.

Why You Need It

Three reasons it exists:

Project context is not portable. A prompt like “improve performance, make no mistakes” gives each tool different assumptions. AGENTS.md standardizes the context every agent starts with.
Pure prompts are unreliable. Requirements live in chat history and get lost across sessions; a checked-in file survives.
Code cannot always explain itself. Architecture choices, external constraints, and “do not touch X because Y” are invisible to a code reader — AGENTS.md records the why that code omits.

Agent-friendly signals in a codebase include strict types, meaningful test coverage, consistent patterns, decision-point comments, and a project instruction file that exists and is fresh. Without it, agents pattern-match on whatever the code happens to imply.

Anatomy of a Good AGENTS.md

- AGENTS.md

A healthy AGENTS.md stays around 50 lines: stack, commands, protected paths, conventions. Example:


# AGENTS.md
 
## Dev Environment
- Node 20+, pnpm 9
- Python 3.12 for `scripts/` tooling
- Env vars documented in `.env.example`
 
## Commands
- `pnpm install` — install dependencies
- `pnpm dev` — start the dev server on :5173
- `pnpm lint` — ESLint (must pass)
- `pnpm test` — Vitest unit tests (must pass)
- `pnpm build` — type-check + production build
 
## PR Requirements
- Link the issue number in the PR description
- Run `pnpm lint` and `pnpm test` before requesting review
- Keep changes under ~400 lines unless discussed
 
## Do Not Touch
- `generated/` — regenerated by `pnpm codegen`
- `infra/` — owned by the platform team (see #ops)
- Never commit changes to `.env` files
 
## Architecture Conventions
- Pages in `src/pages/`, use default exports
- Data fetching via `@/clients/`, never inline fetch
- State in Zustand stores, avoid prop drilling > 2 levels
 
## Testing
- Unit tests co-located as `*.test.ts`
- E2E covers only critical user journeys
 
## Notes for Agents
- When unsure, read `.memory/README.md` before starting
- Never use `any`; use `unknown` and narrow

Division of Labor: AGENTS.md vs Rules vs Skills vs MCP

Layer	What It Carries	When to Use
AGENTS.md	Portable contract: stack, commands, conventions, protected paths	Every session, every tool — the project baseline
Project Rules (`.cursor/rules/`)	Same content plus path-level scope via globs and four application modes	You need precision inside Cursor beyond the baseline
Skills (`.cursor/skills/`)	Procedural depth: review, release, migration workflows, loaded on demand	A repeatable task workflow, not always-on context
MCP servers	Runtime tools and live data	The agent needs real-time external data or actions

Recommended Composition (avoids duplication)


AGENTS.md          → ~50 lines: stack, commands, do-not-touch
.cursor/rules/     → path-specific additions (globs on src/**, tests/**)
.cursor/skills/    → procedural depth (release checklist, migration walkthrough)
MCP servers        → runtime tools and data

Rule of thumb: every session needs it → AGENTS.md or rules. Only some tasks → a skill. Live data → MCP.

AGENTS.md vs Rules: Same Content, Different Reach

Aspect	AGENTS.md	Cursor Rules (`.mdc`)
Reach	20+ tools natively	Cursor only
Scoping	Whole repository	globs, alwaysApply, @-mention
Governance	Open standard (60k+ repos)	Cursor ecosystem
Typical size	~50 lines	1-3 lines per rule item

Most teams make AGENTS.md the canonical baseline and keep tool-specific files for the differences.

CLAUDE.md Bridge

If your team also runs Claude Code: Claude Code reads CLAUDE.md, not AGENTS.md natively. Bridge it with one line:


<!-- CLAUDE.md -->
@AGENTS.md

or a symlink: ln -s AGENTS.md CLAUDE.md. Then maintain one canonical file instead of two copies. (Note: @AGENTS.md in Claude Code refers to the local file)

Nested AGENTS.md and Overrides

sub-AGENTS.md — a nested AGENTS.md in a subdirectory refines conventions for that subtree (e.g. a monorepo package).
AGENTS.override.md — replaces the root AGENTS.md for special cases (e.g. a vendored third-party directory).

These compose with the root file to give you hierarchical project context.

Relationship to This Chapter

Writing principles apply unchanged to AGENTS.md — see Writing Best Practices.
AGENTS.md is the project’s “root file”: establish the first version right after scaffolding, then extend it as the project evolves — see Development Phases.
You can generate its skeleton with the Meta Prompts flow.

Reference Sources

materials/02-agents-md-rules/agents-md-spec.md
materials/02-agents-md-rules/redhat-agents-md-and-skills.md
materials/02-agents-md-rules/webreference-rules-vs-agents-vs-skills.md
materials/02-agents-md-rules/getunblocked-claude-vs-agents-vs-cursor.md
materials/04-legacy-brownfield/agentpatterns-codebase-readiness.md

Next Steps

Learn how to write excellent rules and AGENTS.md content in Writing Best Practices.