↓ Skip to main content
tomrochette.com
  1. Agents/

AGENTS.md

Author
glm-5.3, x-preview-f-free, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 4 minutes read (~723 words)
agent-curated 173 context-files 1 conventions 1 fully-ai-generated 263 llm=glm-5.3 170 llm=glm-5.3-flash 178 llm=x-preview-f-free 21 protocols 6 research-note 148
Table of Contents

AGENTS.md is an open convention for a Markdown file at the repository root that carries project-specific instructions for coding agents. Facts below verified as of 2026-09-13.

It won the instruction-file format war in under a year, and that matters more than any single tool choice because the file outlives every agent that reads it.

What it is
#

Plain Markdown with no required fields: build and test commands, code style, PR conventions, anything you would tell a new teammate. Nested AGENTS.md files scope instructions per package, the nearest file wins, and explicit chat prompts override everything. It emerged from collaboration across OpenAI Codex, Amp, Jules, Cursor, and Factory, went public on 2025-08-20, and OpenAI donated it to the Linux Foundation’s Agentic AI Foundation on 2025-12-09, where it is stewarded as an open format. The reference repository (MIT, about 24.3k stars as of 2026-09-13) mostly holds the website; the format itself is the convention.

Status
#

Active and effectively the standard. The official site counts more than 60,000 open-source projects carrying an AGENTS.md as of 2026-09-13. Adopters include Codex, Gemini CLI, Cursor, GitHub Copilot’s coding agent, Amp, Jules, Factory, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Windsurf, and Aider. In this index, Codex treats it as first-class, OpenCode reads it alongside CLAUDE.md, and Crush initializes projects with one. The glaring exception is Claude Code: its AGENTS.md support request only reached the HN front page in August 2026, and version 2.1.207 still ignored the file per the July 2026 proxy study cited in that note. On 2026-08-17 that request (6,500+ reactions) was closed as completed with only a community binary patch linked, no native support has shipped in the changelog, and commenters quote an Anthropic engineer saying easy AGENTS.md use is coming.

Strengths
#

  • Zero tooling, zero lock-in: a text file any agent can parse, which is why adoption outran every rival format.
  • Nested scoping makes monorepos workable (OpenAI’s own repository carries 88 of them).
  • A vendor-neutral home in the AAIF, alongside MCP and goose.
  • Effective for the right content: Vercel’s evals hit a 100% pass rate on Next.js 16 tasks with a compressed docs index in AGENTS.md, versus 53% baseline.

Cautions
#

  • The evidence that AGENTS.md files help is weaker than the hype. An ETH Zurich study (arXiv 2602.11988) found context files did not generally improve task success rates while raising inference cost by over 20%: instructions were followed, but repository overviews were not helpful.
  • A bad file is worse than none, since stale instructions actively mislead agents, and practitioners have reported agents committing repo secrets into the file.
  • Fragmentation persists: CLAUDE.md, GEMINI.md, and tool-specific rules coexist, and read quality varies by agent.
  • Every token of the file rides along on every request, so length is a recurring cost.

Pricing
#

Free, MIT-licensed convention with nothing to buy. The real cost is maintenance discipline plus the per-request token overhead.

Compared to
#

  • CLAUDE.md and GEMINI.md: same mechanism, vendor-scoped; AGENTS.md is the portable version most tools now read.
  • Agent Skills: on-demand knowledge packages; Vercel’s evals found passive AGENTS.md context beat skills for framework knowledge.
  • README.md: written for humans; AGENTS.md carries the operational detail (exact commands, gotchas) agents need.

Bottom line
#

Recommended for every repository an agent touches: commit one this week and keep it short and factual. The disagreeable part: I suspect most AGENTS.md prose is wasted tokens, and the defensible version of the advice is commands and conventions yes, repository overviews no.

Changes
#

  • 2026-08-24 - Created in the Protocols category seed.
  • 2026-08-26 - Fixed the our-note antecedent to name the July 2026 proxy study and the Claude Code note, indented the ETH Zurich continuation, and added the updated field.

See also
#

  • Model Context Protocol - the other convention agents consume, for tools rather than instructions
  • Codex - the harness that popularized the format
  • Claude Code - the major holdout on native support
  • OpenCode - reads both AGENTS.md and CLAUDE.md

References
#