Skip to main content
The file must be named AGENTS.md — the name is case-sensitive. Place it at the root of your repository or inside any subdirectory. Agents look for this exact filename when reading context for a task.
No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide. There is no schema, no required sections, and no special syntax.
No. The format is plain Markdown. Any valid .md file named AGENTS.md is valid. Conventionally, ## headings are used to separate topic areas, but even this is not required.
Yes. In a monorepo, you can place an AGENTS.md in the root and additional ones inside each package or subdirectory. Agents automatically read the nearest file in the directory tree — the closest one to the file being edited takes precedence. The OpenAI main repository uses 88 AGENTS.md files.
Yes. Agents look for AGENTS.md at the repository root and walk up the directory tree from the file being edited to find the nearest one. You do not need to reference it explicitly in your prompts.
The closest AGENTS.md to the edited file wins. Explicit user chat prompts override everything — instructions given directly in chat always take precedence over AGENTS.md.
Yes — if you list them. The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task. Be explicit about which commands must pass before a change is considered complete.
No. Only include commands that are non-obvious or that agents are likely to get wrong without guidance. If npm test is the only test command and it works from the root, you may not need to document it at all. Focus on commands with special flags, filters, or prerequisites.
Absolutely. Treat AGENTS.md as living documentation. Update it whenever your build process, conventions, or tooling changes.
Rename your existing file and create a symbolic link so tools that expect the old name still work:
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Configure Aider to read AGENTS.md by adding the following to .aider.conf.yml:
read: AGENTS.md
Configure Gemini CLI to use AGENTS.md in .gemini/settings.json:
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

​
More resources

Format reference

Complete reference for the AGENTS.md format, recommended sections, and examples.

Agent compatibility

See which agents support AGENTS.md and any agent-specific notes.

Quickstart

Create your first AGENTS.md file in minutes.

What to include

A guide to the sections that matter most.

Build docs developers (and LLMs) love

Get started for freeTalk to us