What's the difference between AGENTS.md and a README?

READMEs target humans evaluating or contributing to your project. AGENTS.md targets coding agents working in the repo. The agents file is shorter, more imperative, and assumes the reader has full file-system access. Many projects ship both; the AGENTS.md links to the README for human-facing context.

How long should AGENTS.md be?

Short. Most effective files are 50-200 lines. Anything longer typically means rules belong in dedicated docs (CONTRIBUTING.md, architecture decision records) that AGENTS.md links to. Agents have finite context windows — fight for every line.

Should AGENTS.md mention which AI model the project was built with?

Rarely useful. Coding agents care what the code looks like and how to work with it now, not which assistant wrote it originally. Skip it unless the model choice has a concrete bearing on conventions an agent must follow.

Can I link out to other Markdown files from AGENTS.md?

Yes, and it's a good pattern. Keep AGENTS.md as a concise index; offload deep architecture notes, full style guides, or domain glossaries to dedicated files and link to them. Modern agents follow Markdown links during their working session.

Do I need to update AGENTS.md every release?

Only when commands, conventions, or constraints change. Treat it as living documentation — bump it whenever an agent (yours or someone else's) makes a mistake that the file could have prevented. Stale instructions are worse than missing instructions.

How to write an effective AGENTS.md

What is AGENTS.md?

AGENTS.md is a Markdown skill file placed at the root of a code repository. It tells coding agents what the project is, how to install and run it, and which conventions to follow when writing code. The format is documented at agents.md and is read by Codex, Cursor, Aider, and a growing list of IDE agents. For the validation spec, see our validator.

Where should AGENTS.md live in your repo?

At the repository root. Coding agents check /AGENTS.md first; validators also accept /agents.md, /.well-known/agents.md, and /docs/AGENTS.md as fallbacks. Pick the root path unless you have a specific reason not to — alternate locations work but are less discoverable. See our comparison of AGENTS.md, CLAUDE.md, and .cursorrules if you’re deciding which files to ship.

Step 1 — Create AGENTS.md at the repo root

From your project root, create the file. The exact case matters: AGENTS.md is the canonical capitalisation. Most agents are case-sensitive about discovery paths.

# from your repo root
touch AGENTS.md

Step 2 — Open with a one-sentence project overview

Start with an # H1 (your project name), then a > blockquote in one or two sentences that names what the project is and what stack it uses. Coding agents skim this to decide what kind of code to write — the more specific, the better. Version numbers, language, framework. No marketing copy.

Step 3 — Document install, build, and test commands

The single highest-value section. List the exact CLI invocations an agent needs — install dependencies, start the dev server, run tests, lint, type-check — in fenced code blocks with the right language tag (bash, sh). Agents parse these as runnable commands. Skip explanation prose; the commands themselves should be self-evident.

Step 4 — Spell out coding conventions and constraints

List the rules an agent must follow: language version, frameworks to prefer or avoid, naming conventions, files or directories not to touch, security constraints, commit-message format. Each rule should be specific enough that a fresh agent reading the file can apply it correctly on the first attempt. “Use TypeScript strict mode” is fine; “write clean code” is not.

Step 5 — Validate against the agent-readability scanner

Run your repo’s AGENTS.md through the AGENTS.md validator to confirm it has at least two of: install commands, configuration details, and usage examples. The validator also flags ambiguous rules and structural problems that hurt agent comprehension.

What does a strong AGENTS.md look like?

A complete example covering the five steps above — an imaginary TypeScript SDK with install, build, test, conventions, and a “don’t touch” section:

# Acme SDK

> TypeScript client library for the Acme API. Targets Node.js 20+ and modern browsers.

## Install

```bash
pnpm install
```

## Build & test

```bash
pnpm build          # bundles dist/
pnpm test           # vitest, full suite
pnpm test --watch   # watch mode for the file you're editing
pnpm lint           # eslint + prettier --check
pnpm typecheck      # tsc --noEmit
```

## Run the example

Set `ACME_API_KEY` in your environment, then:

```bash
pnpm tsx examples/quickstart.ts
```

## Conventions

- Public functions take a single options object, never positional args.
- Async functions only; never callbacks.
- All errors throw `AcmeError` subclasses — never plain `Error`.
- Use `#private` field syntax, not TypeScript `private`.
- Tests live next to source as `*.test.ts`, not in a top-level `tests/` dir.

## Don't touch

- `dist/` (generated by `pnpm build`)
- `src/generated/` (codegen from OpenAPI; run `pnpm codegen` to regenerate)
- `CHANGELOG.md` (managed by release-please)

## Further reading

- `docs/architecture.md` — module boundaries and data flow
- `CONTRIBUTING.md` — human-facing contribution guide

~50 lines, covers everything an agent needs to make safe changes. Notice how every command is copy-pasteable and every convention is specific enough to action.

Common pitfalls when writing AGENTS.md

Too much marketing prose. Agents don’t care about your vision; they need facts about how the code works. Cut anything that doesn’t change what they’ll type.
Vague conventions. “Follow our code style” is useless. “Use #private field syntax instead of TypeScript private” is actionable.
Missing “don’t touch” section. Generated files, vendored code, files under release-please control — flag anything an agent should never edit, with the reason in one line.
Stale commands. When you switch package managers or test runners, update AGENTS.md the same commit. An outdated npm test command in a pnpm project breaks every agent session.
Trying to be exhaustive. AGENTS.md is the index, not the encyclopedia. Link out to deeper docs (docs/architecture.md, ADRs) rather than inlining everything.

Frequently asked questions

What's the difference between AGENTS.md and a README?: READMEs target humans evaluating or contributing to your project. AGENTS.md targets coding agents working in the repo. The agents file is shorter, more imperative, and assumes the reader has full file-system access. Many projects ship both; the AGENTS.md links to the README for human-facing context.
How long should AGENTS.md be?: Short. Most effective files are 50-200 lines. Anything longer typically means rules belong in dedicated docs (CONTRIBUTING.md, architecture decision records) that AGENTS.md links to. Agents have finite context windows — fight for every line.
Should AGENTS.md mention which AI model the project was built with?: Rarely useful. Coding agents care what the code looks like and how to work with it now, not which assistant wrote it originally. Skip it unless the model choice has a concrete bearing on conventions an agent must follow.
Can I link out to other Markdown files from AGENTS.md?: Yes, and it's a good pattern. Keep AGENTS.md as a concise index; offload deep architecture notes, full style guides, or domain glossaries to dedicated files and link to them. Modern agents follow Markdown links during their working session.
Do I need to update AGENTS.md every release?: Only when commands, conventions, or constraints change. Treat it as living documentation — bump it whenever an agent (yours or someone else's) makes a mistake that the file could have prevented. Stale instructions are worse than missing instructions.