Skip to main content

​
What is AGENTS.md?

AGENTS.md is a Markdown file you place in your repository to give AI coding agents the context they need to work effectively on your project. Think of it as a README — but written for agents instead of humans. It provides a single, predictable place where agents can find:
  • Build and test commands
  • Code style conventions
  • Project structure overviews
  • Security considerations
  • PR and commit guidelines
AGENTS.md is plain Markdown. There are no required fields, no schemas to learn, and no tooling to install. If you know how to write a README, you already know how to write an AGENTS.md.

​
The problem it solves

AI coding agents are increasingly capable of writing, testing, and submitting code — but they often lack the project-specific context that a human contributor picks up over time. Without clear guidance, agents may:
  • Run the wrong build or test commands
  • Ignore established code style conventions
  • Miss security-sensitive areas of the codebase
  • Write commit messages or PRs in the wrong format
AGENTS.md solves this by giving agents a dedicated, reliable place to look for instructions before they start working.

​
How it differs from README.md

README.md is written for humans — it explains what a project does and how to get started. AGENTS.md is written for agents — it explains how to work on the project.

README.md

  • Project overview for new contributors
  • Installation and usage instructions
  • License and contribution links
  • Human-readable prose

AGENTS.md

  • Build, test, and lint commands
  • Code style and formatting rules
  • Commit and PR conventions
  • Security gotchas and deployment steps
Keeping them separate has clear benefits: your README stays concise and human-focused, while your AGENTS.md gives agents precise, actionable guidance without cluttering the human-facing docs.

​
How it works

When an agent starts working in your repository, it reads the AGENTS.md file before taking action. The agent uses that file to:
  1. Understand the project structure and tech stack
  2. Know which commands to run for building, testing, and linting
  3. Follow the project’s code style and conventions
  4. Apply any special instructions for commits, PRs, or security
Agents will attempt to execute testing commands found in AGENTS.md automatically. If you list pnpm test as your test command, agents will run it to verify their changes before finishing.
In a monorepo, you can place multiple AGENTS.md files at different directory levels. The closest file to the code being edited takes precedence, letting you provide general project guidance at the root and more specific instructions deeper in the tree.

​
Who supports it

AGENTS.md is used by over 60,000 open-source projects and is supported by more than 20 AI coding agents and tools.

Codex

OpenAI’s coding agent

Cursor

AI-powered code editor

GitHub Copilot

GitHub’s AI pair programmer

Gemini CLI

Google’s CLI coding agent

Aider

Open-source terminal agent

opencode

Open-source CLI agent
Other compatible agents include Amp, Jules (Google), Factory, RooCode, goose, Kilo Code, Phoenix, Zed, Semgrep, Warp, Ona, Devin (Cognition), Windsurf, UiPath, Augment Code, and Junie (JetBrains).

​
Get started

Adding AGENTS.md to your project takes less than five minutes.

Quickstart

Create your first AGENTS.md file and start guiding agents in minutes.

What to include

Learn which sections matter most and what agents actually use.

Build docs developers (and LLMs) love

Get started for freeTalk to us