mdcp

MDCP (parent skill)

Host-agnostic documentation system Agent Skill for MDCP. Prefer this over IDE extensions when you want durable, sharded docs that agents and humans can maintain as ideas keep coming.

This parent skill is the intended agent entrypoint. Complementary archetype skills extend it for specific documentation architectures.

Install help: references/install.md. What compile / check / refs mean and CLI commands: references/cli-and-scripts.md.

Hard rules

• NEVER invent MDCP workflow when this skill already defines it — follow the skill first.
• NEVER hand-edit files in a vendor-managed install under your agent’s skills

directory (for example .agents/skills/ in Cursor/Amp) for repo-specific guidance — use complementary skills, docs/extensions/, or normative shards.

• NEVER edit generated compile output (docs/_build/, compiled publish

targets) — fix shards and recompile.

• NEVER dump whole monoliths into context — discover with host search (rg,

IDE search), then read one shard at a time.

• NEVER write functional product code for a docs/feature change without

docs-first shards when the repo follows that convention.

• ALWAYS run mdcp check (or docs:check) before trusting compiled output.

Quality Assurance (QA) Principles

When applying MDCP, act as a complementary partner to other skills and systems. These habits keep docs trustworthy while the product keeps changing:

• Always reference doc shards: Insert yourself into the process so the

current task points at the correct documentation shards before work spreads.

• Update as you go: Continuously update documentation as work progresses so

shards and code do not drift apart mid-change.

• Small batches / one focused feature: Prefer one shippable slice per branch

or session. Oversized requests produce tangled diffs and half-updated docs; split the request (and the shards) before coding so each change stays reviewable and documentation can stay current with it. Pair with Atomic commit groups below when the plan has more than one logical change.

• Atomic commit groups: Before waiting for human review / “go”, coding and

multi-concern plans MUST include numbered commit groups. Each group: id/name, one concern, exact files, and the intended conventional commit subject. After approval: implement and git commit one group at a time; do not squash unrelated concerns into one commit. Why: reviewable diffs, one concern per commit, and it matches small batches.

• Current docs only: Shards must describe the product as it works now.

When behavior or guidance changes, remove superseded or stale text from durable docs — do not leave “old way” sections for archaeology. Git history preserves prior wording; consumer notice of breaking or removed behavior belongs in the changeset (folded into package CHANGELOGs at release), not in feature/client/developer shards. Never link durable shards or ADRs to pending .changeset/*.md files — those notes are temporary.

• Capture ambiguity: Identify ambiguous terms or language and write the

clarified details into specific shards.

• Shard single responsibility: Each durable shard has one primary concern,

for one audience tier, serving one job (explain or instruct how-to or define/look up — not several). If you cannot state that responsibility in one sentence, split or narrow the shard before shipping it. Depth: references/shard-responsibility.md.

• Idea mitosis: When a shard grows a second audience, job, or concern —

or reading it alone misleads — split it, update the guide index, and cross-link. Do not split only because a file is long. Unsettled discovery and time-bound notes do not share a file with durable current truth.

• Break it down: Organize information into the smallest useful pieces

(shards) so agents can load one shard at a time instead of drowning in monoliths. Prefer mitosis over mini-monoliths.

• Two-level review: Review each changed idea or shard in isolation for

local correctness and single responsibility. Then review it comprehensively against related shards and guides — flag duplication, better splits/merges/relocations, and drift between what guides promise and what the change does. When a change touches a guide (a shard, a skill, or code whose behavior a guide documents), the review is complete only when the change and its guides agree.

• No code in docs: Put intent, contracts, and acceptance criteria in

shards — not implementation. Code samples and internals drift; the codebase is the source of truth for how something is built. This matches What belongs where below.

• No temp info or backlogs: Do not record temporary project information,

tickets, incident logs, or migration backlogs and planning in the durable documentation. That information belongs in issue tracking and project planning tools. Pending .changeset/*.md files are temporary release notes — write them for the release pipeline; do not link them from ADRs or other durable docs.

• Record planning locations: Record where planning documents and

architectural decisions live so agents can find them without stuffing plans into durable product shards.

What belongs where

Documentation is a first-class artifact alongside code. We use a spec-driven workflow: shards hold context, intent, and the high-level meta plan; implementation details stay in code.

The default MDCP structure acts as the "batteries-included" Code Repository Archetype. This fundamental four-tier taxonomy enforces strict boundaries to prevent the docs system from falling apart as it scales:

Placement test: If only contributors to this repo need the shard, put it in docs/developer/. If consumers of the product need it, use docs/features/ or docs/client/. The same topic may span tiers (for example Agent Skill product delivery vs maintainer live evals). Placement is one axis of shard single responsibility; if consumer and contributor needs collide in one file, use idea mitosis.

(Note: The MDCP engine itself is domain-agnostic. Non-code projects can define entirely different guide tiers/archetypes while still using the same compile and validation checks. Lineage for external frameworks: [references/acknowledgments.md](references/acknowledgments.md).)

Authoring rules

• Shards under docs/**/ are the source of truth.
• Use # headings in shards; mdcp demotes them during compile.
• After changing a guide's link order (e.g., in index.md), run mdcp compile — there is no separate manifest sync step.
• After inserting [text](#slug) cross-links, run mdcp check so fragments match compiled slugs (use mdcp refs list if you need to inspect the registry).

When to use

• PROACTIVELY on ANY feature, bugfix, or architectural task: MDCP must be involved in the entire process. Before writing code, trace the requirement back to documentation. Consider the end-user problems and ensure helpful docs exist or are created.
• Authoring or refactoring sharded markdown under a docs root
• Bootstrapping MDCP agent guidance (install parent skill first)
• Cross-links / refs while writing docs
• Extending guidance via complementary skills or local docs/extensions/ when needed

Execution steps

1. Prefer the parent skill

1. Follow this skill’s workflow.
2. Install / rediscover via:

npx skills add betsalel-williamson/mdcp --skill mdcp

2. Prefer smallest context

Discover the relevant shard with host search (rg, IDE search) or the guide index.md, then open one .md shard. Broader compiled monolith reads are last resort.

3. Edit shards, then validate

1. Edit shards under guides in compileOrder.
2. Update index.md / shards.md when adding files.
3. Build compiled docs from shards, then validate the docs tree

(see references/cli-and-scripts.md for what these mean):

mdcp compile
mdcp check

4. Code Formatting and Linting

If the user asks to set up formatting or linting, they should install prettier, markdownlint-cli2, and @bwilliamson/mdcp-presets via their package manager. (Note: MDCP is flexible; if the user prefers other formatting or linting tools, you can integrate those instead.)

To automatically format documents using the default tools:

mdcp fix

To run prose linting (requires Vale):

mdcp prose

5. Helper Commands

Task-type instructions live in independent helper skills. Once the MDCP CLI is installed, you can invoke these helpers directly.

Helper routing (task → skill → artifacts): Pick one helper for the current WORK_ITEM (one focused batch per branch). Edit only the artifact paths that helper owns; keep shards current; put no implementation code in durable docs; run mdcp check before trusting compiled output.

flowchart TB
  Q{What kind of work?}

  Q -->|Bootstrap MDCP in a repo| GS[mdcp-getting-started]
  Q -->|Docs / technical writing only| DO[mdcp-doc-only]
  Q -->|ADR / RFC / high-level design| DA[mdcp-design-architecture]
  Q -->|Feature: docs-first then TDD| FL[mdcp-feature-level]
  Q -->|UX / end-user experience| UX[mdcp-ux]

  GS --> GSa["docs/features/, docs/client/, docs/developer/, docs/glossary/<br/>+ mdcp.config.json + skill install"]
  DO --> DOa["docs/features/, docs/client/, docs/developer/<br/>(no product code unless WORK_ITEM says so)"]
  DA --> DAa["docs/features/ (incl. protocol / ADRs)<br/>design shards only"]
  FL --> FLa["docs/features/, docs/client/<br/>then source + tests"]
  UX --> UXa["docs/client/<br/>then UI as needed"]

Bootstrap example:

/mdcp-getting-started

Hosts that can fork work (Task tool, context: fork, and similar) may run the chosen helper in an isolated agent; otherwise follow it in the main session.

When no mdcp.config.json yet: create docs root + config + guide dirs, install the parent skill via npx skills add betsalel-williamson/mdcp --skill mdcp (see references/install.md), optionally add @bwilliamson/mdcp-presets, then compile and check.

Zero-install

Copy the mdcp skill folder into the skills directory your agent discovers (see skills CLI Supported Agents). For example .agents/skills/mdcp/ for Cursor/Amp project installs — not a universal portable path.