Agent-native. Human-auditable.
A markup discipline for markdown documents intended to be consumed by software agents.
The thesis
Humans read linearly. Agents query.
A human reading top-to-bottom resolves "as discussed above" and bare pronouns from continuous context. An agent handed one 400-token section as a retrieved chunk cannot — the referent is gone, and the agent either hallucinates or skips the chunk.
Most "AI-ready documentation" projects nod at this observation and then write linear prose anyway. AgenticMD operationalizes it into concrete writing rules and metadata. The single load-bearing rule is below.
The single load-bearing writing rule
No cross-section anaphora.
## why-it-exists
This addresses the problem
described above by inverting
the iteration mechanism. The
result is what we discussed
earlier — fewer interruptions
at the cost of more upfront
tokens.## why-it-exists
HITL tools make the human the
iteration mechanism. HOTL's bet:
a multi-agent stack pays back
its tokens by avoiding rework.
See [ref:hotl#hotl-brief] for
the constraint this addresses.
Cross-section pronouns and "as we saw above" read fine to
humans and break catastrophically when an agent retrieves one
section as a chunk. Replace pronouns with explicit names and
use [ref:topic-id] for cross-topic links.
Three small additions on top of markdown
Once you accept the no-anaphora rule, everything else follows:
Typed nodes
Every ## section carries a marker
{#id node:type}. Agents route on the type —
guardrails are read differently from architecture notes,
corrections invalidate prior claims, briefs are loaded first
as cheap relevance probes.
Addressable references
[ref:topic-id] resolves by ID against the
corpus, not by file path. Reorganize the corpus; nothing
breaks. Links survive renames.
Brief-first probes
Every topic opens with a domain_brief capped at
80 words. An agent scans 20 briefs for less context than
reading one full topic, decides which matter, then pulls
deeper.
Markup discipline, not a new file format
AgenticMD does not introduce a new file extension. Documents
use .md — the same extension markdown has always
used. This places AgenticMD in the lineage of Pandoc Markdown,
MyST, and GitHub Flavored Markdown: stricter profiles of
CommonMark that assert discipline at the corpus level without
inventing a new format.
Conformance is declared at the corpus level by the presence of
a node_type: corpus_root file reachable from the
directory. Within scope, .md files are validated
against the AgenticMD discipline. Outside the scope, they are
unrelated markdown.
Files open in any editor, render in any viewer, diff cleanly in any version-control tool. No AgenticMD-aware tooling required to read a file — only to validate it.
Why this matters
- Queryable. An agent can pull one paragraph into its context window without reading the rest of the document. Token costs drop; relevance goes up.
- Portable. References resolve by ID, not by path. Corpora can be merged, split, renamed, or ingested into a graph database — nothing breaks.
- Verifiable. Files declare what they were verified against. A drift monitor can flag a document automatically when the code it describes changes.
- Auditable. Markdown substrate means a human can inspect what an agent wrote without an intermediary tool. Agent-authored content the human can still trust.
The reference corpus
AgenticMD was extracted from AI Studio's book-ai
corpus — ~74 topic files in production use. AI Studio is the
first adopter and the
reference corpus at scale; the spec was
retroactively codified to match what the corpus had been
empirically converging on.
Every rule in the spec is extracted from real-world authoring, not designed in the abstract. The rules that survived the codification round were the ones that had earned their place across dozens of topics.
Get started
1. Write a topic
Read the Quickstart. Three steps, fits on one page.
2. Validate
dart pub global activate agenticmd
then agenticmd validate ./your-corpus/.
3. Hand it to an agent
Paste the Agent Primer into your LLM's prompt. The agent then knows how to read (and write) your corpus.