Learn Merlon Docs

New to Merlon Docs? Work through this path from top to bottom, or jump to the step you need. Each step ends with somewhere to go next.

Start here

Merlon Docs comes in three parts. Part 1 is the Agent Skill (merlon-docs, which teaches your coding agent how to read, write, and review shards). Part 2 is the skill’s workflows, one for each kind of task. Part 3 is the CLI (merlon compile and merlon check, which build guides and validate links in CI). Read the Agent Skill directly first, or start with why documentation reliability matters.

Part 1 · Read the Agent Skill (SKILL.md)Read the merlon-docs skill instructions, hard rules, QA principles, and workflow router directly.Part 2 · Skill workflows and archetypesBrowse getting-started, doc-only, design-architecture, feature-level, ux, and doc-review workflows.Part 3 · CLI install and quick startAdd the merlon CLI to a repository and run merlon compile and merlon check.Documentation and software reliabilityWhat unreliable software costs, where documentation fits, and what Merlon Docs does about it.

1 · Understand the problem

Software failures cost hundreds of billions to trillions of dollars a year, and documentation is one of the causes a team can act on. When agents write much of the change, docs also break in a few familiar, structural ways.

Why Merlon Docs for coding agentsHow docs fail when agents edit a repository, and which command addresses each failure.Field report: a fully automated repositoryWhat the checks caught when agents wrote every commit, and what they missed.

2 · Understand the ideas

Start with the shard, then read how guides, the check and the skill build on it.

ShardA small Markdown file about one topic, which people and agents read and review.GuideA list of shards that compiles into the README or handbook one reader opens.Check

merlon check fails CI on broken links, unindexed shards and stale compiled files.

Agent SkillThe instructions an agent follows to update shards in the same change as the code.Usage modelHow people and agents read one shard at a time, and who checks what.

3 · Try it

Install the skill in your agent, or the CLI in your repository, and run a compile. The quick start takes a repository from no shards to a passing check.

npx skills add Merlon-Docs/merlon --skill merlon-docs

Part 1 · Get started with the Agent SkillInstall the merlon-docs skill, wire AGENTS.md, and start a bootstrap session.Part 3 · Install and quick start (CLI)Add the CLI, write your first shards, and run merlon compile and merlon check.Project layoutWhere shards, guides, and compiled output live in a repository.

4 · Measure it

How much context does an agent load? This repository measures a whole compiled guide against one shard. The figures are rough estimates. Every model and system tokenizes differently, so compare the sizes with each other, not with a bill.

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.

After pnpm build && pnpm docs:compile:repo, this command counts this repository’s docs with cl100k_base. With --no-write, it prints the table and doesn’t write a CSV:

pnpm bench:context-size --tokenizer cl100k_base --no-write

Benefit claims and evidenceWhat Merlon Docs may and may not claim from these figures.

5 · Compare to what you know

Already keep a long README, a wiki or an llms.txt file? See where Merlon Docs agrees, where it differs, and how it relates to the Model Context Protocol.

Alternatives and adoptionMerlon Docs next to single-file docs, docs sites and other conventions.Scope and positioningWhat Merlon Docs is and isn’t, including how it differs from an MCP server.

Where to next

Past the basics? Pick a direction.

Read the specificationThe Merlon Docs 1.0 specification, from the guide layout to agent context delivery.Decision recordsThe reasoning behind each design choice, including the ideas that were turned down.ContributeSet up the monorepo, run the checks and land a change.Watch a talkThe DORA Community Discussion on Agent Skills and the Merlon Docs documentation system.