AGENTS.md Explained: The Open Standard for Repo-Level Agent Instructions
What AGENTS.md is, why OpenAI created it, how it differs from SKILL.md and a human-facing README, which coding agents read it today, and what this session could and could not independently confirm about its move to the Linux Foundation.
AGENTS.md is an open, plain-Markdown convention for giving coding agents the repo-level context a human contributor would otherwise pick up from tribal knowledge — how to build the project, how to run its tests, which style rules apply, and which files or areas are off-limits. It lives in a single, predictable file (typically the repository root) rather than being buried inside a human-oriented README, so an agent doesn't have to guess. OpenAI created and open-sourced the format; the reference repository (openai/agents.md, MIT-licensed, copyright 2025) describes it simply as "a README for agents."
Key facts
- AGENTS.md is one Markdown file with no required schema and no mandated section list — confirmed directly from the format's own reference repository, which ships exactly one illustrative example (not a template) and states the format's only real constraint is being Markdown at a predictable location.
- The reference repository's own root-level
AGENTS.mdfile is itself a working example: it tells an agent not to runnpm run buildduring interactive sessions (because that disables hot-reload), to prefernpm run dev, and lists lint/test commands in a table — exactly the "build/test/style/boundary" content this format exists to carry. - The convention originated in 2025 (confirmed by the reference repository's MIT license copyright year); a specific August 2025 launch month and design input from Google, Cursor, and Factory are carried over from prior secondary reporting supplied for this task and were not independently re-confirmed this session — see Verified sources.
- Secondary reporting supplied for this task puts native AGENTS.md support at 20-30+ coding tools (Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Devin, Amp, Jules, Claude Code among others) and adoption above 60,000 repositories. This session could not independently verify either figure — every outlet and tool-docs page that would confirm them was unreachable (see Verified sources) — so treat both numbers as unverified pending a future cycle with broader network access.
- Do not assume a nested or per-directory override mechanism (e.g. a
packages/foo/AGENTS.mdtaking precedence over a root one) — this session found no independent corroboration for that specific claim in the format's own docs, so it is deliberately omitted here rather than asserted.
What goes in one (by example, not by rule)
The reference repository's sample AGENTS.md uses three sections — "Dev environment tips" (setup/workspace commands), "Testing instructions" (how to run the suite, where CI config lives), and "PR instructions" (title format, pre-commit checks) — but nothing enforces those names, that order, or even having three sections at all. A minimal, valid AGENTS.md is any Markdown file at the repository root; teams add, rename, or drop sections to fit their own project.
How this differs from Agent Skills (SKILL.md)
AGENTS.md and SKILL.md are not competing standards — they solve different problems and compose cleanly. AGENTS.md is repo-level context: one file per repository describing how to build, test, and work in that specific codebase, closer in spirit to a CONTRIBUTING.md aimed at an agent instead of a human. SKILL.md (see /resources/agent-skills-explained) is a portable, filesystem-based capability format — a directory of procedural instructions plus optional bundled scripts that a host loads into context only when a task triggers it, via Anthropic's three-level progressive-disclosure model, and that travels with the agent across repositories rather than living inside one. Put simply: AGENTS.md tells an agent about the repository it's currently in; a Skill teaches an agent how to do a general task it can carry anywhere. A single project can ship both — an AGENTS.md build/test rule and a bundled Skill are read through entirely separate mechanisms with no conflict.
Governance: the claimed move to the Linux Foundation
This task's brief stated that on 2025-12-09 the Linux Foundation announced a new "Agentic AI Foundation" (AAIF), absorbing AGENTS.md, the Model Context Protocol, and Block's goose as founding donated projects, with platinum members including AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI. Re-checking that claim this session: direct fetches of linuxfoundation.org, agents.md, openai.com, and anthropic.com, plus every general news outlet attempted (TechCrunch, InfoQ, SD Times, CIO Dive) and every search engine tried (Google, Bing, DuckDuckGo), all returned proxy-level 403s in this sandbox — the same class of sandbox-wide network restriction already documented elsewhere in this corpus for hosts like huggingface.co and anthropic.com. So the exact December 2025 date and the platinum-member list could not be independently confirmed this session; treat those specifics as carried over from the task brief, not verified here. What is independently confirmable by fetching the named projects' own repositories: Block's goose repository README (fetched directly) states in its own banner that "This project has moved from block/goose to the Agentic AI Foundation (AAIF) at the Linux Foundation," which directly corroborates goose's donation and the AAIF/Linux-Foundation link. The Model Context Protocol repository's GOVERNANCE.md (fetched directly) states the project "has been established... as a Series of LF Projects, LLC" — Linux Foundation's standard vehicle for hosting open-source projects — though that file does not use the name "Agentic AI Foundation" specifically, so it corroborates Linux Foundation stewardship of MCP without confirming the AAIF branding by itself. By contrast, the openai/agents.md repository's own README, LICENSE, and package.json (all fetched directly) show no equivalent Linux-Foundation or AAIF banner as of this fetch — so AGENTS.md's own specific inclusion in AAIF is not confirmed by the project's own docs in this session, only by the secondary reporting supplied for this task. This is a genuine, disclosed gap, not a confirmed correction: it may simply mean OpenAI structured its contribution differently than Block did (e.g., governance/trademark only, no repository move), or that the project's docs hadn't been updated as of this fetch.
Verified sources
openai/agents.mdrepository — README.md, AGENTS.md, LICENSE, package.json (fetched directly via raw.githubusercontent.com): https://github.com/openai/agents.md — confirms the open-format description, the "README for agents" framing, the illustrative (not mandatory) example sections, MIT license, and 2025 copyright year.- agents.md website, referenced by the repository above as its hosted explainer (not independently fetched — proxy returned a 403 "host not in allowlist" response for agents.md in this sandbox): https://agents.md
- Block
gooserepository README (fetched directly via raw.githubusercontent.com): https://github.com/block/goose — primary confirmation that goose moved to the Agentic AI Foundation (AAIF) at the Linux Foundation. - Model Context Protocol repository
GOVERNANCE.md(fetched directly via raw.githubusercontent.com): https://github.com/modelcontextprotocol/modelcontextprotocol — confirms MCP is established as a Series of LF Projects, LLC (Linux Foundation); does not itself name "Agentic AI Foundation." - Linux Foundation press coverage of the Agentic AI Foundation's formation, and OpenAI/ Anthropic's own posts about it (existence asserted by the task brief; not independently fetched — linuxfoundation.org, openai.com, and anthropic.com all returned proxy-level 403s in this sandbox): https://www.linuxfoundation.org/
- General press coverage of AGENTS.md adoption and tool support (TechCrunch, InfoQ, SD Times, CIO Dive) — existence asserted by the task brief; not independently fetched (all four outlets, plus Google/Bing/DuckDuckGo search, returned proxy-level 403s in this sandbox this session).
- See also: /resources/agent-skills-explained, /resources/mcp-primitives, /resources/building-mcp-servers, /resources/llms-txt-explained