What is AGENTS.md?
AGENTS.md is a markdown file placed in a code repository that gives coding agents project-specific guidance, such as how to build, test and follow the codebase's conventions, and is an open project under the Linux Foundation.
Checked
A README is written for people. AGENTS.md is written for the coding agents that now open pull requests: how to install and run the project, which commands prove a change works, which conventions to follow, and where the deeper documentation lives.
The format is plain markdown with no required schema. Its value comes from being a shared convention, so one file serves several coding agents instead of each tool needing its own.
Where it came from
AGENTS.md originated at OpenAI. On 2025-12-09 the Linux Foundation announced the Agentic AI Foundation (AAIF) with three founding projects: AGENTS.md, Anthropic's Model Context Protocol and Block's goose. The foundation's platinum members include AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft and OpenAI.
Claude Code reads a similar file called CLAUDE.md, which Anthropic's guidance describes as project memory. Some teams keep one file and point the other at it.
What goes in a useful AGENTS.md
Commands that prove a change
Install, build, test, lint and type-check commands, exactly as the agent should run them.
Conventions and hard rules
Naming, structure, banned patterns and anything that must never happen, such as committing from the wrong directory.
A map, not a manual
Short pointers to where architecture notes, API docs and decisions live, so the agent loads detail only when it needs it.
Current gotchas
Framework versions that differ from what a model was trained on, generated files to leave alone, flaky tests to ignore.
How Motiontic's engineers apply it
On a client repo, Motiontic's engineers write the root file early and keep it short, with links into a docs folder that holds the detail. OpenAI's guidance for its newer models points the same way: keep the file's pointers contextual and replace rigid recipes with higher-level guidance.
The file is reviewed like code. When an agent repeats a mistake, the fix is often a single line added to AGENTS.md or a check added to the test suite.
AGENTS.md compared with a README and an Agent Skill
| README | AGENTS.md | Agent Skill (SKILL.md) | |
|---|---|---|---|
| Written for | People | Coding agents | Any agent that supports skills |
| Loaded | When someone opens it | At the start of a session in the repo | Name and description first, full body on demand |
| Holds | Overview and setup | Project rules, commands and pointers | A reusable procedure, often with scripts |
| Scope | One project | One repo or folder | Portable across projects |
Common questions
What is AGENTS.md used for?
AGENTS.md tells coding agents how to work in a specific repository: which commands to run, which conventions to follow and where the detailed documentation lives, so agent-written changes match the project.
Who maintains the AGENTS.md standard?
AGENTS.md is one of the founding projects of the Agentic AI Foundation, a directed fund under the Linux Foundation announced on 2025-12-09, alongside the Model Context Protocol and goose.
What is the difference between AGENTS.md and CLAUDE.md?
Both are root instruction files for coding agents. AGENTS.md is the cross-tool convention under the Linux Foundation; CLAUDE.md is the file Claude Code reads as project memory. Many repos keep one and reference it from the other.
How long should an AGENTS.md file be?
Short enough to read in full every session. Guidance from the labs favours a brief map of commands, rules and pointers, with longer procedures moved into linked docs or skills.
Related
Harness engineering
Designing the environment an agent works in, so its output can be checked and shipped.
Context engineering
Curating everything in the model's view, not just the wording of the prompt.
Skills vs MCP
Connectivity to systems, compared with packaged expertise the agent loads on demand.
Claude Code vs Cursor
Anthropic's coding agent and the SpaceX-owned AI editor compared on plans, models and agent tooling.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.