AGENTS.md: What It Is and How to Write One for Your API

# AGENTS.md — Cloudflare Docs

This file helps AI agents understand the structure, tooling, and conventions of the `cloudflare-docs` repository so they can make correct, buildable changes.

## Repository overview

This is the source for [developers.cloudflare.com](https://developers.cloudflare.com). It is an **Astro** site using the **Nimbus** (`nimbus-docs`) documenta…

AGENTS.md is a plain Markdown file, placed at the root of a repository, that tells AI coding agents how to work with your project. The agents.md convention describes it as a README for agents: a dedicated, predictable place for the context an agent needs — setup commands, conventions, gotchas — that would clutter a README written for humans. It is 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.

For an API producer, the file matters because coding agents are already the first mass agent-readers of your API. Every time a developer asks Cursor, Codex, or Claude Code to "integrate Acme Payments," an agent clones your SDK, reads whatever orientation it can find, and starts constructing requests. Across the Discry Index corpus, only 30% of scanned APIs pass the AGENTS.md check — the starkest gap among the common discovery signals. For comparison, 64% publish an llms.txt. That gap is an opportunity: this is currently the cheapest discovery signal to ship and the one most of your competitors are missing.

What the convention actually specifies

The format is deliberately minimal. Per agents.md, there are no required fields and no schema — AGENTS.md is standard Markdown, and the agent simply parses whatever headings and text you provide. The convention does document a few behaviors you can rely on:

• Popular sections include a project overview, build and test commands, code style guidelines, testing instructions, and security considerations. Anything you would tell a new teammate belongs here.
• Nesting works. In a monorepo, each package can carry its own AGENTS.md; agents read the nearest file in the directory tree, so the closest one takes precedence. The main OpenAI repo carries 88 of them.
• Conflicts resolve predictably: the closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything.
• Listed commands get run. If you include test or lint commands, agents will attempt to execute them and fix failures before finishing a task.

One file works across the ecosystem — Codex, Jules, Cursor, Aider, Devin, Gemini CLI, GitHub Copilot's coding agent, and many others read the same file. You write it once; every agent that supports the convention benefits.

Why this is an API producer's problem

The convention was designed for contributors working on a codebase. The reason it belongs on your agent-readiness checklist is that the same mechanics fire when an agent builds against your API. A coding agent scaffolding an integration will open your SDK repo, and an AGENTS.md there is the one place you can hand it correct, current instructions instead of letting it reconstruct your API's behavior by trial and error. When the reconstruction goes wrong, the support ticket blames your API, not the agent.

The corpus shows both ends of this. Vercel ships AGENTS.md files across vercel/vercel, Next.js, and its agent-skills repos, each with context-specific guidance; LangChain carries one in every major repo. Luno publishes a high-quality AGENTS.md in its luno-python SDK covering project architecture, the request/response flow, the auth pattern, and the error shape — well above the norm. Adyen has adopted the file across all of its SDK repos. On the other side, Cohere's audit found no AGENTS.md in either its docs repo or its SDK repos, and for Dwolla the absent AGENTS.md was the one meaningful discovery signal missing from its primary repos — a coding agent cloning the SDK gets no repo-level orientation at all.

There is also a failure mode between present and useful. Attio's docs repo contains an AGENTS.md that is the un-customized Mintlify boilerplate — "First-time setup: Customize this file…" with empty terminology sections — so an agent gets generic docs-tooling instructions rather than anything about Attio. Shipping the file is the start; the content is the point.

What to put in an AGENTS.md for an API

Browse the examples gallery for real files from the corpus. The sections below are the ones that earn their keep for an API specifically.

From key to first successful call

The single highest-value thing you can document is the shortest path from "I have nothing" to a first successful authenticated request. Spell out where keys come from, which authentication scheme your API uses (header name, token prefix, sandbox vs. live keys), and one copy-pasteable smoke-test call with the exact success response and the most likely failure response. An agent that can verify auth in one request stops guessing; an agent that can't will burn attempts inventing header formats.

Conventions an agent cannot infer

Agents generalize from the APIs they have seen most. Where your API departs from the majority pattern, say so explicitly: amounts in integer minor units, lowercase currency codes, cursor-based pagination with no page parameter, IDs with typed prefixes, timestamps in epoch seconds. Every unstated convention is a place where the agent's prior fills the gap — usually with another API's behavior.

Rate limits, pagination, and retry gotchas

State your rate limits as numbers, per environment, and say exactly what a 429 carries and what to do with it. Across the corpus we repeatedly see error docs that stop at "returns 429" without telling an agent to honor Retry-After — which invites immediate, confident retry storms. Document your retry and backoff expectations, including which requests are safe to retry and how idempotency keys interact with retries.

The mistakes agents actually make

Name the two or three errors you see most in your own support queue when AI-assisted integrations go wrong. Typical patterns: hallucinated endpoints or parameters borrowed from a similar API, live keys used against sandbox (or the reverse), and pagination handled as offset when the API is cursor-based. A short "known agent mistakes" section converts each recurring ticket into one line of prevention.

A worked example

A realistic skeleton for a payments API's SDK repo:

# AGENTS.md — acme-payments-node

Acme Payments is a REST API for charges, refunds, and payouts.
Base URL: https://api.acmepay.example/v2 · Docs: https://docs.acmepay.example

## First successful call
1. Create a sandbox key at https://dashboard.acmepay.example/keys
   (sandbox keys start with `sk_test_`).
2. Auth is a bearer header — `Authorization: Bearer sk_test_...` —
   never a query parameter.
3. Smoke test:
   `curl "https://api.acmepay.example/v2/charges?limit=1" -H "Authorization: Bearer $ACME_KEY"`
   A 200 with `{"data": []}` means auth works. A 401 with code
   `key_mode_mismatch` means a live key was used against sandbox.

## Conventions
- Amounts are integer minor units (`1099` = $10.99). Never send floats.
- Currency codes are lowercase ISO 4217 (`"usd"`, not `"USD"`).
- All IDs carry a type prefix: `ch_` (charge), `cus_` (customer), `po_` (payout).
- List endpoints paginate by cursor: pass `starting_after=<last id>`.
  There is no `page` parameter.

## Rate limits & retries
- 100 req/s per key in live, 25 req/s in sandbox.
- 429 responses include `Retry-After` (seconds). Honor it; never retry
  immediately.
- Send an `Idempotency-Key` header on every POST; retry with the SAME
  key or a network blip can double-charge.

## Known agent mistakes
- `customer` takes a `cus_...` ID, not an email address.
- Webhook signatures verify with the endpoint secret (`whsec_...`),
  not the API key.
- `/v2/charges` has no `capture: "true"` string form — the field is boolean.

## Build & test (this repo)
- `npm install && npm test` — runs against recorded fixtures, no key needed.
- `npm run test:integration` requires `ACME_SANDBOX_KEY`.

Nothing in this file is philosophical. Every line either shortens the path to a working call or blocks a known wrong turn.

How Discry checks for AGENTS.md

AGENTS.md is one of the discovery signals in the Discry methodology. The scanner fetches AGENTS.md from your GitHub org's primary repository on its default branch (with the org-level .github repo as a fallback). A file with real content passes; a stub under 200 characters is credited as partial; and if no public GitHub org is known for your API, the check fails — an agent has nowhere to look. The signal page documents the full semantics.

One boundary worth stating: Discry measures discoverability — whether agents can find and understand your API from its public documentation surface, before execution. We never run your code or test live authenticated calls. The AGENTS.md check verifies that the orientation file exists and has substance, which is exactly what a coding agent probes for before it starts work.

Where it fits among the other signals

AGENTS.md covers the repository surface; your docs domain needs its own entry points. An llms.txt gives agents a curated map of your documentation, and a machine-readable OpenAPI spec is the contract agents validate requests against — it carries the most weight of any discovery check. Together they answer the three questions an agent asks in order: where are the docs, what is the contract, and how do I work in this repo. For how the full discovery layer and comprehension measurement fit together, start with the pillar guide to what agent-readiness is.

If you ship one repo-surface improvement this quarter, make it this file. It is a few hundred lines of Markdown, the coding agents your integrators already use will read it, and most of the APIs we scan still haven't written one.

What grade does an AI agent give your API? Discry your API — free — 60 seconds, no signup.