---
title: "What is AGENTS.md? Instructions for coding agents"
description: "AGENTS.md is an open Markdown format that gives AI coding agents project instructions such as build and test commands. See which tools read it and vs CLAUDE.md."
type: "glossary-term"
canonical_url: "https://theaiengineering.com/glossary/agents-md"
markdown_url: "https://theaiengineering.com/glossary/agents-md.md"
topic: "AI coding agents"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
updated: "2026-11-06"
keywords: ["AGENTS.md","agents.md","AGENTS.md file"]
citation: "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"
---

# What is AGENTS.md? Instructions for coding agents

Also called agents.md, AGENTS.md file.

> **Definition of AGENTS.md:** 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](https://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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) took it on as a founding project, alongside the [Model Context Protocol](https://theaiengineering.com/glossary/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](https://learn.chatgpt.com/docs/agent-configuration/agents-md) 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](https://theaiengineering.com/glossary/context-engineering). It belongs in the stable prefix of a run, next to the [system prompt](https://theaiengineering.com/glossary/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](https://code.claude.com/docs/en/memory) 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](https://theaiengineering.com/articles/ai-coding-agents) covers how each agent reads project instructions, and the [AI coding tools directory](https://theaiengineering.com/platforms/ai-coding-tools) tracks the agents themselves.

## Related terms

- [Context engineering](https://theaiengineering.com/glossary/context-engineering): Context engineering is the practice of selecting, structuring, and pruning all the information placed in an LLM's context window at each step, including instructions, retrieved data, tool results, and memory.
- [System prompt](https://theaiengineering.com/glossary/system-prompt): A system prompt is the set of developer-written instructions sent to a language model ahead of the conversation, defining its role, rules, output format, and tool use for every turn that follows.
- [Context window](https://theaiengineering.com/glossary/context-window): A context window is the maximum number of tokens a language model can take into account in a single request, including the system prompt, conversation history, tool results, and the generated output.
- [Prompt engineering](https://theaiengineering.com/glossary/prompt-engineering): Prompt engineering is the practice of designing the instructions, examples, and formatting given to a large language model so it produces accurate, consistent output for a task, without changing model weights.
- [Agentic AI](https://theaiengineering.com/glossary/agentic-ai): Agentic AI is the class of AI systems that pursue a goal through multiple steps, using a language model to plan, call tools, and act on the results with limited human input.
- [Model Context Protocol (MCP)](https://theaiengineering.com/glossary/model-context-protocol): Model Context Protocol (MCP) is an open protocol, introduced by Anthropic in November 2024, that standardizes how AI applications connect to external tools, data sources, and prompts through MCP servers.

## Guides that cover agents.md

- [AI coding agents: how they work and how the major tools compare](https://theaiengineering.com/articles/ai-coding-agents): AI coding agents compared: how they differ from autocomplete, the four main categories, a comparison table of major tools, and how to evaluate and secure them.
- [What is context engineering? A practical guide for AI agents](https://theaiengineering.com/articles/context-engineering): Context engineering is the practice of choosing what fills an LLM context window. Learn its components, why context rot happens, and how to measure results.
- [What is the Model Context Protocol (MCP)? How it works](https://theaiengineering.com/articles/what-is-model-context-protocol): The Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data. Learn its architecture, transports, tool calls, and security.
- [Claude Code vs Cursor: how the two coding agents differ](https://theaiengineering.com/articles/claude-code-vs-cursor): Claude Code vs Cursor compared: terminal agent vs AI editor, models, subagents, hooks, rules files, code review, CI use, pricing, and enterprise controls.

Part of the [AI coding agents](https://theaiengineering.com/topics/ai-coding) topic hub.

## 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: 2026-11-06
- URL: https://theaiengineering.com/glossary/agents-md
- Markdown: https://theaiengineering.com/glossary/agents-md.md
