Merlon Docs. A keystone AI skill for docs. And a CLI tool to compile guides and validate links.

$2.41T

estimated cost of poor software quality in the US in 2022, about $1.8T of it from operational failures

$400B

estimated yearly cost of downtime across the Forbes Global 2000

1.2× to 12.8×

more impact on organizational performance from the same practices when documentation quality is high

Sources: CISQ 2022, Splunk and Oxford Economics 2024, and DORA 2023. Industry sponsors funded the first two estimates, so read them as orders of magnitude. How these figures connect to documentation.

Why it matters

Unreliable software is costly, and missing documentation is the fix you can ship next

Software failures cost hundreds of billions to trillions of dollars a year. Security vulnerabilities, fragile supply chains, and technical debt all drive those losses, but missing documentation is the risk factor your team can address in its next pull request.

When engineers leave design decisions and runbooks unwritten, teams ship with blind spots: a constraint nobody recorded, an operational step only one person knows, or a guide that still describes a removed component. That gap slows down releases, incident response, and onboarding.

DORA research finds that documentation quality amplifies the other engineering practices a team invests in. Merlon Docs gives human engineers and AI coding agents a shared home for system knowledge in git. merlon compile builds single-file guides for review, and merlon check validates indexes, links, and paths in CI while engineers and agents verify that the prose stays accurate.

Who it’s for

For the people who answer for reliability

If you’re responsible for the platform, the team’s delivery, quality or the skills your agents load, Merlon Docs gives you a documentation practice you can set as policy instead of hoping for it.

• Platform and DevOps leads

  Add one check to the pipeline you already run. Broken links, unindexed pages and stale compiled docs fail the build.

• Engineering and technical managers

  When intent is written down and reviewed with each change, you can learn what the system does without asking the one person who remembers.

• QA and reliability engineers

  Acceptance criteria and known constraints live in shards next to the code, where a test or a review can point at them.

• Owners of the AI skill stack

  One skill, beside your planning and review skills, that tells every agent to update the docs it touches.

Make it policy

1. Install the skill

   Add npx skills add Merlon-Docs/merlon –skill merlon-docs to each repository’s agent setup.

2. Require the check

   Make merlon check a required CI job, so broken docs block a merge like a failing test.

3. Review docs with code

   Ask reviewers to read the shard diff beside the code diff in each pull request.

Already the person who writes things down? Merlon Docs gives your notes a structure that agents and the next reader can use, and a check that keeps the links working. The same shards suit product, design and support teams that keep their knowledge as text.

The problem

Where docs break when agents edit a repository

Code shows what a system does, but not why the team built it that way, and people outside engineering can’t read it. When agents write much of the change, documentation fails in a few familiar ways. Most of them are structural, so a check can catch them.

• One long docs file

  Every change edits the same file, so branches conflict and the table of contents goes stale.

  Each topic is its own shard. merlon compile assembles the README or handbook, contents included.

• Guessed links

  Agents write #anchor slugs from memory, and the links break without anyone noticing.

  merlon check fails CI on a broken link or anchor and names the file and line.

• Pages nobody indexed

  A new file is merged, but no guide lists it, so no reader finds it.

  Every shard must appear in a guide index or the check fails, which makes adding a page a deliberate act.

• Stale compiled output

  Someone edits the README by hand or forgets to rebuild it, and it stops matching its source.

  The check fails when a compiled file differs from what its shards produce.

• The whole handbook in every prompt

  Pasting every page into each turn spends context on pages the task doesn’t need.

  An agent following the skill reads only the shards for its task. Merlon Docs doesn’t stop it from reading more.

• Intent that never gets written down

  A decision is made in a pull request or a ticket and is never written into the docs.

  The skill tells the agent to update shards in the same change, and a reviewer checks that the words match what the team meant.

merlon check covers the structural failures. It doesn’t judge whether the prose is true. That part rests on the agent following the skill and on human review.

Why every repository needs one

A keystone among your helper skills

Agents pick up helper skills for each task, such as planning, test-driven development, or code review. Those skills help finish the task in front of them. Merlon Docs looks after what outlasts the task, from the intent behind a feature to how the team builds and operates the system.

1. The agent writes

   The merlon-docs skill tells the agent which shards a change touches and to update them in the same change as the code.

2. A person confirms intent

   Shards are small and change in the same pull request, so a reviewer can check that the docs say what the team meant.

3. The CLI checks structure

   merlon check fails CI on broken links and anchors, missing files, unindexed shards, and stale compiled files. It doesn’t judge whether the prose is true.

Foundational AI skills

Built for software repositories, in the same family as LLM Wiki and aDNA

Task skills help an agent finish one job, like writing a test, fixing a bug, or reviewing a diff. Foundational AI skills manage the durable context that outlasts a single chat session. LLM Wiki, aDNA, and Merlon Docs all solve that problem with plain Markdown files, but they target different scopes.

LLM Wiki and aDNA organize general knowledge across any domain. LLM Wiki runs a compounding wiki loop (init, ingest, query, and lint), while aDNA structures a broad knowledge vault into what, who, and how directories across any subject.

Merlon Docs is purpose-built for software projects maintained in git. Shards sit next to source code, merlon compile stitches them into single-file guides for review, and merlon check validates links against real repository files, directories, and headings in CI.

• LLM Wiki

  Compounding general-knowledge wiki. Agents initialize a wiki, ingest external sources, query across sessions, and lint wiki pages for consistency.

• aDNA

  General-purpose knowledge vault organized into what, who, and how directories. It pairs folder instructions, domain notes, and procedural skills across any subject.

• Merlon Docs

  Purpose-built for software repositories. Shards hold specs, decision records, runbooks, and glossaries next to code, compiled with merlon compile and gated in CI by merlon check.

• Wired into AGENTS.md

  Point AGENTS.md at the merlon-docs skill so coding agents read and update the relevant shards in the same pull request as the code, for engineers who maintain the system over the long haul.

How it works

Organize docs once, write for every reader

Docs live in a docs/ folder as small Markdown files called shards, one topic per file. Guides list which shards they include, and merlon compile assembles each guide into the README or handbook its reader opens.

A new perspective is a new guide over existing shards. Drafting a customer guide from the same shards, or reviewing the whole set, takes a language model little time.

docs/
├── merlon.config.json
├── features/    what the product does and why
├── client/      install and usage
├── developer/   setup and workflow
└── glossary/    one term per file

• Focused feature work

  An agent building a feature reads only the few shards that describe it.

• Ready for retrieval

  Small, single-topic files are a natural first step toward retrieval-augmented generation.

• Plain Markdown

  GitHub Flavored Markdown with no custom syntax. Stop using Merlon Docs and you keep ordinary docs.

• Open

  MIT licensed. The specification and the reference CLI share one public repository.

Context size

How much an agent reads

An agent that loads a whole guide, or a large docs excerpt from a service such as Context7, spends context on pages the task doesn’t need. An agent following the skill reads the shards for its task. The sizes below compare the two on this repository.

What the agent reads	Relative size	Tokens (estimate)
Features guide and glossarythe monolith, docs/_build/guides.md		85,071
Developer guideDEVELOPERS.md		41,301
CLI guidepackages/merlon-docs-cli/README.md		17,051
Largest shardone file		4,322
90th percentile shardone file		2,092
Average shardmean of 148 shards		980
Median shardone file		807

Estimated tokens an agent loads: a whole compiled guide against one shard, measured on this repository's 148 shards when this site was built on 2026-10-19, from commit bb3d832. Counted with o200k_base from the open-source gpt-tokenizer. Every model and system tokenizes differently, so read these as rough, relative sizes, not costs. Benchmarks says how to re-measure with pnpm bench:context-size and another tokenizer or a counter of your own.

Status

Where Merlon Docs stands

Merlon Docs is an early project, built by one maintainer with help from a colleague. It is useful today and under active refinement. On a repository where agents wrote every commit, the structural checks held: guide manifests indexed every shard and no broken internal link reached trunk. The agents produced useful documentation, but it sprawled, with seven shards past 300 lines and one guide still describing a removed component. A person used the skill’s doc-review workflow to reorganize it. That gap between structure and meaning is what current work on the system and the skill targets.

Specification 1.0.0

148

shards in this repository's guides, each one listed in its guide's manifest

0

broken internal links, unindexed docs files or unresolved paths in prose

3.2 s

for merlon check to compile and check all of this repository's docs

Measured by merlon check when this site was built on 2026-10-19, from commit bb3d832. The build stops when the check fails, so these figures always come from a passing run. The time is the median of three runs on the build machine, so it varies between builds.

The automated repository and validated surface field reports measure two other repositories, and record what the checks missed there.

• Versioned specification

  Merlon Docs 1.0 is written with RFC 2119 keywords, versioned apart from package releases.

• Public decisions

  Design choices are recorded as decision records, including the ideas that were turned down.

• Evidence policy

  Public copy follows a claims policy that bans unmeasured outcomes.

• Built with itself

  This site and the repository’s READMEs compile from Merlon Docs shards, checked in this repository’s CI.

Talks

DORA Community DiscussionAgent Skills and the Merlon Docs documentation system. Recording on YouTube.LA DevOps, July 30, 2026

Why Intent is the New Syntax. Introducing Merlon Docs. Event page.

FAQ

Questions

Does Merlon Docs keep docs in sync with the code automatically?

Not by itself. The CLI checks that docs refer to each other and to files correctly. Whether the prose still matches the code depends on an agent following the skill and a person reviewing the change.

Does Merlon Docs replace my other skills?

No. Helper skills plan, write, and review code. Merlon Docs records what the project needs to remember about that code. Install both.

Do I need the agent skill to use it?

No. The merlon CLI compiles and checks docs on its own in CI or locally. The skill adds the instructions an agent follows to update shards as it works.

Which agents does it work with?

Any host that supports Agent Skills, including Claude Code, Cursor, and GitHub Copilot.

Is Merlon Docs an MCP server?

No. The Model Context Protocol connects agents to live tools and data. Merlon Docs works on files in your repository and runs in CI. See scope and positioning.

Next steps

Start here

Learn Merlon Docs

A short path through the Agent Skill (Part 1), its workflows (Part 2), and the CLI (Part 3).

Part 1 · Read the Agent Skill (SKILL.md)Read the merlon-docs skill, its QA rules, and all six workflows directly.Part 3 · CLI install and quick startAdd the merlon CLI to a repository and run your first compile and check.Why Merlon Docs for coding agentsHow docs fail when agents edit a repository, and what Merlon Docs does about it.Read the specificationThe Merlon Docs 1.0 spec: guide layout, skill workflows, and agent context.ContributeSet up the monorepo, run the checks, and land a change.