AGENTS.md: The README File That AI Agents Actually Read
README.md is for humans. AGENTS.md is for AI agents. Same location (repo or domain root), same markdown, different audience — and a very different payoff. A well-formed AGENTS.md lifts two 10%-weight dimensions of your Agent Readiness Score and cuts the time an agent needs to become productive from minutes to seconds. Here is the spec, a copy-paste template, and why it is the cheapest score improvement you can ship this week.
What AGENTS.md Is
AGENTS.md is a plain markdown file that lives at the root of a code repository (for software projects) or at the root of a business domain (for websites). Its purpose is simple: tell an AI agent everything it needs to become productive in your project or business, in a format optimized for LLM consumption rather than human reading.
The convention mirrors how README.md works. Any developer who clones a new repo looks for README.md first. Any agent dropped into a new project will look for AGENTS.md first. When it finds one, the agent can skip exploratory tool calls, stop guessing at build commands, and move directly to useful work. When it does not, the agent reads README.md and tries to reverse-engineer everything it needs — which costs time, money, and quality.
AGENTS.md is not marketing copy, not a changelog, not a philosophical mission statement. It is an operating manual: project purpose, how to run, key commands, tool inventory, auth, and example workflows. Every section is load-bearing.
README.md vs AGENTS.md
They are siblings, not replacements. Most projects should ship both. The comparison clarifies why the differences matter in practice.
The single biggest difference is assumed context. A human reading README.md knows what Git is, how npm works, and what a localhost port looks like. An agent parsing AGENTS.md should not assume any of that — the file declares everything explicitly, and that discipline is what makes it useful.
The 6 Canonical Sections
The AGENTS.md convention defines six sections in a specific order. Agents parse them by H1/H2 headings, so the exact names matter. You can add more sections below — many teams add a “Gotchas” or “Non-Obvious Patterns” section — but the six below are the minimum.
Project Purpose
One paragraph stating what the project does, who it is for, and the outcome it produces. No marketing prose — agents will quote this verbatim when asked what the project is, so accuracy wins over enthusiasm.
# What this is SaaS invoicing API for freelance consultants. Generates, sends, and reconciles Stripe-powered invoices. Ruby on Rails backend, React dashboard.
How to Run
The literal commands an agent should execute to stand the project up. Include expected output, port numbers, environment variables, and any one-shot setup scripts. Agents copy-paste from this section — keep it unambiguous.
# Run pnpm install pnpm db:seed pnpm dev # listens on :3000
Key Commands
Lint, typecheck, test, build, and deploy commands with their pass criteria. Without this, agents run npm run and hope. With it, they run npm run typecheck and know a 0-exit code means typecheck passed.
# Verify pnpm lint # 0 warnings required pnpm typecheck # must pass pnpm test # 380 tests
Agent-Callable Tools
Any MCP tools, REST endpoints, or A2A skills the agent should use instead of reinventing functionality. This is what separates an AGENTS.md from a README — you are publishing a tool menu to the LLM.
# Tools MCP: create_invoice, send_invoice, reconcile_payment REST: GET /api/invoices, POST /api/invoices
Auth Requirements
Which endpoints require auth, what kind (Bearer, OAuth, API key), and how to obtain credentials in a dev environment. Agents that cannot figure out auth burn minutes guessing; a crisp auth block saves the whole session.
# Auth Bearer token. Dev: STRIPE_TEST_KEY=sk_test_... in .env.local
Example Workflows
End-to-end task recipes: "to add a new invoice template, do X, Y, Z." These are the highest-value section because they encode tribal knowledge that would otherwise cost an agent 5 exploratory tool calls to figure out.
# Workflow: add new template 1. Copy templates/base.liquid 2. Register in config/templates.yml 3. Run pnpm templates:sync
Copy-Paste Template
Drop this into the root of your repo, edit every placeholder, commit, and you have a compliant AGENTS.md. Keep it under 250 lines — agents re-read it on every task, so every line must pay for itself.
# AGENTS.md
## What this is
One-paragraph description of the project, its users, and its outcome.
## How to run
```bash
pnpm install
pnpm db:seed
pnpm dev
```
## Key commands
- `pnpm lint` - 0 warnings required
- `pnpm typecheck` - must pass
- `pnpm test` - full suite, ~45 seconds
- `pnpm build` - production build
## Agent-callable tools
- MCP: `create_invoice`, `send_invoice`, `reconcile_payment`
- REST: `GET /api/invoices`, `POST /api/invoices`
- A2A: skill `invoice_specialist` at `/.well-known/agent-card.json`
## Auth
Bearer token on all `/api/*` routes.
Dev: set `STRIPE_TEST_KEY=sk_test_...` in `.env.local`.
## Example workflows
### Add a new invoice template
1. Copy `templates/base.liquid` to `templates/<name>.liquid`.
2. Register in `config/templates.yml` with type and default fields.
3. Run `pnpm templates:sync` to regenerate the schema.
### Reconcile a payment
1. Call MCP `reconcile_payment({ invoice_id, stripe_charge_id })`.
2. Confirm the invoice status is `paid`.
3. Emit webhook via `pnpm webhooks:fire paid`.
Ship it as /AGENTS.md at the repo root (for code) or at https://yourdomain.com/agents.md for a business site. No auth, no redirects, no paywall. Agents will probe both paths during discovery — a 200 response with a valid markdown body is all they need.
What AGENTS.md Does for Your Agent Readiness Score
The AgentHermes scanner checks for AGENTS.md on every audit. When it finds one, two dimensions benefit directly:
D6 Data Quality
AGENTS.md shows you have structured, machine-readable documentation. The scanner gives additional credit when the file uses the 6 canonical sections, includes runnable code blocks, and declares explicit tool inventories.
D9 Agent Experience
D9 measures how easily an agent can become productive on your surface. A crisp workflow section, explicit auth guidance, and named commands are exactly the signals D9 rewards. Sites with AGENTS.md typically gain 8–12 points on D9 alone.
Combined, that is 20% of the total Agent Readiness Score touched by a single markdown file. For below-Bronze scores (under 40), AGENTS.md alone can be the difference between a 38 and a 46 — crossing the line from “not scored” into Bronze tier and onto the public leaderboard.
AGENTS.md vs llms.txt (Both, Not Either)
AGENTS.md and llms.txt are frequently confused. They serve complementary purposes:
llms.txt answers: what should an LLM read?
It is a content map. A prioritized list of URLs on your site that LLMs should fetch to understand your business. Lives at /llms.txt.
AGENTS.md answers: how does an agent operate here?
It is an operating manual. Purpose, commands, tools, auth, workflows. Lives at /AGENTS.md (repo) or /agents.md (domain).
Publish both. llms.txt tells an LLM what to read when researching your business. AGENTS.md tells an agent how to act once it decides to engage. Together they turn your site from a static destination into an agent-operable surface.
Frequently Asked Questions
What is AGENTS.md?
AGENTS.md is a markdown file, placed at the root of a code repository or the root of a business domain, that documents the project specifically for AI agents to consume. It has a predictable section structure (purpose, run, commands, tools, auth, workflows) and is written in a tone LLMs parse reliably. Think of it as README.md for machines.
Where do I put AGENTS.md?
For code projects: at the repository root, alongside README.md. For business websites: at the domain root, accessible as /agents.md. The file must be publicly readable with no authentication, because agents need to fetch it during discovery before they have credentials. Agents follow the same convention as the humans-oriented README but read a different file.
How is AGENTS.md different from llms.txt?
llms.txt is about website content — it lists which pages on your site are important and what LLMs should read to understand your domain. AGENTS.md is about project and tool context — it tells an agent what the project does, how to run it, and which tools it can call. Websites often ship both: llms.txt as a content map, AGENTS.md as an operating manual.
Does AGENTS.md affect my Agent Readiness Score?
Yes. AgentHermes detects AGENTS.md during a scan and adds points to D6 Data Quality (weight 0.10) and D9 Agent Experience (weight 0.10). Combined that is 20% of the total score impacted by a single markdown file. Sites that publish a well-formed AGENTS.md also tend to rank higher across D3 Onboarding because the section on key commands doubles as onboarding guidance for an agent.
Do I need to write AGENTS.md by hand?
No. If you connect a business to AgentHermes, the platform auto-generates an AGENTS.md from your existing business data, MCP tool inventory, and A2A agent card. You can override any section, but the starting point is already aligned with the spec. For code repos, the same generator accepts a package.json / pyproject / go.mod and outputs a first draft you can edit.
Get AGENTS.md auto-generated for your business
Run a free Agent Readiness scan to see whether your site already ships AGENTS.md. Connect your business and AgentHermes will generate a compliant file plus matching llms.txt and agent-card.json.