Show HN: Documentation.ai.md – a docs standard for AI agents, not humans

Notifications You must be signed in to change notification settings Fork 0 Star 1 BranchesTags Open more actions menu Latest commit History 4 Commits 4 Commits Folders and files NameName Last commit message Last commit date examples examples CONTRIBUTING.md CONTRIBUTING.md LICENSE LICENSE MANIFESTO.md MANIFESTO.md README.md README.md SPEC.md SPEC.md Repository files navigation Ship documentation your users' AI agents can actually act on. Software now has two readers: the person deciding whether to use it, and the agent that will install, configure, and call it on that person's behalf. The AI Docs Standard is a simple, open convention for the second reader — a single machine-first file, documentation.ai.md, that an LLM or coding agent can load and use to run your product without guessing. 📄 The spec: SPEC.md 🔥 The why: MANIFESTO.md 🧩 A skeleton to copy: examples/TEMPLATE.md 🌐 Canonical page: iwasoft.com/standards/ai-docs 🤖 Live index (dogfood): iwasoft.com/llms.txt 🧭 Sibling standard: AI Manifest Standard — presents a site to AI (this presents a product) 📜 License: CC BY 4.0 — free to adopt with attribution The idea in one paragraph A human document earns trust by explaining why — the design, the tradeoffs, the story. An agent doesn't need to be persuaded; it needs the port number, the exact environment variable, the real response shape. Blend the two and you serve neither. So write two documents, for two readers, honestly. A fact an agent has to infer is a fact you failed to state. The file Name documentation.ai.md (the .ai. infix marks the agent document) Format Markdown — structure an agent can parse, no decorative layout Language English only (LLMs are English-first); one file, not a matrix Scope one file per product, per released version, beside the human docs ai is a reader, not a spoken language — it never goes in your site's language switcher. Adopt it in three steps Add documentation.ai.md next to your product's docs, following the required sections: identity → install → configuration → interface quickstart → admin surface → architecture facts → links. Keep it correct per release — every version ships its own, verified against the real product. Make it discoverable — link it from your site's llms.txt, and add the badge below. [](https://github.com/iwasoftcom/ai-docs-standard) What goes in it The document must be self-sufficient: an agent that has read only this file can install, call, and configure the product — no human docs, no source repo, no guessing. Dense over prose; tables over paragraphs; every command copy-pasteable and verified; absolute honesty about status. Full requirements in SPEC.md. Relationship to llms.txt Complementary, not competing. llms.txt is a site-root index of a website's content; documentation.ai.md is a per-product, per-release operational manual (closer to llms-full.txt). A site's llms.txt can link to each product's documentation.ai.md. Adopt either independently. Reference implementations Every iwasoft product ships a documentation.ai.md with each release — real, published examples of the standard in practice. See a real documentation.ai.md: Kivi — an event-ledger database Vesta — S3-compatible object storage More: Canonical write-up: iwasoft.com/standards/ai-docs Live index of every product's AI doc: iwasoft.com/llms.txt Or browse the products on iwasoft.com — each product's Documentation panel includes an AI / LLM entry. Contributing The standard evolves in the open — see CONTRIBUTING.md. Open an issue to discuss a change; send a PR to propose one. About The AI Docs Standard is authored and stewarded by iwasoft and released under CC BY 4.0: adopt it, adapt it, build on it — just keep the attribution. Canonical write-up: iwasoft.com/standards/ai-docs. Topics Resources Readme License Contributing Contributing Activity Stars 1 star Watchers 0 watching Forks 0 forks Report repository