All posts
· 11 min read ·

AGENTS.md is a convention, not a contract — and the difference is starting to matter

60,000 repos adopted AGENTS.md without a schema, signing, or validator. The same omissions that made adoption frictionless are the ones that come due as agents start to depend on what those files say.

AGENTS.md is the most successful agent-web convention of the past 18 months. It is a Markdown file at the repo root that tells a coding agent how to build, test, and contribute to the project, and it was introduced by OpenAI in August 2025 and has been adopted across more than 60,000 open-source projects since. Every major coding agent in the field reads it: GitHub Copilot, VS Code, Cursor, Devin, Codex, Factory, Amp, Jules, Gemini CLI. The specification was donated to the Agentic AI Foundation alongside MCP and goose in December 2025.

The thing the adoption number obscures is why AGENTS.md spread that fast. The format takes essentially no positions. It is standard Markdown. There are no mandatory fields. There is no schema. There is no signing, no version pinning, no provenance, no validator. The spec's own description of itself is one sentence long: "use any headings you like; the agent simply parses the text you provide." That permissiveness is the feature. It is also the bill that comes due as agents start to depend on what those files say.

What the spec leaves out, on purpose

Read the AGENTS.md spec end to end and the list of things it does not require is short and load-bearing. It does not require:

  • A canonical filename location (root vs. subdirectory).
  • A signing mechanism — commit signing exists, but the file itself contains no attestation that it was authored by a project owner.
  • A schema or required sections. The example file uses "Dev environment tips," "Testing instructions," and "PR instructions," but a valid AGENTS.md may contain none of those.
  • Versioning of the format. There is no version: field. Older agents and newer agents read the same file with no negotiation.
  • A correctness check. Nothing in the spec verifies that the commands listed in ## Build actually build the project, or that the test command actually runs tests.
  • A consistency check against the codebase. An AGENTS.md can name packages, scripts, or environment variables that no longer exist in the repo.

The omissions are intentional. The competing conventions in the same space (Anthropic's CLAUDE.md, Cursor's .cursorrules, Copilot instructions) are similarly permissive, because adoption velocity in this space depends on the cost of compliance being zero. The AGENTS.md authors' bet was that an agnostic, low-ceremony format would win the network effects. They were right; 60,000 repos later, the bet has paid out.

The bill that comes due

The same property that made AGENTS.md easy to adopt makes it hard to trust at scale. An agent reading an AGENTS.md in a downloaded repo cannot answer four questions that matter:

  1. Was this file authored by the project maintainer, or added in an anonymous pull request a day before a release?
  2. Does the AGENTS.md still match the codebase, or did the file sit static while three refactors moved the build to a different directory?
  3. Are the commands in the file safe to execute, or do they include a curl … | sh line that downloads a payload?
  4. Is this the same AGENTS.md the project's CI saw, or a modified version pulled from a fork?

Each of those questions has a natural answer if the format had even one of the omitted features: a signature would address (1), an automated probe would address (2), a syntactic safety scan would address (3), a content-addressed reference (a hash, a commit pin, a release tag) would address (4). The spec specifies none of them, which is consistent with its design and means the verification work has to live somewhere else.

The closest historical analogue is package.json in npm's first decade. The format spread because it was permissive: any text editor could write one, any program could read one, and the registry indexed it without enforcement. The verifiability problems showed up later in the form of typosquats, malicious post-install scripts, and dependency confusion attacks. The fix did not arrive in the form of a stricter package.json spec. It arrived in the form of registries that ran scans, publishers that signed packages, and consumer tooling that checked integrity. AGENTS.md is in the first chapter of that same arc.

Convention versus contract

The distinction worth holding onto is between a convention and a contract. A convention is a shared format that lowers coordination costs. A contract specifies obligations both sides can verify. AGENTS.md is the first; MCP server cards are also the first; A2A Signed Agent Cards are starting to move toward the second. The agent web is a stack of conventions today, in approximately the same architectural position that the web of unsigned HTML pages was in 1995, before certificate authorities and Certificate Transparency made browser-side verification routine.

Convention Contract
What it standardizes Format and location Format, location, and provenance
What a consumer can verify That the file parses That the file parses and was authored by the claimed party
Adoption cost Near zero Non-zero (signing, validation)
Adoption velocity High Lower
AGENTS.md fits here Today Possibly the next version
The agent-web format spectrum: convention to contract A horizontal axis with "convention" at the left end and "contract" at the right end. Six agent-web formats are plotted along it. AGENTS.md, CLAUDE.md, and .cursorrules sit at the convention end. MCP server cards sit toward the middle, slightly left. A2A Signed Agent Cards sit past the middle. ERC-8004 sits closest to the contract end. The arrow shows the direction the agent web is incrementally moving. AGENT-WEB FORMAT SPECTRUM

convention format + location contract format + provenance

AGENTS.md CLAUDE.md .cursorrules MCP cards A2A signed cards ERC-8004

DIRECTION OF AGENT-WEB MATURATION

That table is not a critique. A convention is the right product for the adoption phase. A contract is the right product for the trust phase. The specific question to ask of AGENTS.md is when it crosses from one phase to the other — which is the same question to ask of MCP cards, A2A Agent Cards, and every other piece of self-declared agent-web metadata that exists right now.

What this means for tools that read AGENTS.md

If you build a coding agent that reads AGENTS.md files in unfamiliar repos, the practical implication mirrors the lesson from the MCP-server scans this spring: the file is a claim, not evidence. Three things that a serious consumer probably wants to add on top of "parse the Markdown":

  • A diff between the AGENTS.md content and observable repo state. If the build command in ## Build is pnpm build and the repo has no pnpm-lock.yaml, the file is drift, not guidance.
  • A heuristic scan for command patterns that should not be executed blindly. Network downloads followed by execution, sudo invocations, writes outside the workspace.
  • A trust signal about the file's authorship: a commit-author check, a signature lookup, or at minimum a flag that this AGENTS.md is newer than the project's last tagged release.

The work Agenstry does on MCP servers (probe what is published, publish the probe) applies one layer up to AGENTS.md and one layer down to A2A Agent Cards. The shape is the same. The format is different. The cost of skipping the probe is identical: a consumer that trusts a self-declared metadata file is trusting whoever last wrote it, with no way to ask who that was.

What we're watching

Three things, all observable within the next two quarters:

  1. Whether the Agentic AI Foundation version of AGENTS.md adds an optional schema or signing mechanism. A v1.1 with version: and maintainers: fields, even as opt-in, would be a clean step from convention toward contract. A v1.1 that stays purely cosmetic would signal the foundation is preserving adoption velocity as the highest priority.
  2. Whether the first reported AGENTS.md-related supply-chain incident lands in 2026. The pattern is well-established in adjacent ecosystems (npm, PyPI, VSCode extensions); the format's permissive stance does not exclude it. If an agent gets directed to run a malicious command via a poisoned AGENTS.md in a popular repo, the incident will reshape the conversation overnight.
  3. Whether agent vendors begin to publish their own probes of AGENTS.md correctness. Independent verification of "does this AGENTS.md still match its repo" is the kind of measurement the format itself refuses to encode. The first vendor to publish the percentage of AGENTS.md files in the wild that drift from their repos will be doing the work the spec deferred.

AGENTS.md is the cleanest demonstration that an agent-web convention can scale to tens of thousands of repos in under a year. It is also the cleanest demonstration that scale and trust are independent problems. The first is solved. The second is the work ahead.

Sources

← Back to blog Agenstry