Skip to content
Merlon Docs

What kind of Agent Skill is this?

On skills.sh you will find many task skills that teach an agent a repeatable procedure. Merlon Docs belongs to the family of foundational AI skills for durable context and documentation guardrails, alongside skills such as LLM Wiki (bootstrap, ingest, query, and lint a compounding Markdown wiki) and aDNA-style vaults (what, who, and how layout, AGENTS.md in each area, and procedural skill files in the vault’s how leg).

LLM Wiki and aDNA optimize for general knowledge or whole-vault organization across any domain. Merlon Docs optimizes for software projects in git: small validated shards next to source code, merlon compile to build single-file guides for review, and merlon check in CI so links, paths, and indexes stay sound as the code changes.

Comparison at a glance

Section titled “Comparison at a glance”
Pattern Primary focus Merlon Docs difference
LLM Wiki A compounding general-knowledge wiki you ingest sources into and query across sessions Shards live in your software repo next to code; validation checks orphans, repository file and directory links, and compiled outputs
aDNA vault General-purpose vault across any domain: what, who, and how directories with per-folder AGENTS.md Documentation-system skill + CLI; default Code Repository Archetype for features/, developer/, client/, glossary/
Cursor rules / lone AGENTS.md Host-native hints Product intent lives in shards, not only in host config; the skill enforces update docs before you change what they describe
Merlon Docs Long-lived software projects where humans and agents co-maintain specs, ADRs, runbooks, and API docs Agent Skill + merlon CLI; installs from skills.sh/Merlon-Docs/merlon

Merlon Docs can compile into READMEs, monoliths, or downstream site generators. It is not a replacement for Docusaurus or MkDocs when you only need a public website with no agent discipline. See Alternatives and adoption.

Text in git, visuals beside it

Section titled “Text in git, visuals beside it”

Merlon Docs is text-first: shards and merlon check cover Markdown structure, links, and compile. It does not edit Figma or Excalidraw files directly. Use a canvas MCP (Excalidraw, Figma, or your tool) alongside Merlon Docs: shards hold the durable wording and system facts; exported figures live in insert libraries and compile into the guides you review. Agents can read shards to populate or update a canvas, and update shards when the diagram changes. See Text-first content and canvas tools.

Who it is for (and who can skip it)

Section titled “Who it is for (and who can skip it)”

Merlon Docs is for people who operate or extend the software for the long haul: teammates who onboard later, agents that were not in last week’s chat, and you six months from now.

It is not aimed at the engineer who keeps the entire project scope in their head and sees no documentation debt. That can work for a while; Merlon Docs is for everyone else who pays when that knowledge is missing, and for leads who want guardrails so agents do not ship code without updating the shards that describe it. The personas page names this reader explicitly: Anti-persona: the engineer who keeps the system in their head.

Add it to your project (and wire AGENTS.md)

Section titled “Add it to your project (and wire AGENTS.md)”

  1. Install the skill and commit the copy so every teammate and agent shares the same discipline:

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

  2. Reference Merlon Docs in your project’s AGENTS.md (or CLAUDE.md, or your host’s equivalent). That file is what agents read first; pointing at the skill turns documentation from optional advice into project policy. Example lines you can adapt:

    ## Documentation
    

    This repository uses [Merlon Docs](https://github.com/Merlon-Docs/merlon). Shards under `docs/` are the source of truth; compiled READMEs are generated.
    

    - Install: `merlon-docs` skill (see `.agents/skills/merlon-docs` or your agent's skills directory).
    - For documentation work, invoke `/merlon-docs` before editing shards or product behavior.
    - After shard edits, run `merlon compile` and `merlon check` (or `pnpm docs:check` if wired in this repo). Compile builds the guides you review; check validates links and the docs tree, not whether the prose is factually correct.
    - Do not hand-edit files that contain `<!-- merlon-shard:` markers.

  3. Add the CLI to scripts or CI when you are ready: see Get started Path B, or let Path A’s bootstrap session wire it.

The skill does not replace AGENTS.md; it works with it. Host config says that documentation discipline exists; the skill says how to shard, compile, check, and review.

Where to go next

Section titled “Where to go next”