AGENTS.md

Citation review, September 23, 2026: dropped the ~96,600 root-level file count in favor of the official site's "over 60K open-source projects" (path:AGENTS.md NOT is:fork NOT is:archived; June 2026 copy still current). Last push is September 10, 2026 (Technical Charter), not March. Repo stars 24.6K as of September 2026. The arXiv 2602.11988v2 paper does not validate market claims. September 16 corrections to the study summary and Gemini CLI configuration remain.

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^[1], it has rapidly become the de facto way to help AI assistants understand and work effectively within a codebase. The official site cites "over 60K open-source projects" via path:AGENTS.md NOT is:fork NOT is:archived (that June 2026 site copy was still current on September 23, 2026).^[2] The reference repo (agentsmd/agents.md, moved from the OpenAI org) has 24.6K stars as of September 2026, with its last push on September 10, 2026 adding a Technical Charter — the format is not frozen.^[3] There is still no official linter or schema.

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:^[2]

# 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^[2]

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 a vendor-listed roster of coding agents since August 2025; support depth varies:

The format's simplicity—plain Markdown with no proprietary extensions—makes it easy for any tool to parse and respect. Depth of support varies across the vendor-listed roster. On adoption volume: the official agents.md site cites "over 60K open-source projects" via path:AGENTS.md NOT is:fork NOT is:archived; that June 2026 site copy was still current on September 23, 2026.^[2]

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^[1]

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.^[4] 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):^[2]

{ "context": { "fileName": "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 the official site's "over 60K open-source projects" (path:AGENTS.md NOT is:fork NOT is:archived) in its first months; that June 2026 site copy was still the published figure on September 23, 2026.^[2]

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. The ETH Zurich/LogicStar study (arXiv 2602.11988v2) constructed 138 tasks from 5,694 pull requests across 12 repositories. Its revised analysis found no statistically significant accuracy change versus no context file, while LLM-generated files increased inference costs by 20–23% across the two benchmarks. Developer-written files outperformed generated ones; that does not prove a general benefit over no file, and the paper does not validate market-adoption claims. The authors recommend specific instructions beyond what the codebase already reveals.^[5]
• 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 format is not frozen, and there is still no official linter or schema. The June review recorded a March 2026 last push; the live repo last pushed September 10, 2026 (Technical Charter).^[3] Evolution is happening in governance artifacts and in how teams write the files. There is no official 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^[6]

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

"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^[6]

The Bottom Line

Recommended. AGENTS.md is the vendor-listed convention for agent-facing project docs, with a roster of coding agents at varying depth, official-site adoption of over 60K open-source projects, 24.6K reference-repo stars as of September 2026, 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.^[2][3] Tembo is an adjacent consumer of the format for coding-agent sessions, not a steward. Disclosure: Ry Walker is Tembo's co-founder and CEO.^[7]

Outlook: The Markdown convention is safe to bet on, but it is not format-frozen (Technical Charter landed September 10, 2026) and there is still no official linter or schema.^[3] The open question is quality, not presence — arXiv 2602.11988v2 found no accuracy gain and a 20–23% cost increase, so it does not validate market claims; expect the next wave to be unofficial tooling that lints, generates, and evaluates AGENTS.md content.^[5]