What is AGENTS.md?

By Ricardo Cardona · September 21, 2026

AGENTS.md is an open format for giving AI agents instructions: a plain markdown file, usually at the root of a folder, that coding agents such as Codex, Cursor and GitHub Copilot’s coding agent read before they start work. It’s where you write down what an agent should know and how it should behave, once, instead of repeating it in every chat.

It started with software projects, but nothing in the format is about code. A folder that holds your business can have one too.

What the format is

There’s almost nothing to learn. The file is standard markdown with no required fields: use any headings you like, and the agent reads the text. The format’s own site, agents.md, suggests sections such as an overview, the commands to run, style rules and security notes, and it reports use in over 60,000 open-source projects. It’s stewarded by the Agentic AI Foundation under the Linux Foundation, which also hosts MCP.

Two rules decide what an agent follows:

The nearest file wins. When a folder has several AGENTS.md files, an agent follows the one closest to the file it’s working on, so a subfolder can carry its own instructions.
You win over the file. What you type in the chat overrides it.

Who reads it

agents.md lists about two dozen agents and tools that support the format, among them Codex, Cursor, Jules, Zed, Warp, VS Code, Devin, Junie and GitHub Copilot’s coding agent. Three details are worth knowing:

Codex reads a global ~/.codex/AGENTS.md, then every AGENTS.md from the top of the project down to where you’re working, joined in that order, so the closest file has the last word. It stops adding files at 32 KiB by default, and it reads them once, when a session starts.
Claude Code reads AGENTS.md itself, from version 2.1.277, when there’s no CLAUDE.md in the folder or above it. If you keep a CLAUDE.md, start it with the line @AGENTS.md and it reads the same file, without loading it twice.
Gemini CLI and Aider read it after a one-line setting:

Gemini CLI, in .gemini/settings.json:
{ "context": { "fileName": "AGENTS.md" } }

Aider, in .aider.conf.yml:
read: AGENTS.md

What to put in one for a business

A repo’s AGENTS.md covers build commands and code style. A business folder’s covers the business. Keep it to a page and point to detail files instead of pasting them in:

# About this business
What we sell: [offer, price, who it's for]
Who we serve: [the customer, in one line]
This month: [the one priority]
Voice: [plain, direct, the words you never use]

# Where things live
Clients: clients/, one file per client
Money: money/, invoices and subscriptions
Decisions: decisions/, dated, with the reason

# Rules for any agent working here
- Read the files a task needs. Ask before creating folders.
- Never send, publish or delete anything without asking me.
- Client files are confidential. Don't quote them outside this folder.

Add a second AGENTS.md in a subfolder when that part of the work has its own rules, such as clients/acme-corp/AGENTS.md with the terms of that engagement. Because the nearest file wins, an agent working there reads it.

What it doesn’t do

It isn’t enforcement. An agent follows the file most of the time, and a long session or a different model can drift past a rule. Anything that must stay private needs a boundary the agent can’t talk its way past (scoping an agent with tags).
It isn’t memory. Agents don’t update it on their own. When a price changes, you change the file.
It isn’t read by chat apps. A chat assistant doesn’t open files on your computer by itself. Add the file to a project there, and replace that copy when the file changes.

AGENTS.md, CLAUDE.md and OKF

They answer different questions. AGENTS.md tells an agent how to behave in a folder. CLAUDE.md is Claude Code’s own name for the same job (a CLAUDE.md for your business). OKF, the open standard for AI-readable markdown, describes each file in the folder: what it is, with its type and tags (what OKF is). Use both, and an agent gets the rules and the map.

Where Oknola fits

The rules file is the easy part. The folder it describes is what drifts: a client moves, a price file goes stale, the invoices pile up in the wrong place. Oknola types, tags and files what lands in the folder, so the paths your AGENTS.md points to stay true while you work, and it hands each agent only the tags you allow. There’s no connector: if a tool can read a folder, it can work on your business. What is available today is on the roadmap.

Questions people ask

Is AGENTS.md only for code?

No. The format is plain markdown with no code-specific fields. It was built for software projects, and a folder that holds a business works the same way.

Do I need both AGENTS.md and CLAUDE.md?

Usually not anymore. Current Claude Code reads AGENTS.md when a folder has no CLAUDE.md. Keep a CLAUDE.md only for Claude-specific notes, and start it with @AGENTS.md so there’s still one source.

How long should it be?

Short enough to read in a minute. Codex stops reading at 32 KiB by default, and every agent loads the file at the start of a session. Link to detail files instead of pasting them in.

Does ChatGPT read AGENTS.md?

Codex, OpenAI’s coding agent, does. The ChatGPT chat app doesn’t read files on your computer by itself, so add the file to a project there instead.