Glossary · term

AGENTS.md

AGENTS.md is an open convention for Markdown files that give coding agents repository-specific working instructions. A file can describe build and test commands, code conventions, project structure, review expectations, or constraints that are easy for a human contributor to infer but difficult for an agent to discover. Files may appear at the repository root and in subdirectories, allowing instructions to be scoped to the files an agent is changing. It is guidance, not an executable policy or permission system.

Agents2025-05-16Wave 1 · 2023Maturity: 4/5

Origin and context

OpenAI's May 2025 Codex launch documented AGENTS.md as repository guidance for coding agents, including nested-file precedence. A vendor-neutral project later documented the open format. The Linux Foundation's December announcement describes collaborative origins, adoption by more than 60,000 open-source projects, and transfer to the Agentic AI Foundation. These facts establish an early documented use and meaningful adoption, but not a single-person coinage claim; earlier tool-specific instruction files remain precursors rather than evidence for the exact filename.

Sources: s5, s1, s2

Why it matters

Coding agents repeatedly need the same local knowledge: which checks to run, where generated files belong, what style rules apply, and which operations require caution. Keeping that knowledge in a versioned repository file makes it visible in code review and portable across supporting tools. Nested files can narrow guidance for a package or service. The convention also separates durable project instructions from a one-off user prompt, although an agent still has to resolve conflicts and respect higher-priority system or user instructions.

Sources: s1, s2, s5

Example

A monorepo can place one AGENTS.md at its root with the standard install command and pull-request checks, then add another inside a payments package requiring a focused test suite and prohibiting edits to generated ledger fixtures. A coding agent working in that package reads both applicable files before changing code. The files communicate workflow expectations; they do not themselves grant database access, approve a release, or prove that the resulting patch is safe.

Sources: s1, s5

How it differs

llms.txt

AGENTS.md addresses agents operating in a software repository and can be scoped by directory. llms.txt is a proposed website-root document that summarizes public web content and points to useful pages for language-model consumers. One guides repository work; the other indexes web documentation. Neither is a replacement for robots.txt, authentication, or authorization.

Maturity and evidence

Maturity is rated 4 because the convention has a stable filename and documented scope, is supported across several coding-agent tools, has substantial public-repository adoption, and now has neutral foundation governance. The rating describes ecosystem maturity, not proven effectiveness. A controlled 2026 preprint found that repository-level agent instruction files did not generally improve task success and increased inference cost in its tested settings.

Sources: s1, s2, s3

Limits and open questions

Instructions can be stale, contradictory, or overly broad. An agent may follow them without gaining useful repository understanding, and extra text consumes context and inference. A controlled 2026 preprint reported no general performance gain from the tested instruction files and more than 20% higher inference cost on average. Teams should keep guidance concise, review it like code, and state verifiable commands. AGENTS.md communicates instructions; it does not itself enforce permissions or guarantee compliance.

Sources: s1, s3

References

AGENTS.mdAGENTS.md Project · 2025-12-10 · class A
Linux Foundation Announces the Formation of the Agentic AI FoundationLinux Foundation · 2025-12-09 · class A
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?arXiv · 2026-02-12 · class B
The /llms.txt file, v2llms.txt Project · 2024-09-03 · class A
Introducing CodexOpenAI · 2025-05-16 · class A

Last updated: 2026-09-04

In the Skills Atlas

This term is also covered in the Skills Atlas as ai assisted development skill.