--- title: How to write an effective AGENTS.md description: A step-by-step guide to writing an AGENTS.md skill file that coding agents (Codex, Claude Code, Cursor) can actually use. Required sections, format conventions, common pitfalls. last_updated: 2026-05-11 canonical_url: https://agent-ready.dev/how-to-write-an-effective-agents-md --- # How to write an effective AGENTS.md > A step-by-step guide to writing a skill file that coding agents — Codex, Claude Code, Cursor, Aider — can actually use. ## 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](https://agents.md) and is read by Codex, Cursor, Aider, and a growing list of IDE agents. For the validation spec, see [our validator](https://agent-ready.dev/agents-md-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](https://agent-ready.dev/agents-md-vs-claude-md-vs-cursorrules) if you're deciding which files to ship. ## Step-by-step ### Step 1 — Create AGENTS.md at the repo root Add a file named AGENTS.md (exact case) at the root of your repository. Agents like Codex, Cursor, and Aider look there first. Alternate paths that validators accept include /agents.md, /.well-known/agents.md, and /docs/AGENTS.md, but the repo root is the canonical location. ### Step 2 — Open with a one-sentence project overview The first line under the H1 should describe what the project is and what stack it uses, in one or two sentences. Coding agents skim this to decide what kind of code to write. Keep it factual and current — version numbers, language, framework. Avoid marketing copy. ### Step 3 — Document install, build, and test commands Spell out the exact CLI invocations an agent needs to run the project: install dependencies, start the dev server, run tests, lint, type-check. Use fenced code blocks with the right language tag so agents parse them as runnable commands. This is the single highest-value section of an AGENTS.md. ### 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. ### Step 5 — Validate against the agent-readability scanner Run your repo's AGENTS.md through agent-ready.dev/agents-md-validator to confirm it has at least two of: install commands, configuration details, and usage examples. The validator also flags missing sections, 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: ```markdown # 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. --- Read the full guide on the web: Validate your AGENTS.md: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.