Usage model
Operational roles in Merlon Docs.
Agent entrypoint
Section titled “Agent entrypoint”Agents should load the parent Agent Skill (/merlon-docs, installed in your agent’s skills directory via npx skills add) first. That skill teaches how to query with smallest context — discover one shard at a time — without loading entire guides. See Agent Skill.
Actors and obligations
Section titled “Actors and obligations”| Actor | Reads | Writes | Must run |
|---|---|---|---|
| Author (human/agent) | shards, Agent Skill | shards, manifest | check before PR |
| CI | config | — | check --require-lint when peers configured |
| Agent (context consumer) | Agent Skill, single shards (rg/IDE) |
— | — |
Authors can also run merlon prose locally to see Vale findings before CI does.
Shards are source of truth; compiled files are generated.
Adoption paths
Section titled “Adoption paths”Minimal
Section titled “Minimal”One guide that compiles to guide.md and passes check. Install the skill with its install command.
Typical
Section titled “Typical”Multi-guide compileOrder, publish outputs (compile.outputFile).
Agent-native
Section titled “Agent-native”Above plus the four-tier guide layout (features / client / developer / glossary), the merlon-docs skill’s workflows.
Coexistence
Section titled “Coexistence”Alternatives and adoption says what Merlon Docs adds beside site generators and host rules files. Scope and positioning explains why MCP sits on top of Merlon Docs instead of replacing it.
Query preference order
Section titled “Query preference order”- When the parent Agent Skill (
/merlon-docs) is available, load it with the task; the skill picks a workflow and runs intake forWORK_ITEM, as Skill workflows says - Find the shard with host search and read one shard, as refs says
- Rely on
merlon checkfor broken#cross-links (optionally inspectmerlon refs-list)
Read docs/skills.md for the skill and its workflow index.