AGENTS.md

AGENTS.md is an open, plain-Markdown file format for giving AI coding agents the instructions they need to work in a repository. The project's own site describes it as "a simple, open format for guiding coding agents" and "a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." A README is written for people deciding whether to use a project. AGENTS.md is written for the agent that has been asked to change it.

What Goes in the File

There is no required schema. The format is ordinary Markdown with whatever headings suit the project, and agents.md lists the sections teams most often include: a project overview, build and test commands, code style guidelines, testing instructions and security considerations. The useful content is whatever a capable newcomer could not infer from the code: the command that actually runs the test suite, the directory that must not be edited by hand, the migration step everyone forgets.

Large repositories can place additional files in subdirectories. The stated precedence rule is short: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." That lets a monorepo keep general conventions at the root and package-specific rules next to the code they govern.

Origin and Adoption

The format grew out of a practical nuisance. Each coding tool had introduced its own instruction file, and teams using more than one agent were maintaining several copies of the same guidance. According to agents.md, the format "emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory"; the Linux Foundation credits its release to OpenAI in August 2025.

In December 2025 AGENTS.md became one of the founding projects of the Agentic AI Foundation under the Linux Foundation, alongside the Model Context Protocol and Block's goose. The foundation's announcement put adoption at more than 60,000 open-source projects and agent frameworks, and agents.md still cites "over 60k" (checked October 2026). Both are project-reported figures and neither has been updated in step with the format's growth, so they are better read as a floor. The site lists more than two dozen supporting tools, among them Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, Jules, Devin, Zed, Aider, goose and JetBrains Junie.

AGENTS.md and CLAUDE.md

CLAUDE.md is the equivalent file for Claude Code, and it predates the shared format. The two now interoperate. Anthropic's documentation states that Claude Code "can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting." By default Claude Code reads AGENTS.md only when no CLAUDE.md is present in the working directory or above it; a setting makes it read both, and a CLAUDE.md can import AGENTS.md so that one file serves every tool.

The differences are of scope more than kind. CLAUDE.md belongs to a wider Claude Code system with user-level and organization-level files, local overrides and path-scoped rules, while AGENTS.md is deliberately minimal and tool-neutral. A reasonable pattern for teams using several agents is to keep shared, tool-agnostic guidance in AGENTS.md and reserve CLAUDE.md for the Claude-specific remainder. The advice in How to Write a CLAUDE.md applies to both: short, specific, and maintained.

AGENTS.md and llms.txt

The two files are often confused because both are Markdown briefings for machines, but they face in opposite directions. AGENTS.md lives in a repository and addresses an agent working on that code. llms.txt lives at a website's root and addresses an agent trying to use what the site documents. A developer-tool company typically needs both: AGENTS.md in its own repositories for contributors' agents, and llms.txt on its documentation for its customers' agents. Together with SKILL.md they form the context layer of agent experience.

Limits

AGENTS.md is advisory. Agents treat it as context, not as enforced policy, so it cannot substitute for permissions, CI checks or code review. It is also loaded into the context window on every run, which makes length a cost, and a stale file misleads with full confidence. Because any text an agent reads can steer it, instruction files in third-party repositories are also a prompt injection surface worth reviewing before an agent is let loose in unfamiliar code. Public evidence on how much a good AGENTS.md improves agent output is limited to anecdote and vendor guidance.