AGENTS.md

What is AGENTS.md?

AGENTS.md is an open standard for providing AI coding agents with project-specific context and instructions. Launched by OpenAI in August 2025 and contributed to the Agentic AI Foundation in December 2025, it has rapidly become the de facto way to help AI assistants understand and work effectively within a codebase. As of June 2026, GitHub code search returns roughly 96,600 root-level AGENTS.md files, and the reference repo (agentsmd/agents.md, moved from the OpenAI org) has 22.1K stars with its last push in March 2026 — the spec itself changes slowly by design.

Think of it as a README for robots: a dedicated, predictable place for the detailed instructions that coding agents need but that would clutter human-facing documentation.

The Problem It Solves

README.md files are designed for humans—quick starts, project descriptions, contribution guidelines. But AI coding agents need different information:

• Build commands: How to install dependencies, run the dev server, build for production
• Testing requirements: Which tests to run before committing, how to focus on specific tests
• Code style: Formatting preferences, naming conventions, architectural patterns
• PR conventions: Title formats, commit message styles, review requirements
• Environment details: Package manager preferences, directory structure, CI/CD setup

Putting all this in a README creates noise for human readers. AGENTS.md gives agents a predictable location for this machine-oriented context.

Standard Format

AGENTS.md is intentionally simple—just standard Markdown with no required schema:

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add the package to your workspace
- Check the name field inside each package's package.json to confirm the right name

## Testing instructions
- Find the CI plan in the .github/workflows folder
- Run `pnpm turbo run test --filter <project_name>` to run tests
- Fix any test or type errors until the whole suite is green
- Add or update tests for the code you change, even if nobody asked

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

Common Sections

While there are no required fields, popular sections include:

• Project overview: Architecture, key concepts, important files
• Setup commands: Install, build, dev server
• Code style guidelines: Formatting, naming, patterns to follow/avoid
• Testing instructions: How to run tests, what coverage is expected
• PR/commit conventions: Title formats, review requirements
• Security considerations: Sensitive areas, what not to modify
• Deployment steps: Production builds, release processes

How It Works

Agents automatically discover and parse AGENTS.md files:

1. Root-level AGENTS.md: Applies to the entire repository
2. Nested AGENTS.md: In subdirectories for package-specific instructions
3. Closest wins: Agents read the nearest file in the directory tree
4. User prompts override: Explicit chat instructions take precedence

For large monorepos (like OpenAI's own repositories with 88+ AGENTS.md files), this hierarchy ensures each subproject gets tailored guidance while sharing repository-wide conventions.

Platform Adoption

AGENTS.md has achieved remarkable adoption since August 2025:

The format's simplicity—plain Markdown with no proprietary extensions—makes it easy for any tool to parse and respect. On adoption volume: the official agents.md site still cites "over 60K open-source projects" (non-fork, non-archived), while a raw GitHub code search for root-level AGENTS.md files returns ~96,600 results as of June 2026.

Governance: Agentic AI Foundation

In December 2025, OpenAI contributed AGENTS.md to the Agentic AI Foundation (AAIF), a directed fund under the Linux Foundation. AGENTS.md was one of three founding projects alongside MCP (contributed by Anthropic) and goose (contributed by Block). The foundation was co-founded by:

• Founding members: OpenAI, Anthropic, Block
• Supporting companies: Google, Microsoft, Amazon, Bloomberg, Cloudflare

Governance has moved from announcement to operation. Per the Linux Foundation's May 18, 2026 press release, AAIF added 43 new members in a single quarter — including Gold members F5, GoDaddy, Stripe, and TRON, plus associate members like Pacific Northwest and Sandia National Laboratories and the U.S. Army — bringing total membership past 180 organizations. The agents.md site now states the standard "is stewarded by the Agentic AI Foundation under the Linux Foundation."

This governance structure ensures:

• Vendor neutrality: No single company controls the standard
• Open evolution: Community input drives development
• Long-term sustainability: Linux Foundation's proven stewardship model
• Portability: Standard works across all tools and platforms

Best Practices

Do

• Keep it actionable: Specific commands over vague guidance
• Include verification steps: How to know if changes work
• Document the unusual: Edge cases, gotchas, non-obvious requirements
• Update as you go: Treat it as living documentation
• Use nested files: Package-specific instructions in monorepos

Don't

• Duplicate the README: Complement, don't repeat
• Include secrets: No API keys, credentials, or sensitive data
• Be too verbose: Agents can follow concise instructions
• Forget to test it: Try asking an agent to follow your AGENTS.md

Migration from Other Formats

If you have existing agent instructions (AGENT.md, CLAUDE.md, .cursorrules):

# Rename and create symlinks for backward compatibility
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Tool-Specific Configuration

Aider (.aider.conf.yml):

read: AGENTS.md

Gemini CLI (.gemini/settings.json):

{ "contextFileName": "AGENTS.md" }

The Ecosystem Effect

AGENTS.md represents a broader shift in how we think about documentation. Just as README.md became foundational for open source, AGENTS.md is becoming foundational for AI-assisted development.

The comparison to early README adoption is apt: a simple convention that started as a practical solution and evolved into an ecosystem standard. The key difference is velocity—AGENTS.md went from 0 to 60,000+ repositories in its first six months, and to roughly 96,600 root-level files on GitHub by June 2026.

This rapid adoption signals that developers want their codebases to be agent-ready, and that a simple, open standard beats proprietary configuration formats every time.

Cautions

• Presence isn't performance. A 2026 ETH Zurich study covering 138 repository instances and 5,694 pull requests found that the most common style of AGENTS.md — README-like restatements of project context — slightly hurt agent performance (2-3%) while raising token costs 20%+. The files that help contain narrow, non-inferable directives: exact build/test commands, gotchas, and verification steps.
• Context is a budget. Every token an agent spends reading boilerplate instructions is a token not spent reasoning about the task. Bloated AGENTS.md files effectively shrink working memory.
• The spec is frozen, the practice isn't. The reference repo's last push was March 2026; evolution is happening in how teams write the files, not in the format itself. There is no linting, validation, or conformance story yet.

What Developers Say

Discussion of the ETH Zurich findings on Hacker News (March 2026) split roughly down the middle:

"It just prevents hallucinations and coerces the AI to use existing files and APIs instead of inventing them." — CrzyLngPwd, Hacker News

"We're authoring them like READMEs for humans when agents actually need narrow, non-inferable directives." — danielmeppiel, Hacker News

"I suspect AGENTS.md files will prove to be a short-lived relic of an era when we had to treat coding agents like junior devs." — nayroclade, Hacker News

The Bottom Line

Recommended. AGENTS.md has won the format war: backing from every major AI lab, adoption by all significant coding agents, ~96,600 files on GitHub, and operating Linux Foundation governance with 180+ AAIF member organizations as of May 2026. If you're building software in 2026, you should have an AGENTS.md file.

Outlook: The standard itself is stable and safe to bet on. The open question is quality, not adoption — empirical work now shows badly written files are worse than none, so expect the next wave to be tooling that lints, generates, and evaluates AGENTS.md content rather than changes to the format.