Your AI Agent Reads One Plain Markdown File

The AI-agent industry has standardized on one plain Markdown file. It is called AGENTS.md, and it is where coding agents read the instructions for a project. More than 60,000 open-source projects already use it, and the Linux Foundation now stewards it. No proprietary container, no database — a file you can open in any text editor.

That convergence is the quiet story of 2026. When OpenAI, Google, and a dozen others needed a shared way to tell an agent how a project works, they did not invent a new format — they agreed on Markdown.

The official site puts it plainly: "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project."¹ The interesting part is not the file. It is what the file's format implies for everything else you write down.

What most people assume

Most people assume AGENTS.md is a developer convenience — a config file, like a .gitignore, relevant only to people who ship code. It looks like plumbing. It sounds like plumbing. For the engineer adding one to a repository, that is exactly what it is: a place to tell the agent which commands to run and which mistakes to avoid.

That reading is fair, and it is also incomplete. A config file is usually proprietary to the tool that consumes it — AGENTS.md is not. It was deliberately built to belong to no single vendor. The site's own design note is direct: "Rather than introducing another proprietary file, we chose a name and format that could work for anyone."² That one decision is what turns a convenience into something larger.

Why "just a config file" misses it

The standardization is the point, not the file. AGENTS.md is a cross-vendor interface, not one company's setting. The Linux Foundation says the format "has already been adopted by more than 60,000 open source projects and agent frameworks including Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code."³ One file, read by rival tools.

Released by OpenAI in August 2025, AGENTS.md was described by the Linux Foundation as "a simple, universal standard that gives AI coding agents a consistent source of project-specific guidance needed to operate reliably across different repositories and toolchains."⁴ Within four months it had a neutral steward. On December 9, 2025, the Foundation announced the Agentic AI Foundation, with "founding contributions of three leading projects driving innovation in open source AI; Anthropic's Model Context Protocol (MCP), Block's goose, and OpenAI's AGENTS.md."⁵

Read the platinum backers and the scale becomes hard to dismiss as marketing. They "include Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI."⁶ When eight companies that agree on almost nothing agree on a file format, the format has stopped being a feature and become infrastructure.

How the file actually works

An agent does not run AGENTS.md. It reads it. The file is loaded into the model's context as plain text, the same way a human skims a README before touching a project. OpenAI's Codex documentation states it directly: "Codex reads AGENTS.md files before doing any work... you can start each task with consistent expectations, no matter which repository you open."⁷

This is what makes the format choice load-bearing rather than cosmetic. There is no schema to satisfy and no parser to appease. The official FAQ is blunt: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."⁸

Anthropic's engineering team describes the same mechanism for its own CLAUDE.md files — they "are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time."⁹

The diagram below traces the path from a file you wrote to the work an agent does. The instruction never leaves plain text.

flowchart TB
  A["You write<br/>plain-Markdown<br/>instructions"] --> B["AGENTS.md<br/>sits in the project"]
  B --> C["Agent reads the<br/>file as plain text"]
  C --> D["Text loaded into<br/>the model's context"]
  D --> E["Agent acts with<br/>your guidance"]

How an agent uses AGENTS.md: a plain-Markdown file you author is read as text and loaded into the model's working context before it acts. No proprietary format sits between what you wrote and what the agent does — the same file opens in any editor, today and in ten years.

Nesting is allowed and common. The official site notes that "at time of writing the main OpenAI repo has 88 AGENTS.md files,"¹⁰ one near each part of the codebase, each scoped to its folder. The format scales not by adding machinery but by adding more of the same plain files.

What this means for your own notes

Here is the part that reaches past developers. The agent ecosystem converged on the format your knowledge already uses: plain Markdown that any tool can open and no vendor owns. The instructions your agents now require live in the same file type as the notes you keep. That convergence is a quiet vote for a principle you can apply everywhere.

We have argued before that your notes are already AI-readable. AGENTS.md is the sequel: the format is not merely readable now — it is the interface the industry agreed on.

This is one move in a larger pattern. The instruction file is the configuration layer; the wire protocol agents use to reach your files is a separate convention, and an agent "skill" is itself just a folder of Markdown. Three layers, one substrate. The same plain text underneath all of it is where you can keep your own knowledge as durable AI memory.

The official distinction between the two files makes the parallel exact. "README.md files are for humans: quick starts, project descriptions, and contribution guidelines."¹¹ AGENTS.md is the same content, addressed to a machine reader. Both are plain Markdown. Both outlast the tool that reads them today.

Steph Ango, Obsidian's CEO, made the durability argument years earlier: "File over app is a philosophy: if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read."¹² His one-line version is the whole case: "Apps are ephemeral, but your files have a chance to last."¹³

So the lesson is not "add an AGENTS.md." It is narrower and more durable. The format that won — for the most demanding readers software has produced — is the plain file you can hold in your hand. Your knowledge deserves the same.

The honest caveat: the file is not magic

The file is the standard. It is not a guarantee. A study from ETH Zurich, reported by InfoQ, examined whether context files actually help agents and found the gains are small — and conditional. The researchers concluded that "LLM-generated context files have a marginal negative effect on task success rates, while developer-written ones provide a marginal performance gain."¹⁴

The numbers are modest in both directions. Auto-generated files measured as "reducing the task success rate by an average of 3%,"¹⁵ while a human-written file gave a "4% average increase in task success rate on AGENTbench."¹⁶

The work, by Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, and Martin Vechev, is one study, not a verdict. But its finding points the same way the standard does: the value is in a file a person wrote, not one a machine generated to fill a slot.

That is the strongest possible argument for owning your own files. A standard is only as good as the words you put in it, and the words that work are the ones you authored. The format is shared; the thinking is yours.

Frequently asked questions

These are the questions people actually type when they first meet AGENTS.md — what it is, whether it counts as a standard, how it differs from a README, and whether it earns its keep. The short answers below are drawn from the official site, the Linux Foundation, and an independent study, each cited in full.

What is AGENTS.md?

AGENTS.md is a plain Markdown file that tells AI coding agents how to work on a project — the commands to run, the conventions to follow, the mistakes to avoid. The official site frames it as "a README for agents," a predictable place for the instructions that help agents work on your project.¹ More than 60,000 open-source projects use it.³

Why do AI agents read plain Markdown files for instructions?

Because Markdown is human-readable text that needs no parser, schema, or proprietary tool. The official FAQ states it plainly: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."⁸ The agent loads the file into its context and reads it the way a person reads a README before starting work.⁷

Is AGENTS.md a standard?

Yes. Released by OpenAI in August 2025,⁴ AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation, where it is one of three founding projects alongside Anthropic's Model Context Protocol and Block's goose.⁵ The Foundation calls it "a simple, universal standard."⁴

What is the difference between AGENTS.md and README?

They are the same format with different readers. "README.md files are for humans: quick starts, project descriptions, and contribution guidelines."¹¹ AGENTS.md carries the machine-facing instructions an agent needs. Both are plain Markdown, so both open in any editor and outlive the tool that reads them.

What tools support AGENTS.md?

The Linux Foundation lists adoption "including Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules and VS Code among others."³ The roster spans tools from companies that otherwise compete, which is what makes the convention a cross-vendor interface rather than one product's setting.

Does AGENTS.md actually help AI coding agents?

The gains are real but small, and they depend on who wrote the file. An ETH Zurich study found a human-written file gave a "4% average increase in task success rate,"¹⁶ while an auto-generated one reduced success "by an average of 3%."¹⁵ The file is the agreed-on interface, not magic. A file you author yourself is the part that pays.

Who owns and governs AGENTS.md?

No single company. AGENTS.md was contributed to the Agentic AI Foundation, formed under the Linux Foundation on December 9, 2025.⁵ Its platinum backers "include Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI."⁶ It was built, by design, as "a name and format that could work for anyone."²

The most demanding readers software ever built now agree on one thing: instructions belong in a plain file you can open anywhere. Your knowledge — the notes you keep for yourself — has the same right to live in plain Markdown, on your own device, readable long after today's tools are gone.

If your knowledge deserves the format your agents now require, mnmnote.com keeps your notes as plain Markdown on your own device, working offline, with nothing locked in a vendor's box.