Where the standard lives
The home of AGENTS.md is agents.md, and its
repository is
agentsmd/agents.md
(MIT). It was released by OpenAI in August 2025 and donated to the
Agentic AI Foundation — announced by the Linux Foundation on
9 December 2025 — where it now sits alongside the Model Context Protocol and
goose.
This page is not that standard and does not speak for it. Nothing here amends AGENTS.md, and if the wording below ever disagrees with agents.md, agents.md is right.
What AGENTS.md is, in its own words
“AGENTS.md is a simple, open format for guiding coding agents.” The site puts it another way: “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.”
It is plain markdown with no required fields. Its own FAQ is explicit: “Are there required fields? No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.” Headings like Build and test commands or Code style guidelines are offered as popular choices, not as structure you owe anyone.
The file goes at the root of a repository. In a monorepo, packages carry their own; agents read the nearest one in the directory tree, so the closest file takes precedence — and an explicit instruction in the chat overrides all of them.
It is honest to call AGENTS.md a format or a convention — those are the words its own materials use. It has no version number, no RFC-2119 conformance language and no separate specification document, and calling it a “spec at version n” would be inventing something that does not exist.
What this profile adds
Three keys of frontmatter — the same three the rest of this register uses.
---
$id: https://agents.md.org.ai/AGENTS.md
$type: TechArticle
$context: https://schema.org.ai
---| Key | What it says |
|---|---|
$id | The file's own address — the URL another document cites when it means this file. |
$type | What the file is, named in a vocabulary that already has a word for it. |
$context | Where that vocabulary lives. Always https://schema.org.ai here. |
TechArticle is
an existing type —
“a technical article … how-to topics, procedural troubleshooting,
specifications” — and it is the nearest one the vocabulary already has
for a file of build commands, conventions and house rules. It is a
near fit rather than an exact one, and we would rather say so than
coin AgentInstructions and hand every reader a word only this
register knows.
Frontmatter is inert to a markdown renderer: GitHub, a static-site generator and a terminal pager all skip it. A file that carries these three keys is still an ordinary file of its kind for every tool that has never heard of this register — which is the only reason it is safe to add them.
Conformance
Any plain AGENTS.md remains valid. A file with no frontmatter at all is a correct AGENTS.md, was before this page existed and still is. This profile is additive and optional: it adds three keys that a markdown renderer skips and that no agent needs in order to read the instructions underneath.
Nothing here removes a heading, requires a section, changes precedence between nested files, or asks an agent to behave differently. A tool that implements AGENTS.md and ignores this page entirely is fully correct. Conversely, this profile cannot make a file conformant that AGENTS.md itself would not — there is no conformance test here, and this host issues no verdicts.
The canonical example
/AGENTS.md is served from this host as
text/markdown: a real AGENTS.md for a real repository — this
one — carrying the frontmatter. The bytes below are that file.
---
$id: https://agents.md.org.ai/AGENTS.md
$type: TechArticle
$context: https://schema.org.ai
---
# AGENTS.md
The canonical example of an `AGENTS.md` carrying MDXLD frontmatter. Everything
below this line is an ordinary AGENTS.md, written the way agents.md describes
it: plain Markdown, no required fields, headings of the author's choosing.
Everything above it is the whole of what this profile adds.
## Project overview
`md.org.ai` is a static site served by one Cloudflare Worker across three
hosts. There is no database, no API and no build step beyond `node build.js`.
## Build and test commands
```sh
npm install
npm run build # → public/
npm run dev # wrangler dev
npm run deploy # wrangler deploy
```
`npm run deploy` uses wrangler's saved OAuth login. If `CLOUDFLARE_API_TOKEN`
is set in the environment it shadows that login and the deploy fails with a
10000 authentication error — unset it for the call:
`env -u CLOUDFLARE_API_TOKEN npx wrangler deploy`.
## Code style
- ES modules, no TypeScript, no framework, no bundler.
- The pages fetch nothing from anywhere. No CDN, no web font, no analytics.
If a change would add an external subresource, it is the wrong change.
- Every HTML response carries `text/html; charset=utf-8`, and every document
opens with `<meta charset="utf-8">` as the first element in the head.
## Conventions specific to this repo
- `src/TODO.md` and `src/AGENTS.md` are served verbatim. Edit them as files,
never by generating them from `build.js`.
- Status claims are load-bearing. Do not add a version number, an adoption
figure, or the word "standard" where "convention" is the truth.
## What not to do
- Do not commit `public/`. It is built.
- Do not change `$id` in any frontmatter. Other documents cite it.
Status — read this before citing anything here
The frontmatter profile on this page is our own, written in this estate; AGENTS.md itself is not ours and is not covered by anything said here. It is new. It carries no version number, because there is nothing yet to have changed from, and version numbers on a two-week-old convention are theatre.
No adoption is claimed. No count of implementers is given here, because the honest count is the one we would rather not print. If that changes, this paragraph changes with it.
There is no 1.0 and there will not be one until the shape has survived people other than its authors trying to break it. Until then every page in this register is a proposal published so that it can be broken.