AGENTS.md contents and where agents stop reading

AGENTS.md is a Markdown file of instructions that a coding agent loads before it starts work, usually from the root of a repository. It has no required fields and no fixed headings. OpenAI Codex, Cursor, GitHub Copilot, Devin and most other coding agents read it. CLAUDE.md vs AGENTS.md sets out which file each agent reads, including the few that need a setting first.

Fill it with the commands, conventions and rules that apply to every task and that the agent can’t work out from the code. Keep it short, because several agents stop reading at a fixed size. Codex stops at 32 KiB across all the AGENTS.md files it combines, and Devin’s cloud agent reads only the first 16 KiB of each file. Procedures belong in skills, and anything a linter can check belongs in the linter.

Every agent’s behaviour below was checked against its own documentation, or its source where the docs are silent, on 12 October 2026. Agents often change how they load these files, so treat that date as part of the answer.

The AGENTS.md format and who looks after it

• agents.md, the format’s own site, calls the file a README for agents, a predictable place for the context and instructions an agent needs to work on your project.
• Its FAQ says there are no required fields. It’s standard Markdown, any headings will do and the agent reads the text as it stands.
• Nothing on the site sets a length for the file or says how to import or link other files.

OpenAI released the format in August 2025. On 9 December 2025 the Linux Foundation announced the Agentic AI Foundation, with three founding projects: Anthropic’s MCP, Block’s goose and OpenAI’s AGENTS.md. The agents.md site now says the foundation looks after the format under the Linux Foundation. It puts adoption at over 60,000 open-source projects. The foundation’s announcement gave a similar figure.

Because the standard says so little, each agent decides how long the file may be and what to do with nested files. That’s why both work so differently from one agent to the next.

Root and nested AGENTS.md files

A repository can hold more than one AGENTS.md. The root file covers the whole project. A file in a subfolder adds rules for the code below it. For conflicts, the agents.md site gives one rule. The AGENTS.md closest to the edited file wins, and any explicit instruction in the chat overrides everything. GitHub’s docs say the same for Copilot, where the nearest file takes precedence.

Agents disagree on when a nested file arrives. Some read it at start-up, some only once they work on a file in its folder and some never read it at all.

• Amp includes a subfolder’s AGENTS.md when the agent reads a file in that subfolder.
• Claude Code reads a subfolder’s AGENTS.md when it opens a file there, as long as the subfolder has no CLAUDE.md of its own.
• Cursor applies a nested file when it works with files in that folder. It combines the file with its parents, with the more specific instruction winning.
• Kilo Code and goose load a subfolder’s file once the agent reads or opens a file there.
• Antigravity walks up from a file’s folder to the workspace root whenever it reads or edits that file, and loads the rules at each level.
• Factory Droid finds a subfolder’s AGENTS.md as it reads files under that folder.
• Zed reads one instruction file from the root of each project, according to its source, so it never sees a nested one. VS Code reads nested files only with its experimental chat.useNestedAgentsMdFiles setting, which is off by default.

So anything that must hold everywhere belongs in the root file, because a nested file may arrive late or not at all. A nested file should hold only what’s different about its folder. Factory’s docs say so directly. Use nested files for real differences, such as another package manager or generated code, and don’t use them to repeat root rules.

How Codex combines AGENTS.md files

OpenAI’s Custom instructions with AGENTS.md (2026) sets out the order. Codex reads a global file from ~/.codex first. Then it walks from the project root, usually the Git root, down to the folder you started in, and takes at most one file from each folder. In each folder, AGENTS.override.md wins over AGENTS.md. Started in services/billing, Codex joins these files in this order:

~/.codex/AGENTS.md
AGENTS.md
services/billing/AGENTS.md

A file nearer your folder comes later, so it overrides what came before it. Codex stops at the folder you started in, so a file further down isn’t loaded at start-up. For code review, OpenAI’s Review GitHub pull requests with Codex (2026) advises a ## Code Review Rules section in the AGENTS.md closest to the code it governs. In GitHub, Codex then flags only P0 and P1 issues.

AGENTS.md size limits: where each agent stops

AGENTS.md has no standard length, so each agent sets its own, in whatever unit suits it. A KiB is 1,024 bytes, so Codex’s 32 KiB is 32,768 bytes. In plain English text a character is one byte, but an accented letter or a curly quote takes two or three. These documented limits reach AGENTS.md:

Other figures are advice, or caps that may not cover AGENTS.md. Anthropic’s memory docs target under 200 lines for a CLAUDE.md. Claude Code reads that file in place of AGENTS.md when both exist. They say longer files “consume more context and reduce adherence”. Cursor advises keeping a rule under 500 lines. Antigravity caps a rule file at 24,000 bytes and all its always-on rules at 20,000 tokens together, though its docs don’t say whether AGENTS.md counts towards that budget.

Nothing fails when a file runs past a limit. An agent works from what it kept, so you find out from the code it writes. So the order of the file matters as much as its length.

Keep critical instructions near the top.

The Prickles canon shows the problem. All 51 tenets in one AGENTS.md come to 37,949 bytes. Codex would cut that file short of the end, and Devin’s cloud agent would read less than half of it. AI3 Working Context gives the reason to keep it smaller. Release 3.0.0, published on 13 October 2026, restructures every pack around an always-loaded entry. Its AGENTS.md states every tenet’s rule in 11,327 bytes, measured on 23 October 2026, and points to the rest.

To check your own file, count its bytes:

wc -c AGENTS.md

Compare the result with 16,384 if anyone on your team uses Devin’s cloud agent, and with 32,768 for Codex. Codex counts every AGENTS.md on the path from the root to your folder together, so leave room for the nested ones.

What to put in AGENTS.md

AI2 Persistent Brief gives the reason the file exists: “Anything you would say twice belongs in a file the model loads on every session.” The vendors broadly agree on what that covers:

• Anthropic’s memory docs say to keep to facts the agent should hold in every session, such as build commands, conventions, project layout and “always do X” rules.
• Factory’s guide adds testing rules, generated files, security rules and what a pull request needs.
• agents.md itself suggests a project overview, build and test commands, code style, testing instructions and security considerations.

Two studies from 2026 ran agents with and without the file:

Agents did follow what the files said. In Gloaguen’s study, agents used uv 1.6 times a task on average when a file mentioned it, against under 0.01 times when it didn’t. Repository overviews didn’t help them reach the right files any sooner. Gloaguen and colleagues conclude that context files are useful for specifying non-standard coding practices.

So write what the agent can’t infer, such as the package manager you use, the command that runs one test or a convention that differs from the framework’s default. Make each rule specific enough to check. Anthropic’s example is “Use 2-space indentation” rather than “Format code properly”, and VS Code’s docs ask for each instruction to be a single, simple statement.

Write the rule itself into AGENTS.md, because a line that only refers to it does much less. In A First Look at Coding Agents’ Compliance with AI Contribution Rules (2026), Wenhao Yang, Runzhi He and Minghui Zhou tested agents against AI contribution policies. Left to find the policy on their own, the agents opened it in 12 of 347 runs. A one-line reminder in AGENTS.md helped some pairs. Quoting the rule there lifted three of the four pairs further:

Each figure gives the share of runs that met the policy’s disclosure rule, from about 30 runs a cell. Yang, He and Zhou tested contribution rules, and no comparable study of coding standards was found.

What to leave out of AGENTS.md

• Style rules a linter or formatter can enforce. Anthropic’s docs say Claude treats instruction files as context, and point to a hook when an action must be blocked whatever Claude decides. HumanLayer’s Writing a good CLAUDE.md (2025) puts it more bluntly: “Never send an LLM to do a linter’s job.”
• Multi-step procedures, such as a release or a database migration. Factory’s guide says not to paste long run books into AGENTS.md. Put them in a skill, as the next section explains.
• A tour of the repository or a list of every directory. Factory warns that directory lists drift from the code. In Gloaguen’s study, overviews didn’t help. Keep them in the README.
• Secrets, and notes on the task in hand. Factory’s guide says those notes belong in an issue, a pull request or a spec.
• Copies of documents that live elsewhere. Cursor’s rules docs say to reference a file instead of copying it, so it can’t go stale.
• A second copy of the same rules in another agent’s file. CLAUDE.md vs AGENTS.md shows how copies drift apart and how to keep one source.

Telling the agent which rule it broke does more still. In Yang, He and Zhou’s study, one round of feedback naming the broken clause fixed most failing runs. The share ran from 55% to 100%, depending on the agent and the rule. A linter gives that kind of feedback every time it runs. TA1 Linter as Law asks you to move every check you can into one.

AGENTS.md and skills

A skill is a folder holding a SKILL.md file, under the Agent Skills specification (2026). An agent loads every skill’s name and description at start-up, about 100 tokens each, and reads the rest only when it decides the skill is relevant. That makes a skill the place for detail an agent needs now and then, and AGENTS.md the place for what it needs every time. Antigravity’s rules docs draw the same line, with a rule for constraints and invariants and a skill for multi-step workflows.

An agent may never open the skill. In Vercel’s evals, which CLAUDE.md vs AGENTS.md covers, a skill went uninvoked in 56% of cases. A compressed docs index in AGENTS.md passed every test. Jude Gao’s write-up (Vercel, 2026) concludes that for general framework knowledge, always-loaded context currently does better than retrieval on demand. So keep the rule in AGENTS.md and the detail in the skill, and tell the agent when to read it. Write the path as plain text, tied to a moment in the task:

- Before you write a database migration, read `.agents/skills/db-migrations/SKILL.md`.

Don’t write it as an @ import. Claude Code and goose load an @-mentioned file at once, as does Amp unless the file sets globs, so the detail goes back into every session. opencode’s rules docs show the lazy version, an instruction in AGENTS.md to load a referenced file with the Read tool on a need-to-know basis.

Skills live in different folders for different agents. Codex scans .agents/skills in every folder from the one you start in up to the repository root, according to OpenAI’s Build skills (2026). The comparison article lists the other agents that read that folder. Claude Code reads .claude/skills, and Anthropic’s skills page doesn’t mention .agents/skills. Kiro’s skills page names .kiro/skills and is silent on .agents/skills too. A repository shared across agents needs a copy of each skill in those two folders as well.

An AGENTS.md example

Here’s an AGENTS.md for a small TypeScript service, to use as a template. It’s illustrative, and each part follows the advice above. Commands come first, then the conventions an agent couldn’t guess and what it mustn’t touch. Then come pointers, each with a moment to read it, and review rules for Codex.

# AGENTS.md

## Commands

- Install: `pnpm install`
- Run one test file: `pnpm vitest run src/orders/order-total.spec.ts`
- Before you say a task is done: `pnpm lint && pnpm typecheck && pnpm test`

## House rules

- Use pnpm. Never run npm or yarn, because they ignore `pnpm-lock.yaml`.
- Keep each test next to the file it tests, named `*.spec.ts`.
- Validate request bodies with the schemas in `src/schemas/`. Don't write a validator by hand.
- Store money as a whole number of pence. Never use a float for it.

## Off limits

- Never edit `src/generated/`. Change the schema and run `pnpm codegen`.
- Ask before you add a dependency.

## When to read more

- Before you write a database migration, read `.agents/skills/db-migrations/SKILL.md`.
- Before you cut a release, read `.agents/skills/release/SKILL.md`.
- `services/billing/AGENTS.md` adds rules for the billing service.

## Code Review Rules

- Flag any change to `src/generated/` that didn't come from `pnpm codegen`.
- Flag money stored or calculated as a float.

It runs to 30 lines and 1,028 bytes. There’s no overview and no list of folders, because the README and the code already hold both. Formatting and type rules are missing too, because pnpm lint and pnpm typecheck check them.

The Prickles AGENTS.md

The Prickles packs take the same shape for coding standards. From release 3.0.0, the pack for AGENTS.md agents installs an AGENTS.md that holds the rule of each of the 51 tenets in 87 lines, under nine pillar headings. Each heading names the skill that holds the rest of that pillar and says when to read it. This is how it opens:

# Prickles canon v4.0.0: the 51 tenets

Every tenet below binds any code you write, change, test or review in this repository. Each line is the tenet's rule. The file named in each heading holds the rest of that pillar's tenets and binds you exactly as this file does.

IMPORTANT: reading a pillar's file is a precondition. Read it with your file-read tool before your first edit of the kind its heading names, and again after your context is compacted.

## Foundations (F1–F6). Before you write or change source code, read `.agents/skills/prickles-foundations/SKILL.md`.

- **F1 Single Responsibility Principle.** One obvious job per function, class, or module. When a second concern shows up in the same unit, peel it out so each piece has its own reason to change.
- **F2 Intention-Revealing Names.** Use names that answer why this exists and what it does in the domain vocabulary. If the signature does not hold the meaning, rename.

It ends with a ## Code Review Rules section, the heading Codex code review looks for. That section treats a change that breaks any tenet as a finding, named by the tenet’s ID. The nine skills sit in .agents/skills, with byte-identical copies in .kiro/skills for Kiro. Download the pack for your language from the implementation page. It also has a pack in each agent’s own format.

How to write an AGENTS.md

1. List the commands an agent needs to install, run one test and check its work before it finishes.
2. Add the conventions an agent couldn’t infer from the code, such as the package manager or a rule that differs from the framework’s default.
3. Write each rule as one specific instruction, and put the most important rules first.
4. Move multi-step procedures into skills, and point to each with a plain path and the moment to read it.
5. Move anything a linter, formatter or type checker can enforce into that tool’s config.
6. Put rules that apply to one folder in that folder’s own AGENTS.md.
7. Run wc -c AGENTS.md and keep the result well under the smallest limit among the agents your team uses.
8. If your team uses more than one agent, keep this file as the single source, as CLAUDE.md vs AGENTS.md explains.
9. Add a rule when an agent makes the same mistake more than once, as Cursor’s docs suggest.