AGENTS.md

January 30, 2026

AGENTS.md is an open standard for guiding AI coding agents — a dedicated file in your repository that provides the context and instructions agents need to work effectively on your project. Think of it as a README for agents: predictable, simple, and universal.

The Core Idea

README.md files are for humans: quick starts, project descriptions, contribution guidelines. AGENTS.md complements this by containing the extra context coding agents need — build steps, tests, conventions, and project-specific instructions that might clutter a README or aren't relevant to human contributors.

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

Why Not Just Use the README?

Three reasons:

  1. Predictability: Agents need a known location to find instructions. AGENTS.md is always AGENTS.md.

  2. Separation of concerns: Humans and agents need different information. Keeping them separate keeps both files focused.

  3. Detail level: Agents benefit from precise, verbose instructions that would clutter documentation for humans.

Why It Works

Vercel's research found that an 8KB compressed docs index in AGENTS.md achieved 100% pass rate on their evals, while skills-based retrieval topped out at 79% with explicit instructions.

The insight: passive context (always available) beats active retrieval (fetched on demand). When knowledge is embedded directly in AGENTS.md, the agent doesn't need to decide to look it up — it's already there.

As one developer noted:

vercel ran evals on teaching coding agents. skills: 53% pass rate. agents just didn't use them. plain markdown file in repo root: 100%

Adoption

AGENTS.md is used by over 60,000 open-source projects and is supported by major AI coding tools:

How to Use It

1. Create the file

Add an AGENTS.md file at your repository root. Most coding agents can even scaffold one for you.

2. Cover what matters

Popular sections include:

3. Nested files for monorepos

In large monorepos, place additional AGENTS.md files inside each package. Agents automatically read the nearest file in the directory tree, so each subproject can have tailored instructions. The OpenAI repo has 88 AGENTS.md files at time of writing.

What Goes In It?

Here's a real-world example structure:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add workspace visibility
- Check the `name` field in each package.json for correct package names

## Testing instructions
- Find CI plan in `.github/workflows`
- Run `pnpm turbo run test --filter <project_name>` for package tests
- Fix any test or type errors before committing
- Add or update tests for changed code, even if nobody asked

## PR instructions
- Title format: `[<project_name>] <Title>`
- Always run `pnpm lint` and `pnpm test` before committing

Governance

AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI, Amp, Google (Jules), Cursor, and Factory. It's now stewarded by the Agentic AI Foundation under the Linux Foundation.

The format is intentionally simple: just Markdown. No required fields, no schema validation. Use any headings you like; the agent simply parses the text you provide.

vs CLAUDE.md and .cursorrules

Before AGENTS.md consolidated, different tools had their own conventions:

AGENTS.md unifies these into a tool-agnostic standard. If you have existing files, you can migrate:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Sources

See also: Context Loading · Agent Skills · AGENTS.md vs Skills