AGENTS.MD FORMAT

AGENTS.md is a plain Markdown file at the root of a repository that tells coding agents how to build, test and change the project. It has no required schema, which is exactly why so many tools can read it.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Is AGENTS.md?

AGENTS.md is a README for coding agents. Where README.md explains a project to people, AGENTS.md tells an agent the things it cannot guess: which package manager you use, the exact command that runs the tests, which directories are generated, and which rules a change must follow.

The format is deliberately plain Markdown. There is no frontmatter, no required heading and no special syntax, so any agent that can read a text file can use it. The agents.md site describes it as an open format used by over 60,000 open-source projects, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.

Which Agents Read AGENTS.md?

Support has grown quickly. Last verified 2026-11-13 against the vendor documentation. The short version:

  • OpenAI Codex reads AGENTS.md before doing any work, from the project root down to the current directory.
  • Cursor supports AGENTS.md in the project root and in subdirectories.
  • GitHub Copilot reads it in the cloud agent, code review, the Copilot CLI and VS Code chat; Copilot Chat on GitHub.com and in Visual Studio does not.
  • Windsurf (whose docs are now published under Devin) treats AGENTS.md as an always-on rule, scoped by directory.
  • Zed, Cline and Jules read it too; Zed uses only the first matching instruction file it finds.
  • Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md, unless you change a setting. Most teams add a CLAUDE.md that imports it.

The full table, with every file and every surface, is on the compatibility page.

Where Does AGENTS.md Live and How Does Nesting Work?

Put the main file at the repository root. Several agents also read AGENTS.md files in subdirectories, so a monorepo can keep one file per package. Codex walks from the project root down to the working directory, checking each directory for AGENTS.override.md, then AGENTS.md, and concatenates what it finds with the closest file last, so deeper files win. Cursor combines nested files with their parents, with the more specific instructions taking precedence.

  1. Keep shared rules in the root AGENTS.md.
  2. Add a nested AGENTS.md only where a package really differs, such as a different test command.
  3. In the nested file, write only the differences. Do not copy the root file.
  4. Use AGENTS.override.md (Codex) for a temporary override instead of editing the shared file.

What Does a Good AGENTS.md Look Like?

This is the shape 2prompt generates. Commands come early because an agent that cannot run the tests cannot check its own work.

# AGENTS.md

Project: shop-api. Order and checkout API for the storefront.

This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.

## Stack

- Language: TypeScript
- Framework: Fastify
- Database: PostgreSQL
- Tests: Vitest
- Package manager: pnpm

## Commands

Run these from the repository root.

- Install dependencies: `pnpm install`
- Run locally: `pnpm dev`
- Run all tests: `pnpm test`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`

## Code style

- Indentation and line wrapping are whatever the formatter produces; do not hand-format against it.
- TypeScript runs in strict mode. Do not use `any`; use `unknown` and narrow it, or write the real type.

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.

## Project phase

This project is in active development. Follow the patterns that already exist; consistency beats novelty.

Every rule is something a reviewer could check. "Write clean code" is not; "do not add a dependency without asking" is.

How Long Should AGENTS.md Be?

Shorter than you think. The file is loaded into the agent's context on every task, so every line costs tokens and competes for attention. Codex stops adding instruction files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default, and files past that point are dropped. Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, which is a sensible target for AGENTS.md as well.

  • Aim for one or two screens of text.
  • Move long reference material into normal docs and link to it.
  • Delete rules nobody can remember a reason for.

What Are the Common AGENTS.md Mistakes?

  • No commands section, or commands that no longer work. This is the single most useful thing the file can contain.
  • Vague rules such as "follow best practices", which no agent can act on.
  • Contradictions, such as "use tabs" in one section and "2-space indent" in another.
  • Persona paragraphs ("You are a world-class engineer") that cost tokens without changing behavior.
  • Secrets pasted in as examples. The file is committed and read by every tool.
  • Copying the whole file into CLAUDE.md, GEMINI.md and the Cursor rules, so the copies drift apart.

The 2prompt linter checks for all of these in your browser.

How Does 2prompt Generate AGENTS.md?

The generator turns a short form (stack, commands, conventions, working rules and project phase) into AGENTS.md plus thin wrappers for Claude Code, Gemini CLI, Copilot and Cursor. The output is deterministic, so the same answers always give the same file, and everything runs in your browser.

Related: CLAUDE.md vs AGENTS.md, AGENTS.md vs copilot-instructions.md, and the .cursorrules to AGENTS.md converter.

Frequently Asked Questions

Is AGENTS.md an official standard?

It is an open format rather than a formal specification. It started as a collaboration between several agent vendors and is now stewarded by the Agentic AI Foundation under the Linux Foundation. There is no required structure: any Markdown works.

Does AGENTS.md need frontmatter?

No. AGENTS.md is plain Markdown with no frontmatter or metadata. That is the main difference from Cursor .mdc rules or Windsurf rule files, which use frontmatter to control when a rule applies.

Does Claude Code read AGENTS.md?

Only partly. By default Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. The reliable pattern is a CLAUDE.md that contains the line @AGENTS.md, which imports the shared file.

Can I have more than one AGENTS.md?

Yes. Codex, Cursor and Windsurf all read nested AGENTS.md files in subdirectories, so a monorepo can keep package-specific rules next to the package. Keep the shared rules in the root file and write only differences in nested ones.

Should AGENTS.md replace README.md?

No. README.md is for people and AGENTS.md is for agents. Keep the human overview in the README and put the precise commands, constraints and rules an agent needs into AGENTS.md, linking between them where useful.

Was this helpful?