AGENTS.md

AGENTS.md is "a simple, open format for guiding coding agents" — a markdown file in a repo holding "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions," keeping READMEs human-focused. It's the context-standard counterpart to the capability-standard agentskills-spec: where skills package what an agent can do, AGENTS.md packages what it needs to know about this project. Source: agents.md.

Why it matters here

Cross-tool convergence (the real signal): "over 60k open-source projects," read by *OpenAI Codex, Google Jules, Aider, goose, VS Code, Devin, GitHub Copilot, JetBrains Junie, Cursor, Zed, Warp" and ~20 more — now stewarded by the Agentic AI Foundation (Linux Foundation). This is the same open-standard-as-industry-attractor pattern the synthesis tracks for agentskills-spec, but for project context rather than capability.
It's the generalized, vendor-neutral sibling of tool-specific memory files (e.g. CLAUDE.md), and the reviewable-context substrate that spec-driven-development and agent-guardrails (the AGENTS.md contract in agents-never-do-alone) build on.

Why it won, per a competitor (2026-08-23)

attention-is-all-you-have gives the adoption above a mechanism, and it is not flattering to the alternatives: teams paste their workflows into AGENTS.md because it is "always loaded, zero setup, no trigger lottery" — "the crudest mechanism wins on the only axis users feel — simplicity." On that reading this file's 60k projects are partly a defection from the skills-install channel rather than a preference for the format, and the paper treats it as the bar any successor has to clear: won on delivery, not on design.

Worth holding beside context-files-ablation-paper, which measured no correctness effect from this file on either of two frontier agents. Together the two make an uncomfortable pair — the convention that won on ease of delivery is also the one that has failed its only controlled test — and neither result touches the other. Note also what the paper concedes on its own side: AGENTS.md is resident context, so it pays exactly the distance decay (context-rot) the paper builds its case on.

A generator that takes the hub-and-spoke reading (2026-09-01)

vibe-coding-prompt-template writes this file and the vendor files in one step, and states the relationship between them as a rule: keep AGENTS.md as the cross-tool source of truth, then add .cursor/rules/, .claude/agents/, .codex/config.toml, .agents/skills/ or GEMINI.md "only as concise tool-specific adapters." Same instruction for MEMORY.md against tool-side memory: the tool's is personal, the repo's is the one under version control.

That is a position on where the substance lives, not just which file exists — and it is the reading the standard's adoption numbers imply but never spell out. One template does not make it the consensus; it is the first source here that generates both halves and says which one is authoritative.

What the spec actually says

Per agents-md-spec (the format's own site), it's plain Markdown with flexible headings, suggesting — not mandating — sections for project overview, build/test commands, code style, testing, security, commit/PR guidelines, and deployment. The role split with the README is deliberate: the README serves humans, AGENTS.md holds the "extra, sometimes detailed context coding agents need."

The mechanism that makes it work across a large codebase is the nearest-file rule — "agents automatically read the nearest file in the directory tree, so the closest one takes precedence." So context composes hierarchically: a repo-root file sets defaults, subproject files override locally. OpenAI's main repository carries 88 nested AGENTS.md files agents-md-spec, the clearest evidence the convention scales to monorepos rather than degrading into one bloated file.

Does it work? The first controlled test says no (added 2026-08-03)

Everything above documents adoption — 60k projects, 30-odd tools, a Linux Foundation steward. None of it is evidence that the files improve what agents produce, and this wiki carried the convention for two months without any.

context-files-ablation-paper supplies the first controlled measurement, and it is a null. Across two frontier agents (Claude Code sonnet-4-6, Codex CLI gpt-5.5), 17 tasks mined from merged PRs in 3 Python repositories, and 288 gold-test-evaluated runs, context-injection strategy does not measurably move correctness — every Claude pairwise difference ≤2.3pp, bounded to ≤10pp (Claude) and ≤15pp (Codex). Deleting the AGENTS.md entirely scored 53.3% for Claude against 55.6% with it always in the system prompt. On the borderline tasks picked to have room to move, the no-context arm scored higher (58% vs 42%).

The mechanism matters more than the number. A triage of near-miss failures found the agents losing on implementation skill — feature design, pattern selection, exact wiring — and not on repository knowledge a context file could supply. A pre-registered probe re-ran the two convention-closest near-misses on both agents across 36 cells: the real, unmodified AGENTS.md never converts a near-miss to a pass on either agent. The author's phrasing is careful — the manipulation is not inert, it "simply does not supply the implementation skill that gates these tasks."

What did move was process, not outcome. On the one repository whose file warns that the test suite takes over 20 minutes, Claude's blind full-suite pytest runs fell monotonically with more context (3.67 → 2.44 → 1.67 per cell) and wall-clock time with them. That saving came from a single warning about a cost the agent could not observe for itself — not from the conventions, style guides or architectural notes that make up most of a real AGENTS.md.

Read narrowly, since the study is small (MDE >30pp; a 10pp effect would need 120–200 tasks), Python-only, and a snapshot of two model versions. What it establishes is a bounded null with a mechanism, which is enough to stop treating adoption as evidence of effect. See synthesis for how it sits against the spoke's other measured results.

agents-md-spec · agentskills-spec · agent-skills · spec-driven-development · agent-guardrails · agents-never-do-alone · claude-agent-sdk · context-files-ablation-paper · agent-specific-task-difficulty · agent-evals · context-driven-development