What is AGENTS.md? Instructions for coding agents

Also called agents.md, AGENTS.md file

Definition

AGENTS.md is an open format for a plain Markdown file, placed at a repository's root and optionally in subdirectories, that gives AI coding agents project instructions such as build commands, test commands, and conventions.

AGENTS.md is an open format for a plain Markdown file that tells AI coding agents how to work in a repository. The agents.md site describes it as a README for agents: the README serves human contributors, and AGENTS.md holds the extra detail an agent needs, such as setup commands, test commands, code style, and pull request rules. OpenAI released the format in August 2025. In December 2025 the Linux Foundation's Agentic AI Foundation took it on as a founding project, alongside the Model Context Protocol and Block's goose.

How AGENTS.md works#

AGENTS.md works as standing context. At the start of a session, a supporting agent loads the repository's AGENTS.md into its context, and tools that support nesting also load files from subdirectories on the way to the working directory. The format has no required fields or schema; the agent treats any Markdown in it as instructions, not enforced configuration.

A monorepo can put an AGENTS.md in each package. The agents.md guidance is that the file closest to the code being edited takes precedence, and that explicit instructions in the chat override all of them. Codex shows one concrete implementation: it walks from the project root down to the working directory, takes at most one file per directory, and concatenates them so files nearer the working directory come later. It stops adding files once their combined size reaches a limit, 32 KiB by default.

Every file loaded this way costs tokens in every session, which makes AGENTS.md part of context engineering. It belongs in the stable prefix of a run, next to the system prompt and tool definitions.

AGENTS.md vs CLAUDE.md and other tool-specific files#

AGENTS.md is one shared file for many tools, while CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md started as files for one vendor's tools. Several of those tools now read AGENTS.md as well, so a repository can keep a single instruction file. Defaults differ. Some tools load AGENTS.md automatically, and others need a setting or an import.

Tool Native file How it handles AGENTS.md
OpenAI Codex AGENTS.md Native, with an optional AGENTS.override.md
Claude Code CLAUDE.md Reads AGENTS.md when no CLAUDE.md is present, or both with a setting; a CLAUDE.md can also import it with @AGENTS.md
Gemini CLI GEMINI.md Reads it when context.fileName in settings.json lists it
GitHub Copilot .github/copilot-instructions.md Reads AGENTS.md files, and the nearest one in the directory tree wins; also accepts a root CLAUDE.md or GEMINI.md

The Linux Foundation announcement lists Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules, and VS Code among the tools that support the format, and reports adoption by more than 60,000 open source projects and agent frameworks.

What goes in an AGENTS.md file#

An AGENTS.md file should hold what an agent cannot infer from the code: exact build, test, and lint commands, the directory layout, style conventions, and rules for commits and pull requests. Keep it short, since a supporting agent loads it in every session, and move guidance for one package into that package's own file.

The AI coding agents comparison covers how each agent reads project instructions, and the AI coding tools directory tracks the agents themselves.

Cite this definition

The AI Engineering Editors. "What is AGENTS.md? Instructions for coding agents." The AI Engineering, updated Nov 06, 2026. https://theaiengineering.com/glossary/agents-md

Title
What is AGENTS.md? Instructions for coding agents
Author
The AI Engineering Editors
Publisher
The AI Engineering
Updated
View as Markdown

Part of the AI coding agents hub · Updated