Guide

AGENTS.md: make your repo agent-verifiable

An agent dropped into your repository does not want to be persuaded — it wants to act without breaking things, and it trusts what it can run over what you assert. An AGENTS.md earns that trust by pairing every claim with the exact command that proves it. The same discipline is what makes a skeptical human reviewer believe you.

The one idea

A README says “well-tested, production-ready.” An agent has no reason to believe that. An AGENTS.md says: the test suite is 36 tests across 7 files; run npm test and see them pass.Now the claim carries its own proof. The reader — agent or human — runs one command and knows. Every section below is an application of that single move: claim + the command that verifies it.

What to put in it

Four things, in roughly this order:

# AGENTS.md

## What this is
One paragraph: what the project does and its honest maturity
(alpha / beta / stable). No superlatives.

## Repo map
Where the load-bearing code lives, so an agent doesn't have to
grep blindly.
- src/lib/        core logic
- examples/       runnable reference backend
- docs/           the contract other implementers follow

## Verifiable claims
Each claim + how to check it:
- Tests: 36 tests across 7 files.        -> npm test
- The MCP endpoint answers a spec handshake and, unauthenticated,
  returns a 401 OAuth challenge:
    curl -s -D - -X POST https://mcp.example/mcp \
      -H 'content-type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
    # expect: HTTP/1.1 401 + WWW-Authenticate: Bearer resource_metadata="..."
- Build is clean:                          -> npm run build

## Conventions for agents working here
Branch naming, how to run one test, what NOT to touch, how to
report a missing capability.

Write claims that fight back

The point of a verifiable claim is that it fails loudly when it drifts. If you write “36 tests” and later delete one, the next person who runs npm test sees 35 and catches the stale doc. That is a feature: the command is a test of your own honesty. A claim with no command can rot forever without anyone noticing.

Do

  • +Attach a runnable command to every factual claim.
  • +State maturity honestly — "beta, expect breaking changes" builds more trust than "production-ready".
  • +Include live probes (curl) for anything an agent reaches over the network.
  • +Tell agents how to report a gap — a missing-capability path beats a silent wrong guess.

Don’t

  • −Assert quality ("robust", "battle-tested") with nothing to run.
  • −Let numbers drift — a wrong count is worse than no count.
  • −Duplicate the whole README; link it and stay action-focused.
  • −Describe endpoints you have not curled yourself from a clean environment.

A real one

The AGENTS.md of cortex-gateway states its test count and gives npm test to confirm it, provides live curl probes against its running endpoint (initialize handshake, the 401 OAuth challenge), maps the repo, and is blunt about beta status. Nothing in it asks to be believed; everything can be run.

Verify the network claims

The claims about your deployed surface are the ones most likely to quietly break. Run your domain through the agent-readiness checkerto confirm the MCP handshake, the OAuth discovery chain, and llms.txt actually behave the way your AGENTS.md promises — each result shows the curl, so you can paste it straight into the doc.

FAQ

AGENTS.md vs README.md?

The README is for a human deciding whether to use your project. AGENTS.md is for an agent about to act in it: where things are, what commands to run, what is true and how to check. Overlap is fine, but the AGENTS.md optimizes for machine action and verifiable claims, not persuasion.

AGENTS.md vs llms.txt?

llms.txt lives at your web root and maps your public site for agents that arrive over HTTP. AGENTS.md lives in your repository and guides an agent working inside the code. A good llms.txt often links to the AGENTS.md as the place to find verifiable claims.

Does any agent actually read AGENTS.md?

Coding agents increasingly look for it at the repo root, and it is a fast-growing convention. But its value does not depend on automated reading: a claim paired with the command that proves it is useful to any reviewer, human or machine, and it forces you to keep the claims honest.

Where does it go?

At the repository root, alongside README.md, as plain markdown. Large monorepos sometimes add a scoped AGENTS.md per package; start with one at the root.

What makes a claim "verifiable"?

A reader can run a single command and see the result you promised — npm test showing N passing tests, a curl returning the exact status and header you describe, a build finishing clean. If a claim has no command attached, it is marketing, and it belongs in the README, not here.
Verify any of this on a real domain with the agent-readiness checker— every result line ships the curl that reproduces it. See the pattern shipped end-to-end in cortex-gateway.