Team open-sources documentation.ai.md, a docs standard written for AI agents

Agents became the primary reader

A team that builds several developer products — among them an event-ledger database and an S3-compatible object store — says the way people adopt its tools has quietly flipped. In a post published August 30 on dev.to, the team writes that most people who try its products no longer start in a browser; they tell a coding agent to add the tool to their project, and the agent handles the installation and the wiring.

Watching those agents work against the existing documentation mostly went fine, the team reports. But every so often an agent would invent a configuration flag that did not exist, reach for the wrong port, or call an endpoint that was almost right. The team's diagnosis is that this was not the model failing. The docs had been written to persuade and onboard humans, which left the agent reconstructing facts from prose scattered across paragraphs.

A second document for a different reader

The fix was to ship a second file alongside each release: documentation.ai.md. It is explicitly not a terser translation of the human docs, the team stresses, but a different document for a different reader, held to a stricter standard of precision. It is written in English, dense, and self-sufficient — an agent that has read only that file should be able to install, configure and call the product.

The format uses fixed sections in a fixed order:

• a one-line statement of what the product is
• install and run instructions, with exact commands, image names and ports
• a configuration section covering every environment variable and key, each with its default
• an API quickstart built around a real request and response rather than pseudocode
• an admin surface, including how the first credential is obtained and the common operations
• architecture facts that affect integration
• links

Two rules shape the writing. There is no marketing language. And the file is blunt about status: if something is early or unaudited, it says so, because an agent that recommends an unstable feature to a user after the documentation oversold it is a genuine failure mode, not a hypothetical one.

Not another llms.txt

The post anticipates the obvious question. documentation.ai.md is not an attempt to replace llms.txt, which the team describes as a good site-level index of content. Their file is instead a per-product, per-release operational document, closer in spirit to llms-full.txt: complete rather than an index. The two formats can be used together without conflict, they argue, rather than competing.

Released as an open standard

After the format proved itself across their own products, the team wrote it up as an open standard under a CC BY 4.0 licence, with the specification published in a public GitHub repository under its iwasoftcom organisation, so other vendors can adopt it as-is.

Why it matters

The post is a concrete data point for a shift many developer-tools companies are only starting to name: the reader of your documentation is increasingly not the person who decides to install your product, but the agent acting on their behalf. Agents read differently. They do not fill gaps with judgement; they fill them with plausible guesses — an invented flag, a near-miss endpoint. By that logic, any fact an agent has to reconstruct is effectively a fact the documentation never stated, and the cost of the gap now lands as an integration bug in a user's project rather than a mildly confused reader.

The move also reframes documentation as distribution. If agents are the ones evaluating and wiring up tools, machine-facing precision becomes part of the adoption funnel, and honesty about a feature's maturity becomes functional rather than merely reputational, because agents repeat whatever the docs claim. Whether documentation.ai.md specifically catches on is an open question — it sits alongside an existing convention in llms.txt — but the underlying practice, shipping a distinct and stricter document for machine readers with every release, is the part other teams can copy starting today.