Documentation Authoring Hub (sk-doc)
One advisor identity, fifteen workflow modes across fourteen packets, one shared sk-create-quality-control backbone.
sk-doc is the parent hub for documentation and OpenCode-component authoring.
It holds NO per-packet logic: it routes by workflowMode through mode-registry.json, and each packet keeps its own contract in its nested folder.
The cross-cutting sk-create-quality-control pipeline (validators, global standards, frontmatter/llms/template assets) lives once in shared/ and is consumed by every packet.
Version authority. This file's version frontmatter is the hub's release version and matches the newest entry under changelog/; description.json, mode-registry.json and hub-router.json carry the same value, so every hub-root JSON routing file states the same release; ROUTER.md keeps its own document version.
1. WHEN TO USE
Use this skill for documentation and OpenCode-component authoring, and for document-quality work. The hub classifies the request, resolves a workflowMode, and loads the matching nested packet.
| Mode |
Use it for |
Packet |
Command |
| sk-create-skill |
Scaffold an OpenCode skill (and, via sk-create-skill-parent, a parent hub with nested mode packets) |
sk-create-skill/ |
/create:skill, /create:skill-parent |
| sk-create-readme |
Author a folder README, general or code-folder |
sk-create-readme/ |
/create:readme |
| sk-create-agent |
Scaffold an OpenCode agent (permission/authority frontmatter) |
sk-create-agent/ |
/create:agent |
| sk-create-command |
Scaffold an OpenCode slash command (argument-hint + allowed-tools + router/presentation split) |
sk-create-command/ |
/create:command |
| sk-create-feature-catalog |
Author a feature-catalog inventory package |
sk-create-feature-catalog/ |
/create:feature-catalog |
| sk-create-manual-testing-playbook |
Author a manual-testing-playbook package |
sk-create-manual-testing-playbook/ |
/create:manual-testing-playbook |
| sk-create-benchmark |
Author MCP-promotion and behavior packages or inputs |
sk-create-benchmark/ |
/create:benchmark |
| sk-create-changelog |
Author a global component changelog entry (version bump + topology-aware placement). Packet-local changelogs are deprecated |
sk-create-changelog/ |
/create:changelog |
| sk-create-diff |
Produce a local, Git-free before/after review of an edited document (text/Markdown/HTML/DOCX/text-PDF) as a self-contained HTML report |
sk-create-diff/ |
/create:diff |
| sk-create-repo-rule |
Create, revise or retire a repo-local rule under repo-rules/ and wire it into REPO RULES.md (four decision tests refuse most requests) |
sk-create-repo-rule/ |
/create:repo-rule |
| sk-create-with-human-voice |
Apply the Human Voice Rules to prose, or score prose against them, with a scope gate and a re-scan |
sk-create-with-human-voice/ |
/create:with-human-voice |
| sk-create-frontmatter |
Own the YAML frontmatter contract: per-class field rules, the description budget, and the 4-part version derivation |
sk-create-frontmatter/ |
— (routes via aliases) |
| sk-create-goal |
Author or revise a packet goal.md: the durable directive, three to seven self-contained completion criteria, and the phase-parent binding table (session-goal setting stays with the goal hooks) |
sk-create-goal/ |
/create:goal |
| sk-create-quality-control |
Validate / score / optimize an EXISTING document (extract → DQI → HVR → validate) |
sk-create-quality-control/ |
(routes via aliases) |
When NOT to Use
- Code implementation, tests, or debugging — use
sk-code.
- Git worktree, branch, commit, PR, or release work — use
sk-git.
- Spec-folder workflow / memory / save context — use
system-spec-kit.
- A measured Style Reference (design tokens extracted from a live source) — use
sk-design-md-generator.
- The
shared/ backbone is consumed by the packets, not invoked as a user workflow.
2. SMART ROUTING
Routing is registry-driven at runtime and authored in hub-router.json in two stages.
Stage 1 (hub → mode) selects a mode: hub-router.json vocabularyClasses is the one authored routing vocabulary.
The mode-registry.json aliases, each packet's Keyword triggers: line and the root ROUTER.md intents are checked against it.
sk-create-skill/scripts/ci-hub-vocabulary-source.cjs fails on the alias, stage-two, triggers and packets legs; its stage-two-reverse leg only reports.
Stage 2 (mode → leaves) lives in the root ROUTER.md, which maps the request's authoring intent to the packet-local leaf resources that mode loads.
The two layers stay separate: the hub never emits leaf paths, and the surface router never re-decides the mode.
The advisor routes every documentation and authoring query to the single identity sk-doc.
Resolve the mode with node .skilled/bin/compiled-route.cjs --hub sk-doc --prompt "<task>".
Act on the decision: route loads its targets, clarify and defer ask, reject refuses.
Compiled routing is the default.
An unclear documentation intent asks for disambiguation, because routerPolicy.defaultMode is null.
Run the compiled-routing directive in ROUTER.md before selecting hub resources.
3. HOW IT WORKS
Terms
workflowMode: the public packet key a request resolves to, such as sk-create-skill.
packetKind: workflow for every sk-doc packet, because this hub has no surface axis.
backendKind: template-scaffold for the create-* generators and sk-create-quality-control for the quality-control mode.
- packet: a nested
sk-create-* folder that keeps its own authoring contract, references, assets and scripts.
mode-registry.json: the registry that owns each packet's discriminator, aliases, command and advisorRouting.
hub-router.json: stage one's signals, vocabulary classes, default fallback resource and bundle rules.
vocabularyClasses: the one authored routing vocabulary that the registry aliases, the Keyword triggers: lines and the ROUTER.md intents are checked against.
ROUTER.md: stage two's INTENT_SIGNALS and RESOURCE_MAP, which map an authoring intent to the packet-local leaf resources its mode loads.
- leaf: a canonical
(workflowMode, leafResourceId) pair from leaf-manifest.json that a RESOURCE_MAP path converts to.
defer: the outcome that asks for disambiguation, which this hub reaches because routerPolicy.defaultMode is null.
- shared backbone: the
shared/ copy of the sk-create-quality-control pipeline that every packet consumes.
graph-metadata.json: the one advisor identity for the whole skill, which no packet or shared/ directory carries.
Layout
sk-doc/
SKILL.md # this routing hub (no per-packet logic)
ROUTER.md # stage-two surface router (authoring intent -> leaf sets)
mode-registry.json # the fifteen-mode discriminator + advisorRouting (single source of truth)
hub-router.json # router signals + vocabulary classes
description.json # hub advisor descriptor
graph-metadata.json # the ONE advisor identity for the whole skill
changelog/ manual-testing-playbook/ benchmark/ feature-catalog/
sk-create-skill/ sk-create-readme/ sk-create-agent/ sk-create-command/
sk-create-feature-catalog/ sk-create-manual-testing-playbook/
sk-create-benchmark/ sk-create-changelog/ sk-create-diff/
sk-create-repo-rule/ sk-create-frontmatter/ sk-create-goal/
sk-create-with-human-voice/ sk-create-quality-control/ # nested workflow packets
scripts/ # facade symlinks -> shared/ + owning packets (tool paths only)
shared/ # sk-create-quality-control backbone: validators, global standards, shared assets
Each packet is self-contained (its own SKILL.md, README.md, changelog/, and moved references//assets//scripts/) and carries no graph-metadata.json, so the advisor discovers exactly one sk-doc identity.
Shared backbone
shared/ holds the universal sk-create-quality-control pipeline consumed by every packet:
- Generic validator scripts in
shared/scripts/.
- Cross-cutting standards and vocabulary in
shared/references/.
- Shared templates in
shared/assets/.
The generic validator shared/scripts/cite-drift-scan.mjs counts and resolves the <path>.<ext>:<line> citations in every tracked skill doc.
It makes zero model calls by default.
--jev runs the backend and needs --out <dir>, so every call is recorded, and the Jev arm and the advisory live in the sibling shared/scripts/classifier-cite-drift-scan.mjs.
validate_document.py runs the same check as a non-blocking advisory on the document it validates.
It prints cite-drift advisory: lines only when a Jev credential is stored, never changes the exit code, and JEV_FEATURE_CITE_DRIFT=0 (older name: SKDOC_CITE_DRIFT_CHECK=0) skips it.
The sk-doc/scripts/ root directory keeps facade symlinks pointing inward to shared/ and the owning packets so tool paths resolve.
There are no hub-root assets/ or references/ aggregation directories: consumers reference each packet's own assets//references/ or the shared/ backbone directly.
4. RULES
✅ ALWAYS
- ALWAYS resolve a packet through
mode-registry.json; never hardcode a router mapping in the hub.
- ALWAYS keep authoring contracts in the packets; the hub stays routing-only.
- ALWAYS keep exactly one
graph-metadata.json (this hub's) so the advisor sees one identity.
- ALWAYS keep the root
ROUTER.md RESOURCE_MAP in sync with leaf-manifest.json and leaf-aliases.json — the leaf sets dual-read to canonical typed pairs at the one contract boundary.
- ALWAYS keep the sk-create-quality-control pipeline as one shared source under
shared/, consumed by the packets.
- ALWAYS keep changelogs as real files at the hub and in each packet — never symlinked.
⛔ NEVER
- NEVER add a
graph-metadata.json inside a packet or shared/.
- NEVER put per-packet authoring logic in the hub.
- NEVER add a surface axis or a
surfaceBundle outcome — sk-doc is workflow-only.
⚠️ ESCALATE IF
- A new documentation workflow is needed — extend
mode-registry.json and open a packet; do not bolt logic onto the hub.
- A packet would become a near-empty shell (generic doctrine, no type-specific behavior) — fold it into
shared/ instead.
5. REFERENCES
- Registry:
mode-registry.json (fifteen modes across fourteen packets, packetKind: workflow).
- Hub router:
hub-router.json (signals + vocabulary classes).
- Surface router:
ROUTER.md (authoring intent to packet-local leaf sets).
- Advisor descriptor:
description.json; skill-graph identity: graph-metadata.json.
- Packets:
sk-create-skill/, sk-create-readme/, sk-create-agent/, sk-create-command/, sk-create-feature-catalog/, sk-create-manual-testing-playbook/, sk-create-benchmark/, sk-create-changelog/, sk-create-diff/, sk-create-repo-rule/, sk-create-frontmatter/, sk-create-goal/, sk-create-with-human-voice/, sk-create-quality-control/.
- Shared backbone:
shared/scripts/, shared/references/, shared/assets/.
- Parent-skill pattern:
sk-create-skill/references/parent-skill/parent-skills-nested-packets.md.
1---2name: sk-doc3description: "Documentation & component authoring hub: skills, agents, commands, READMEs, catalogs, playbooks, changelogs, goals, frontmatter."4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 2.9.15.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-doc8 family: sk-util9---1011<!-- Keywords: sk-doc, documentation, markdown, authoring, parent-hub, mode-registry, hub-router, workflowmode, packetkind, sk-create-skill, sk-create-readme, sk-create-agent, sk-create-command, sk-create-feature-catalog, sk-create-manual-testing-playbook, sk-create-benchmark, sk-create-changelog, sk-create-diff, sk-create-repo-rule, sk-create-frontmatter, sk-create-goal, sk-create-with-human-voice, sk-create-quality-control, human-voice-rules, hvr, shared-backbone, create-quality-control-pipeline -->1213# Documentation Authoring Hub (sk-doc)1415One advisor identity, fifteen workflow modes across fourteen packets, one shared sk-create-quality-control backbone.16`sk-doc` is the parent hub for documentation and OpenCode-component authoring.17It holds NO per-packet logic: it routes by `workflowMode` through `mode-registry.json`, and each packet keeps its own contract in its nested folder.18The cross-cutting sk-create-quality-control pipeline (validators, global standards, frontmatter/llms/template assets) lives once in `shared/` and is consumed by every packet.1920**Version authority.** This file's `version` frontmatter is the hub's release version and matches the newest entry under `changelog/`; `description.json`, `mode-registry.json` and `hub-router.json` carry the same value, so every hub-root JSON routing file states the same release; `ROUTER.md` keeps its own document version.2122---2324## 1. WHEN TO USE2526Use this skill for documentation and OpenCode-component authoring, and for document-quality work. The hub classifies the request, resolves a `workflowMode`, and loads the matching nested packet.2728| Mode | Use it for | Packet | Command |29|------|------------|--------|---------|30| **sk-create-skill** | Scaffold an OpenCode skill (and, via `sk-create-skill-parent`, a parent hub with nested mode packets) | `sk-create-skill/` | `/create:skill`, `/create:skill-parent` |31| **sk-create-readme** | Author a folder README, general or code-folder | `sk-create-readme/` | `/create:readme` |32| **sk-create-agent** | Scaffold an OpenCode agent (permission/authority frontmatter) | `sk-create-agent/` | `/create:agent` |33| **sk-create-command** | Scaffold an OpenCode slash command (argument-hint + allowed-tools + router/presentation split) | `sk-create-command/` | `/create:command` |34| **sk-create-feature-catalog** | Author a feature-catalog inventory package | `sk-create-feature-catalog/` | `/create:feature-catalog` |35| **sk-create-manual-testing-playbook** | Author a manual-testing-playbook package | `sk-create-manual-testing-playbook/` | `/create:manual-testing-playbook` |36| **sk-create-benchmark** | Author MCP-promotion and behavior packages or inputs | `sk-create-benchmark/` | `/create:benchmark` |37| **sk-create-changelog** | Author a global component changelog entry (version bump + topology-aware placement). Packet-local changelogs are deprecated | `sk-create-changelog/` | `/create:changelog` |38| **sk-create-diff** | Produce a local, Git-free before/after review of an edited document (text/Markdown/HTML/DOCX/text-PDF) as a self-contained HTML report | `sk-create-diff/` | `/create:diff` |39| **sk-create-repo-rule** | Create, revise or retire a repo-local rule under `repo-rules/` and wire it into `REPO RULES.md` (four decision tests refuse most requests) | `sk-create-repo-rule/` | `/create:repo-rule` |40| **sk-create-with-human-voice** | Apply the Human Voice Rules to prose, or score prose against them, with a scope gate and a re-scan | `sk-create-with-human-voice/` | `/create:with-human-voice` |41| **sk-create-frontmatter** | Own the YAML frontmatter contract: per-class field rules, the description budget, and the 4-part `version` derivation | `sk-create-frontmatter/` | — (routes via aliases) |42| **sk-create-goal** | Author or revise a packet `goal.md`: the durable directive, three to seven self-contained completion criteria, and the phase-parent binding table (session-goal setting stays with the goal hooks) | `sk-create-goal/` | `/create:goal` |43| **sk-create-quality-control** | Validate / score / optimize an EXISTING document (extract → DQI → HVR → validate) | `sk-create-quality-control/` | (routes via aliases) |4445### When NOT to Use46- Code implementation, tests, or debugging — use `sk-code`.47- Git worktree, branch, commit, PR, or release work — use `sk-git`.48- Spec-folder workflow / memory / save context — use `system-spec-kit`.49- A measured Style Reference (design tokens extracted from a live source) — use `sk-design-md-generator`.50- The `shared/` backbone is consumed by the packets, not invoked as a user workflow.5152---5354## 2. SMART ROUTING5556Routing is **registry-driven at runtime and authored in `hub-router.json`** in two stages.57Stage 1 (hub → mode) selects a mode: `hub-router.json` `vocabularyClasses` is the one authored routing vocabulary.58The `mode-registry.json` aliases, each packet's `Keyword triggers:` line and the root `ROUTER.md` intents are checked against it.59`sk-create-skill/scripts/ci-hub-vocabulary-source.cjs` fails on the `alias`, `stage-two`, `triggers` and `packets` legs; its `stage-two-reverse` leg only reports.60Stage 2 (mode → leaves) lives in the root [`ROUTER.md`](./ROUTER.md), which maps the request's authoring intent to the packet-local leaf resources that mode loads.61The two layers stay separate: the hub never emits leaf paths, and the surface router never re-decides the mode.62The advisor routes every documentation and authoring query to the single identity `sk-doc`.63Resolve the mode with `node .skilled/bin/compiled-route.cjs --hub sk-doc --prompt "<task>"`.64Act on the decision: `route` loads its `targets`, `clarify` and `defer` ask, `reject` refuses.65Compiled routing is the default.66An unclear documentation intent asks for disambiguation, because `routerPolicy.defaultMode` is `null`.67Run the compiled-routing directive in [`ROUTER.md`](./ROUTER.md) before selecting hub resources.6869---7071## 3. HOW IT WORKS7273### Terms7475- **`workflowMode`**: the public packet key a request resolves to, such as `sk-create-skill`.76- **`packetKind`**: `workflow` for every sk-doc packet, because this hub has no surface axis.77- **`backendKind`**: `template-scaffold` for the create-* generators and `sk-create-quality-control` for the quality-control mode.78- **packet**: a nested `sk-create-*` folder that keeps its own authoring contract, references, assets and scripts.79- **`mode-registry.json`**: the registry that owns each packet's discriminator, aliases, command and `advisorRouting`.80- **`hub-router.json`**: stage one's signals, vocabulary classes, default fallback resource and bundle rules.81- **`vocabularyClasses`**: the one authored routing vocabulary that the registry aliases, the `Keyword triggers:` lines and the `ROUTER.md` intents are checked against.82- **`ROUTER.md`**: stage two's `INTENT_SIGNALS` and `RESOURCE_MAP`, which map an authoring intent to the packet-local leaf resources its mode loads.83- **leaf**: a canonical `(workflowMode, leafResourceId)` pair from `leaf-manifest.json` that a `RESOURCE_MAP` path converts to.84- **`defer`**: the outcome that asks for disambiguation, which this hub reaches because `routerPolicy.defaultMode` is `null`.85- **shared backbone**: the `shared/` copy of the sk-create-quality-control pipeline that every packet consumes.86- **`graph-metadata.json`**: the one advisor identity for the whole skill, which no packet or `shared/` directory carries.8788### Layout89```90sk-doc/91 SKILL.md # this routing hub (no per-packet logic)92 ROUTER.md # stage-two surface router (authoring intent -> leaf sets)93 mode-registry.json # the fifteen-mode discriminator + advisorRouting (single source of truth)94 hub-router.json # router signals + vocabulary classes95 description.json # hub advisor descriptor96 graph-metadata.json # the ONE advisor identity for the whole skill97 changelog/ manual-testing-playbook/ benchmark/ feature-catalog/98 sk-create-skill/ sk-create-readme/ sk-create-agent/ sk-create-command/99 sk-create-feature-catalog/ sk-create-manual-testing-playbook/100 sk-create-benchmark/ sk-create-changelog/ sk-create-diff/101 sk-create-repo-rule/ sk-create-frontmatter/ sk-create-goal/102 sk-create-with-human-voice/ sk-create-quality-control/ # nested workflow packets103 scripts/ # facade symlinks -> shared/ + owning packets (tool paths only)104 shared/ # sk-create-quality-control backbone: validators, global standards, shared assets105```106107Each packet is self-contained (its own `SKILL.md`, `README.md`, `changelog/`, and moved `references/`/`assets/`/`scripts/`) and carries **no** `graph-metadata.json`, so the advisor discovers exactly one `sk-doc` identity.108109### Shared backbone110`shared/` holds the universal sk-create-quality-control pipeline consumed by every packet:111- Generic validator scripts in `shared/scripts/`.112- Cross-cutting standards and vocabulary in `shared/references/`.113- Shared templates in `shared/assets/`.114115The generic validator `shared/scripts/cite-drift-scan.mjs` counts and resolves the `<path>.<ext>:<line>` citations in every tracked skill doc.116It makes zero model calls by default.117`--jev` runs the backend and needs `--out <dir>`, so every call is recorded, and the Jev arm and the advisory live in the sibling `shared/scripts/classifier-cite-drift-scan.mjs`.118`validate_document.py` runs the same check as a non-blocking advisory on the document it validates.119It prints `cite-drift advisory:` lines only when a Jev credential is stored, never changes the exit code, and `JEV_FEATURE_CITE_DRIFT=0` (older name: `SKDOC_CITE_DRIFT_CHECK=0`) skips it.120The `sk-doc/scripts/` root directory keeps facade symlinks pointing inward to `shared/` and the owning packets so tool paths resolve.121There are no hub-root `assets/` or `references/` aggregation directories: consumers reference each packet's own `assets/`/`references/` or the `shared/` backbone directly.122123---124125## 4. RULES126127### ✅ ALWAYS128- **ALWAYS** resolve a packet through `mode-registry.json`; never hardcode a router mapping in the hub.129- **ALWAYS** keep authoring contracts in the packets; the hub stays routing-only.130- **ALWAYS** keep exactly one `graph-metadata.json` (this hub's) so the advisor sees one identity.131- **ALWAYS** keep the root `ROUTER.md` `RESOURCE_MAP` in sync with `leaf-manifest.json` and `leaf-aliases.json` — the leaf sets dual-read to canonical typed pairs at the one contract boundary.132- **ALWAYS** keep the sk-create-quality-control pipeline as one shared source under `shared/`, consumed by the packets.133- **ALWAYS** keep changelogs as real files at the hub and in each packet — never symlinked.134135### ⛔ NEVER136- **NEVER** add a `graph-metadata.json` inside a packet or `shared/`.137- **NEVER** put per-packet authoring logic in the hub.138- **NEVER** add a surface axis or a `surfaceBundle` outcome — sk-doc is workflow-only.139140### ⚠️ ESCALATE IF141- A new documentation workflow is needed — extend `mode-registry.json` and open a packet; do not bolt logic onto the hub.142- A packet would become a near-empty shell (generic doctrine, no type-specific behavior) — fold it into `shared/` instead.143144---145146## 5. REFERENCES147148- Registry: `mode-registry.json` (fifteen modes across fourteen packets, `packetKind: workflow`).149- Hub router: `hub-router.json` (signals + vocabulary classes).150- Surface router: `ROUTER.md` (authoring intent to packet-local leaf sets).151- Advisor descriptor: `description.json`; skill-graph identity: `graph-metadata.json`.152- Packets: `sk-create-skill/`, `sk-create-readme/`, `sk-create-agent/`, `sk-create-command/`, `sk-create-feature-catalog/`, `sk-create-manual-testing-playbook/`, `sk-create-benchmark/`, `sk-create-changelog/`, `sk-create-diff/`, `sk-create-repo-rule/`, `sk-create-frontmatter/`, `sk-create-goal/`, `sk-create-with-human-voice/`, `sk-create-quality-control/`.153- Shared backbone: `shared/scripts/`, `shared/references/`, `shared/assets/`.154- Parent-skill pattern: `sk-create-skill/references/parent-skill/parent-skills-nested-packets.md`.