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). An August 2025 launch and design input from Google, Cursor, Factory, and Sourcegraph are now WebSearch-corroborated by multiple independently agreeing outlets found this session (including Factory's own announcement post) — still not independently fetched, since factory.ai and the other named outlets stayed proxy-blocked in this sandbox; see Verified sources.
- 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 are now WebSearch-corroborated by multiple independently agreeing outlets found this session. No single primary count (an AAIF-published figure or a GitHub code-search total) was directly fetched, since every candidate host stayed blocked — treat the figure as directionally credible, not an exact count.
- The reference repository itself still defines no nested/per-directory precedence rule (re-confirmed this session via a direct fetch of its files). Separately, tool-specific docs found via WebSearch this session describe a nearest-file-wins rule for at least one major implementation (OpenAI Codex): when a repo has AGENTS.md files at multiple directory depths, the most-deeply-nested one closest to the edited file takes precedence over the root file. That is tool behavior layered on top of the format, not something the AGENTS.md spec itself mandates — WebSearch-corroborated only, since developers.openai.com stayed blocked.
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 move to the Linux Foundation
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. This session re-checked the claim: direct fetches of linuxfoundation.org, agents.md, aaif.io, openai.com, siliconangle.com, and infoq.com all returned proxy-level blocks in this sandbox, the same class of restriction already documented elsewhere in this corpus. WebSearch, however, now returns the exact same date, founding-project list, and platinum-member list from multiple independently agreeing sources (the Linux Foundation's own press release, OpenAI's own post titled "OpenAI co-founds the Agentic AI Foundation," Block's own post titled "Block, Anthropic, and OpenAI Launch the Agentic AI Foundation," plus SiliconANGLE and InfoQ) — this is the same WebSearch-corroborated confidence level this corpus's /resources/mcp-vs-a2a and /resources/nlweb-explained entries already apply to this identical fact, so this page is now brought into line with them rather than remaining an outlier. 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. 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. By contrast, the openai/agents.md repository's own README, LICENSE, and package.json (re-fetched directly this session) still show no equivalent Linux-Foundation or AAIF banner — so AGENTS.md's own specific inclusion in AAIF remains unconfirmed by the project's own repository even eight months after the announcement, corroborated only by the secondary reporting above (including Block's own post naming OpenAI as a co-launcher). This is a genuine, disclosed gap, not a contradiction: 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 haven't been updated to reflect it.
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 release on the Agentic AI Foundation's formation — WebSearch-corroborated only this session (direct fetch proxy-blocked): https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
- OpenAI's own post, "OpenAI co-founds the Agentic AI Foundation under the Linux Foundation" — WebSearch-corroborated only this session (direct fetch proxy-blocked): https://openai.com/index/agentic-ai-foundation/
- Block's own post, "Block, Anthropic, and OpenAI Launch the Agentic AI Foundation" — WebSearch-corroborated only this session (direct fetch proxy-blocked): https://block.xyz/inside/block-anthropic-and-openai-launch-the-agentic-ai-foundation
- SiliconANGLE and InfoQ coverage of the AAIF launch, and Factory's own post on joining the AGENTS.md collaboration — WebSearch-corroborated only this session (direct fetch proxy-blocked for all three): https://siliconangle.com/2025/12/09/linux-foundation-announces-agentic-ai-foundation-joined-anthropic-openai-block/, https://www.infoq.com/news/2025/12/agentic-ai-foundation/, https://factory.ai/news/agents-md
- General press/blog coverage of AGENTS.md adoption figures (60,000+ repositories, 20-30+ tools) and the Codex nearest-file-wins nested-precedence behavior — WebSearch-corroborated by multiple independently agreeing outlets this session; the presumed primary source, https://developers.openai.com/codex/guides/agents-md, was proxy-blocked to direct WebFetch.
- See also: /resources/agent-skills-explained, /resources/mcp-primitives, /resources/building-mcp-servers, /resources/llms-txt-explained, /resources/mcp-vs-a2a