AGENTS.md: The Plain-Text File That Became the 'README for Agents'
Every repo has a README, a note for the humans who land on it. Over the past couple of years a second file has started appearing beside it: AGENTS.md, a note meant for coding agents. It tells an agent how the project really works before the agent starts poking around. It looks almost comically humble for something so important — a plain markdown file with project paths, testing commands, and style rules scribbled in. But in 2025 it went from a handy convention to an industry format, and it now sits under the same neutral governance that stewards the Linux kernel.
What it is
Think of AGENTS.md as a README for agents. The official site puts it plainly: a dedicated, predictable place to give AI coding agents the context and instructions they need to work on your project. READMEs tell people what the software is; AGENTS.md tells the tool how to build, run, and check it.
A good one is short and index-like. It points at the right commands instead of dumping a hundred lines of lore. For example: "Run pnpm install --filter <package> to add a package so Vite and TypeScript can see it," or "Always run pnpm lint and pnpm test before committing." Different models have different habits, so the file stays a living document — a compact contract between your team and whatever agent walks in.
It's also portable. Because it's a plain file in the repo, it travels with the code, works across every major coding agent, and survives whatever tool is fashionable next year. That portability is exactly why it standardized so fast.
How it got formalized
The format grew out of OpenAI's Codex and shipped with their tools, and it spread because it was useful and cost nothing to adopt. In 2025, OpenAI contributed AGENTS.md to a steadier home.
That home is the Agentic AI Foundation (AAIF), a Linux Foundation project announced on December 9, 2025. Its founding contributions were three pieces of the agent stack that had been drifting between companies: Anthropic's Model Context Protocol (MCP), Block's goose, and OpenAI's AGENTS.md. MCP is the protocol that connects models to tools and data — the "USB-C for AI," with more than 10,000 published servers — and goose is Block's open-source, local-first agent framework that runs on MCP. Bringing all three under one roof meant no single vendor controlled the plumbing your agents depend on.
The member list reads like a who's who of infrastructure: IBM, Cisco, Docker, Salesforce, SAP, Shopify, Snowflake, and others signed on as Gold members, with Hugging Face, Zapier, and more in the Silver tier.
Why it matters now
Nobody would have predicted in 2023 that the future of agent infrastructure would run on a markdown file and a protocol nobody had heard of. But the pattern is familiar — the internet runs on plain text because plain text never locks you in. AGENTS.md gives your team a way to pass down context that doesn't depend on any vendor's tool, and it's now maintained by a foundation with the same neutral track record as the kernel. If you haven't added one to your repo yet, it's a ten-minute task that pays off every time an agent touches your code.