AGENTS.md

Why you'd careThe problem it solves

Count the files in your repo that tell an agent to use pnpm rather than npm. There is probably a CLAUDE.md, something under .cursor/rules/, a .github/copilot-instructions.md, and a paragraph in the README nobody reads. They agreed when you wrote them. They do not agree now, because six weeks ago you changed the test command in two of the four. The symptom is a teammate reporting that "the agent keeps running npm install" on a repo where you fixed that ages ago — in a file their tool does not read. AGENTS.md is the answer to exactly that: one file, at the root, that the largest number of agents will pick up without configuration.

ConceptWhat it is

AGENTS.md is plain Markdown at the root of a repository, read as standing project context when an agent session starts. There is no schema. No frontmatter, no required headings, no reserved keys. Whatever you write, the agent gets, every session, in full.

Nesting is the one structural rule worth knowing, and it is a convention rather than a spec: many tools support AGENTS.md files in subdirectories, with the nearest file up the tree from the work winning. In a monorepo that lets packages/worker/AGENTS.md carry deployment specifics without inflating what every other package pays for.

Governance is the reason this entry reads differently from a typical vendor convention. AGENTS.md was contributed by OpenAI and is now stewarded by the Agentic AI Foundation under the Linux Foundation — primary-sourced, and worth stating plainly, because an earlier draft of this page hedged it. That matters practically: a cross-vendor convention with a neutral home is a safer thing to standardise a monorepo on than one vendor's filename.

The boundary is the always-on part. A skill is named and conditional — the model reads a description line and decides. AGENTS.md has no trigger and no name; it is in context whether or not it is relevant, which makes it the right home for the four things that are always true and the wrong home for a 300-line runbook. It is also, strictly, a file on a disk. Nothing hosted reads it.

How it worksThe mechanics

The layout is the whole mechanism.

repo/
  AGENTS.md              # applies to work anywhere in the repo
  packages/
    worker/
      AGENTS.md          # nearest file wins for edits under worker/

Content is ordinary Markdown, and the only real discipline is imperative brevity — you pay for this in tokens on every single turn.

# Build
pnpm install --frozen-lockfile
pnpm -w test          # vitest, never jest

# Conventions
- Never hand-edit anything under generated/.
- Local D1 seeding requires the dev server stopped first.
- Cloudflare secrets are request-time only; they do not exist at build.

# Do not
- Do not commit or push unless explicitly asked.

Loading is done by the harness before the model runs. Different clients place it differently — some as part of the system prompt, some as a leading user-turn block — and none of them show you the token bill directly, which is why a 900-line AGENTS.md is a real and invisible cost.

Claude Code is the interesting case. Its documented file is CLAUDE.md, and native AGENTS.md discovery was not verified on 2026-07-25 — do not assume it either way. The portable fix does not depend on the answer: keep AGENTS.md as the single source of truth and make CLAUDE.md a one-line file that imports it.

# CLAUDE.md
@AGENTS.md

The @path import is Claude Code's own syntax and pulls the referenced file's contents into context. A symlink works too, with the usual Windows caveat. Either way you maintain one file and the second one is a pointer, which is the only arrangement that survives contact with a team.

One habit worth adopting: when you change a build command, change it in AGENTS.md and delete it everywhere else rather than updating both. Duplication is what broke the last four files.

At a glanceSee it

Nearest AGENTS.md wins, and the split between clients that read it and endpoints that cannot.

Where it runsSurfaces and availability

The old generalisation — every "Yes" is a tool with a working tree, every "No" is a hosted endpoint — no longer holds. Google's hosted agents load .agents/AGENTS.md from the agent's environment as system instructions, and OpenAI's Responses API mounts skill bundles the same way. What actually stops at the API boundary is your filesystem, not the file convention: hosted harnesses read these files from a sandbox that something has to populate, so shipping AGENTS.md to them is a build step rather than a checkout. If your product calls a model directly with no sandbox in the loop, AGENTS.md remains a source file your build reads, not a feature you get.

ExampleIn the real world

A monorepo: web app, a Cloudflare Worker, a shared package. The root AGENTS.md is nine lines — pnpm with a frozen lockfile, pnpm -w test, never hand-edit generated/, never commit unless asked.

packages/worker/AGENTS.md adds four more, and they are exactly the ones that have burned somebody: seeding the local D1 database requires the dev server to be stopped first, and secrets are request-time only so they are absent during a build.

A developer opens Codex in packages/worker/ and asks it to add an endpoint and seed a test row. The harness loads the nearest AGENTS.md, so the model stops the dev server before seeding — a step nobody typed in the prompt and which fails silently and confusingly when skipped.

A second developer, in Claude Code, gets the identical behaviour because CLAUDE.md is one line: @AGENTS.md. When the test command changes next quarter, it changes in one file and both of them are correct the next morning. The reviewer on the pull request sees a two-line diff in AGENTS.md instead of the same edit repeated across four vendor files, three of which somebody would have missed.

Not thisWhat it is often confused with

• Not a skillAGENTS.md is always loaded and always paid for. A skill has a name and a description, loads its body only when the model matches it, and can bundle scripts and reference files. Long conditional procedures belong in a skill.
• Not a schemathere is no validator and no required section. "AGENTS.md compliant" means the file exists at the root and is Markdown. Anyone selling you more structure than that is describing their own tool's conventions.
• Not a permission systemit is advice in the context window. It cannot stop an agent running a destructive command. Enforcement lives in permission settings, hooks and CI.
• Not a READMEthe README is prose for a human arriving on the project. AGENTS.md is the imperative subset an agent needs to act correctly, and every sentence in it is billed on every turn.
• Not a system promptit is harness-assembled context. The provider's system field is set by whoever wrote the harness; a raw API call sees neither unless your code supplies them.

LimitsWhen not to reach for it

• The procedure only applies sometimes.A release runbook or a migration checklist should be a skill, so it costs nothing on the sessions that never touch it.
• It contains secrets or machine-specific paths.This file is committed and shared. Local-only guidance belongs in an untracked or user-scoped file.
• It has to be enforced, not suggested."Never push to main" in Markdown is a preference. In a hook or a branch protection rule it is a fact.
• The file is already 800 lines.You are paying that on every turn and burying the four rules that matter. Split into nested files, move the long parts into skills, and keep the root file short enough to read in one screen.
• You are shipping a product that calls the API.There is no repo at runtime. Put the standing instructions in your system prompt and treat AGENTS.md as build-time input.

RelatedGo deeper