Code Family Hub (sk-code)
One skill has two axes, one shared surface-detection router and one advisor identity.
The workflow axis has two code modes that act: sk-code-quality and sk-code-review.
The surface axis has three read-only evidence packets the hub bundles alongside a workflow mode: sk-code-ci, sk-code-frontend and sk-code-skilled.
Each packet carries the shared implement → debug → verify workflow doctrine (shared/references/workflow-*.md, symlinked in) plus its own domain knowledge.
This hub holds NO per-mode logic. It routes by workflowMode through mode-registry.json, and each mode or surface keeps its own contract in its 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. Each hub-root JSON routing file therefore states the same release.
ROUTER.md and README.md keep their own document versions, as the frontmatter-versioning standard gives every doc but SKILL.md.
The authority stops at the hub root. Each modes[] packet carries its own version and release cadence.
A packet version is independent of this one by design, so a gap between them is not drift.
1. WHEN TO USE
Use this skill for code-family workflows. Invoke it as sk-code with an optional mode hint such as quality: <request>. The hub classifies the request, resolves a mode key, and loads the matching nested packet.
Workflow axis (modes that act, one of them chosen as primary):
| Mode |
Use it for |
Packet |
| sk-code-quality |
Quality gate, P0/P1/P2 author checks, comment hygiene and surface checklists. |
sk-code/sk-code-quality/ |
| sk-code-review |
Findings-first review, security and correctness baseline, checklists, output contract and PR-state gates. |
sk-code/sk-code-review/ |
Surface axis (read-only, advisor-invisible evidence. When a workflow mode scores, the hub bundles the surface after that primary mode. When no workflow mode scores, the hub routes the surface alone for a lookup, implement, debug or verify task, and the acting agent hands the author gates to sk-code-quality before it claims completion):
| Surface |
Carries |
Packet |
| sk-code-ci |
GitHub Actions evidence: trigger, filter, permission, timeout, concurrency and caching rules, the protected set, the intentional message-contract exception and the scaffold templates, with the repository-specific values read from a CI profile. Read-only. |
sk-code/sk-code-ci/ |
| sk-code-frontend |
Stack-agnostic frontend evidence: web markup and CSS, web layout and accessibility, visual values, visual hierarchy and review, motion and interaction, the tokens.css starter tokens and Figma-to-code checks. Read-only. |
sk-code/sk-code-frontend/ |
| sk-code-skilled |
System-code evidence: TypeScript/Python/shell/config standards, hooks, alignment verification, authoring checklists. Bundles the implement → debug → verify workflow doctrine (read-only evidence) for the Skilled surface, and the acting agent applies it. |
sk-code/sk-code-skilled/ |
Surface list. The hub has exactly three surfaces:
- SKILLED (
sk-code-skilled): the native surface for this framework's own code.
- CI (
sk-code-ci): the GitHub Actions workflow standards surface.
- Frontend (
sk-code-frontend): the stack-agnostic web practice and Figma-to-code surface, with visual values, visual hierarchy and review, and motion and interaction guidance, selected by its FRONTEND file markers or bundled from request vocabulary.
The hub also has two workflow modes: quality (sk-code-quality) and review (sk-code-review).
Any other sk-code doc that counts surfaces points to this sentence.
When NOT to Use
- Documentation-only changes with no code-work contract - use
sk-doc.
- Git workflow, branch, commit, PR, merge, or release work - use
sk-git.
- Pure browser inspection or external MCP transport work - use the relevant MCP skill.
- For a measured Style Reference (design tokens extracted from a live source), use
sk-design-md-generator first.
- When a request or a frame leaves a visual value open (spacing, type, color, radius, shadow or motion), or a value sits off every token and scale, load
sk-code-frontend and decide it from its visual-values reference.
- Backend support primitives in
shared/ - they are consumed by the modes, 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) uses hub-router.json as the authored mode vocabulary. mode-registry.json carries the packet contracts, whose aliases are checked against that vocabulary.
Stage 2 (mode → leaves) uses the root ROUTER.md as the authored leaf-set router.
Both files point back here instead of restating the split.
The advisor routes every code query to the single identity sk-code. Resolve the mode with node .skilled/bin/compiled-route.cjs --hub sk-code --prompt "<task>" and follow the decision: route loads its targets, clarify and defer ask, reject refuses.
Compiled routing is the default. The legacy fallback, the kill-switch and the UNKNOWN_FALLBACK_CHECKLIST live in the compiled-routing section of ROUTER.md.
A bare implement, debug or verify request with no workflow mode becomes a pure surface bundle, and an unclear code intent asks for disambiguation. Neither path forces a stale default.
Run the compiled-routing directive in ROUTER.md before selecting hub resources.
3. HOW IT WORKS
Terms
workflowMode: the public mode or surface key a request resolves to.
packetKind: the axis a packet sits on, workflow for a mode that acts and surface for read-only evidence bundled alongside a mode.
backendKind: which backend runs the packet, surface-router or review-cache for a workflow mode and evidence-base for a surface.
surfaceBundle: the routerPolicy.outcomes entry where one workflow mode leads and zero or more surfaces follow as evidence.
mode-registry.json: the registry that owns each mode's discriminator, surfaceDetection markers and advisorRouting.
hub-router.json: stage one's routerSignals, vocabularyClasses and the surface-bundling policy.
ROUTER.md: stage two's INTENT_SIGNALS and RESOURCE_MAP, plus the SHARED_CONTROL_RESOURCES list and the always-loaded DEFAULT_RESOURCE preamble.
- shared control: a hub-level resource declared in
SHARED_CONTROL_RESOURCES, which resolves on disk and never projects as a leaf.
- leaf: a typed
(workflowMode, leafResourceId) pair from leaf-manifest.json that a RESOURCE_MAP path converts to.
- surface detection: the shared detection order over the declared surfaces, which tries each specific surface first, then the
SKILLED fallback, then UNKNOWN.
--surface-hint: the front-door flag that carries the detected surface into the compiled route, so a hinted surface leads a keyword tie.
UNKNOWN_FALLBACK: the load level the router returns, with a disambiguation checklist, when no mode resolves.
Layout
sk-code/
SKILL.md # this routing hub (no per-mode code logic)
README.md # human-facing front page for the hub
ROUTER.md # active stage-two surface router and shared-control declaration
mode-registry.json # the two-axis discriminator + advisorRouting contract
hub-router.json # lexical routing signals + surfaceBundle policy for hub-local choice
description.json # hub advisor descriptor
graph-metadata.json # the ONE advisor identity for the whole skill
leaf-manifest.json # typed (workflowMode, leaf) pairs the router guards validate
changelog/ # hub release notes, one v<version>.md per hub release
feature-catalog/ # current-state inventory of the hub's routing capabilities
manual-testing-playbook/ # routing and disambiguation scenarios for the hub
benchmark/ # historical routing benchmark inputs and reports
sk-code-quality/ # quality mode packet (workflow)
sk-code-review/ # review mode packet (workflow)
sk-code-ci/ # GitHub Actions workflow standards packet (read-only evidence; rules, protected set and scaffold templates)
sk-code-frontend/ # stack-agnostic web and Figma-to-code evidence packet (read-only; references/web-visual-values.md, web-visual-hierarchy.md and web-motion-and-interaction.md plus assets/tokens.css)
sk-code-skilled/ # skilled surface packet (read-only evidence; carries the workflow doctrine)
shared/ # shared surface-detection router, cross-mode helpers, and the implement/debug/verify workflow doctrine (references/workflow-*.md)
Each mode or surface packet is self-contained and carries no per-packet graph-metadata.json. Only this hub carries one, so the advisor discovers exactly one code skill identity. The implement/debug/verify workflow doctrine is a single shared source under shared/references/, and each surface symlinks it in rather than duplicating it.
Backend
The surface-router backend is the shared surface-detection router under shared/.
It centralizes the detection order over the declared surfaces, the SKILLED fallback and UNKNOWN.
It carries the shared implement → debug → verify workflow doctrine consumed by each surface.
The review-cache backend supports the sk-code-review mode's non-mutating review output cache.
The evidence-base backend serves the surface packets as read-only domain evidence (sk-code-ci/, sk-code-frontend/, sk-code-skilled/). The hub bundles them alongside the primary mode.
The packet mutates nothing and never carries process. The acting agent applies the doctrine it bundles.
Shared backend material provides surface identity, the workflow doctrine and cross-mode helpers.
It must never gain per-mode workflow contracts.
The implement → debug → verify phases are not standalone modes.
Their surface-agnostic doctrine lives once in shared/references/workflow-implement.md, workflow-debug.md and workflow-verify.md.
Those files are symlinked into each surface, so the active surface carries the full workflow.
A request to implement, debug or verify code causes the router to detect its surface and load that surface's bundled doctrine.
The acting agent applies that doctrine.
Maintenance
After adding or removing a surface, run /doctor:sk-code setup. It checks the hub and names the repair for each failing check.
4. RULES
✅ ALWAYS
- ALWAYS resolve a mode through
mode-registry.json, and never hardcode a router mapping in the hub.
- ALWAYS keep mode contracts in the mode packets, so the hub stays routing-only.
- ALWAYS keep exactly one
graph-metadata.json (this hub's) so the advisor sees one skill identity.
- ALWAYS give every mode an
advisorRouting block with routingClass: "metadata" and the correct packetSkillName.
- ALWAYS keep the implement/debug/verify workflow doctrine as one shared source under
shared/references/, symlinked into each surface, and never fork per-surface copies.
- ALWAYS keep
ROUTER.md RESOURCE_MAP keys aligned with its intent keys and packet leaves aligned with leaf-manifest.json.
- ALWAYS keep hub-shared map inputs explicit in
SHARED_CONTROL_RESOURCES, because they are control resources and never typed leaves.
⛔ NEVER
- NEVER add a
graph-metadata.json inside a mode packet or shared/.
- NEVER put per-mode quality, review, or surface workflow logic in the hub.
- NEVER hardcode a router mapping outside
mode-registry.json.
- NEVER reintroduce implement, debug, or verify as standalone mode packets, because they are surface-owned doctrine.
⚠️ ESCALATE IF
- A new code mode is needed - extend
mode-registry.json and open a packet. Do not bolt logic onto the hub.
- Surface identity and workflow ownership conflict in a way the shared router cannot classify.
5. REFERENCES
- Workflow mode packets:
sk-code-quality/SKILL.md, sk-code-review/SKILL.md.
- Surface evidence packets:
sk-code-ci/SKILL.md, sk-code-frontend/SKILL.md, sk-code-skilled/SKILL.md.
- Shared workflow doctrine:
shared/references/workflow-implement.md, shared/references/workflow-debug.md, shared/references/workflow-verify.md (symlinked into each surface).
- Registry:
mode-registry.json (two-axis: packetKind discriminates workflow vs surface).
- Hub router signals + surface bundling:
hub-router.json.
- Surface router and shared controls:
ROUTER.md.
- Parent-skill pattern:
.skilled/skills/sk-doc/sk-create-skill/references/parent-skill/parent-skills-nested-packets.md.
- Sibling example:
.skilled/skills/sk-prompt/.
1---2name: sk-code3description: "Implement, debug and verify code: TypeScript, Python, shell, JSON; quality and review workflow modes with stack surface packets."4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 3.12.1.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-code8 family: sk-code9---1011<!-- Keywords: sk-code, code, surface-aware, two-axis, opencode, typescript, python, shell, json, jsonc, github-actions, ci-workflow, sk-code-quality, sk-code-review, sk-code-ci, sk-code-frontend, quality, code-review, verification, debug, implement, workflow-doctrine, mode-registry, workflowmode, packetkind, backendkind, surface-router, evidence-base, surface-packet, guard, adapter, stderr, detector -->1213# Code Family Hub (sk-code)1415One skill has two axes, one shared surface-detection router and one advisor identity.16The **workflow axis** has two code modes that act: sk-code-quality and sk-code-review.17The **surface axis** has three read-only evidence packets the hub bundles alongside a workflow mode: sk-code-ci, sk-code-frontend and sk-code-skilled.18Each packet carries the shared **implement → debug → verify** workflow doctrine (`shared/references/workflow-*.md`, symlinked in) plus its own domain knowledge.19This hub holds NO per-mode logic. It routes by `workflowMode` through `mode-registry.json`, and each mode or surface keeps its own contract in its packet.2021**Version authority.** This file's `version` frontmatter is the hub's release version and matches the newest entry under `changelog/`.22`description.json`, `mode-registry.json` and `hub-router.json` carry the same value. Each hub-root JSON routing file therefore states the same release.23`ROUTER.md` and `README.md` keep their own document versions, as the frontmatter-versioning standard gives every doc but `SKILL.md`.24The authority stops at the hub root. Each `modes[]` packet carries its own version and release cadence.25A packet version is independent of this one by design, so a gap between them is not drift.2627---2829## 1. WHEN TO USE3031Use this skill for code-family workflows. Invoke it as `sk-code` with an optional mode hint such as `quality: <request>`. The hub classifies the request, resolves a mode key, and loads the matching nested packet.3233**Workflow axis** (modes that act, one of them chosen as primary):3435| Mode | Use it for | Packet |36|------|------------|--------|37| **sk-code-quality** | Quality gate, P0/P1/P2 author checks, comment hygiene and surface checklists. | `sk-code/sk-code-quality/` |38| **sk-code-review** | Findings-first review, security and correctness baseline, checklists, output contract and PR-state gates. | `sk-code/sk-code-review/` |3940**Surface axis** (read-only, advisor-invisible evidence. When a workflow mode scores, the hub bundles the surface after that primary mode. When no workflow mode scores, the hub routes the surface alone for a lookup, implement, debug or verify task, and the acting agent hands the author gates to `sk-code-quality` before it claims completion):4142| Surface | Carries | Packet |43|---------|---------|--------|44| **sk-code-ci** | GitHub Actions evidence: trigger, filter, permission, timeout, concurrency and caching rules, the protected set, the intentional message-contract exception and the scaffold templates, with the repository-specific values read from a CI profile. Read-only. | `sk-code/sk-code-ci/` |45| **sk-code-frontend** | Stack-agnostic frontend evidence: web markup and CSS, web layout and accessibility, visual values, visual hierarchy and review, motion and interaction, the `tokens.css` starter tokens and Figma-to-code checks. Read-only. | `sk-code/sk-code-frontend/` |46| **sk-code-skilled** | System-code evidence: TypeScript/Python/shell/config standards, hooks, alignment verification, authoring checklists. Bundles the implement → debug → verify workflow doctrine (read-only evidence) for the Skilled surface, and the acting agent applies it. | `sk-code/sk-code-skilled/` |4748**Surface list.** The hub has exactly three surfaces:49- SKILLED (`sk-code-skilled`): the native surface for this framework's own code.50- CI (`sk-code-ci`): the GitHub Actions workflow standards surface.51- Frontend (`sk-code-frontend`): the stack-agnostic web practice and Figma-to-code surface, with visual values, visual hierarchy and review, and motion and interaction guidance, selected by its `FRONTEND` file markers or bundled from request vocabulary.5253The hub also has two workflow modes: quality (`sk-code-quality`) and review (`sk-code-review`).54Any other sk-code doc that counts surfaces points to this sentence.5556### When NOT to Use57- Documentation-only changes with no code-work contract - use `sk-doc`.58- Git workflow, branch, commit, PR, merge, or release work - use `sk-git`.59- Pure browser inspection or external MCP transport work - use the relevant MCP skill.60- For a measured Style Reference (design tokens extracted from a live source), use `sk-design-md-generator` first.61- When a request or a frame leaves a visual value open (spacing, type, color, radius, shadow or motion), or a value sits off every token and scale, load `sk-code-frontend` and decide it from its visual-values reference.62- Backend support primitives in `shared/` - they are consumed by the modes, not invoked as a user workflow.6364---6566## 2. SMART ROUTING6768Routing is **registry-driven at runtime and authored in `hub-router.json`** in two stages.69Stage 1 (hub → mode) uses `hub-router.json` as the authored mode vocabulary. `mode-registry.json` carries the packet contracts, whose aliases are checked against that vocabulary.70Stage 2 (mode → leaves) uses the root [`ROUTER.md`](./ROUTER.md) as the authored leaf-set router.71Both files point back here instead of restating the split.7273The advisor routes every code query to the single identity `sk-code`. Resolve the mode with `node .skilled/bin/compiled-route.cjs --hub sk-code --prompt "<task>"` and follow the decision: `route` loads its `targets`, `clarify` and `defer` ask, `reject` refuses.74Compiled routing is the default. The legacy fallback, the kill-switch and the `UNKNOWN_FALLBACK_CHECKLIST` live in the compiled-routing section of [`ROUTER.md`](./ROUTER.md).7576A bare implement, debug or verify request with no workflow mode becomes a pure surface bundle, and an unclear code intent asks for disambiguation. Neither path forces a stale default.77Run the compiled-routing directive in [`ROUTER.md`](./ROUTER.md) before selecting hub resources.7879---8081## 3. HOW IT WORKS8283### Terms8485- **`workflowMode`**: the public mode or surface key a request resolves to.86- **`packetKind`**: the axis a packet sits on, `workflow` for a mode that acts and `surface` for read-only evidence bundled alongside a mode.87- **`backendKind`**: which backend runs the packet, `surface-router` or `review-cache` for a workflow mode and `evidence-base` for a surface.88- **`surfaceBundle`**: the `routerPolicy.outcomes` entry where one workflow mode leads and zero or more surfaces follow as evidence.89- **`mode-registry.json`**: the registry that owns each mode's discriminator, `surfaceDetection` markers and `advisorRouting`.90- **`hub-router.json`**: stage one's `routerSignals`, `vocabularyClasses` and the surface-bundling policy.91- **`ROUTER.md`**: stage two's `INTENT_SIGNALS` and `RESOURCE_MAP`, plus the `SHARED_CONTROL_RESOURCES` list and the always-loaded `DEFAULT_RESOURCE` preamble.92- **shared control**: a hub-level resource declared in `SHARED_CONTROL_RESOURCES`, which resolves on disk and never projects as a leaf.93- **leaf**: a typed `(workflowMode, leafResourceId)` pair from `leaf-manifest.json` that a `RESOURCE_MAP` path converts to.94- **surface detection**: the shared detection order over the declared surfaces, which tries each specific surface first, then the `SKILLED` fallback, then `UNKNOWN`.95- **`--surface-hint`**: the front-door flag that carries the detected surface into the compiled route, so a hinted surface leads a keyword tie.96- **`UNKNOWN_FALLBACK`**: the load level the router returns, with a disambiguation checklist, when no mode resolves.9798### Layout99```100sk-code/101 SKILL.md # this routing hub (no per-mode code logic)102 README.md # human-facing front page for the hub103 ROUTER.md # active stage-two surface router and shared-control declaration104 mode-registry.json # the two-axis discriminator + advisorRouting contract105 hub-router.json # lexical routing signals + surfaceBundle policy for hub-local choice106 description.json # hub advisor descriptor107 graph-metadata.json # the ONE advisor identity for the whole skill108 leaf-manifest.json # typed (workflowMode, leaf) pairs the router guards validate109 changelog/ # hub release notes, one v<version>.md per hub release110 feature-catalog/ # current-state inventory of the hub's routing capabilities111 manual-testing-playbook/ # routing and disambiguation scenarios for the hub112 benchmark/ # historical routing benchmark inputs and reports113 sk-code-quality/ # quality mode packet (workflow)114 sk-code-review/ # review mode packet (workflow)115 sk-code-ci/ # GitHub Actions workflow standards packet (read-only evidence; rules, protected set and scaffold templates)116 sk-code-frontend/ # stack-agnostic web and Figma-to-code evidence packet (read-only; references/web-visual-values.md, web-visual-hierarchy.md and web-motion-and-interaction.md plus assets/tokens.css)117 sk-code-skilled/ # skilled surface packet (read-only evidence; carries the workflow doctrine)118 shared/ # shared surface-detection router, cross-mode helpers, and the implement/debug/verify workflow doctrine (references/workflow-*.md)119```120121Each mode or surface packet is self-contained and carries no per-packet `graph-metadata.json`. Only this hub carries one, so the advisor discovers exactly one code skill identity. The implement/debug/verify workflow doctrine is a single shared source under `shared/references/`, and each surface symlinks it in rather than duplicating it.122123### Backend124The `surface-router` backend is the shared surface-detection router under `shared/`.125It centralizes the detection order over the declared surfaces, the SKILLED fallback and UNKNOWN.126It carries the shared implement → debug → verify workflow doctrine consumed by each surface.127The `review-cache` backend supports the sk-code-review mode's non-mutating review output cache.128The `evidence-base` backend serves the surface packets as read-only domain evidence (`sk-code-ci/`, `sk-code-frontend/`, `sk-code-skilled/`). The hub bundles them alongside the primary mode.129The packet mutates nothing and never carries process. The acting agent applies the doctrine it bundles.130Shared backend material provides surface identity, the workflow doctrine and cross-mode helpers.131It must never gain per-mode workflow contracts.132133The **implement → debug → verify** phases are not standalone modes.134Their surface-agnostic doctrine lives once in `shared/references/workflow-implement.md`, `workflow-debug.md` and `workflow-verify.md`.135Those files are symlinked into each surface, so the active surface carries the full workflow.136A request to implement, debug or verify code causes the router to detect its surface and load that surface's bundled doctrine.137The acting agent applies that doctrine.138139### Maintenance140141After adding or removing a surface, run `/doctor:sk-code setup`. It checks the hub and names the repair for each failing check.142143---144145## 4. RULES146147### ✅ ALWAYS148- **ALWAYS** resolve a mode through `mode-registry.json`, and never hardcode a router mapping in the hub.149- **ALWAYS** keep mode contracts in the mode packets, so the hub stays routing-only.150- **ALWAYS** keep exactly one `graph-metadata.json` (this hub's) so the advisor sees one skill identity.151- **ALWAYS** give every mode an `advisorRouting` block with `routingClass: "metadata"` and the correct `packetSkillName`.152- **ALWAYS** keep the implement/debug/verify workflow doctrine as one shared source under `shared/references/`, symlinked into each surface, and never fork per-surface copies.153- **ALWAYS** keep `ROUTER.md` `RESOURCE_MAP` keys aligned with its intent keys and packet leaves aligned with `leaf-manifest.json`.154- **ALWAYS** keep hub-shared map inputs explicit in `SHARED_CONTROL_RESOURCES`, because they are control resources and never typed leaves.155156### ⛔ NEVER157- **NEVER** add a `graph-metadata.json` inside a mode packet or `shared/`.158- **NEVER** put per-mode quality, review, or surface workflow logic in the hub.159- **NEVER** hardcode a router mapping outside `mode-registry.json`.160- **NEVER** reintroduce implement, debug, or verify as standalone mode packets, because they are surface-owned doctrine.161162### ⚠️ ESCALATE IF163- A new code mode is needed - extend `mode-registry.json` and open a packet. Do not bolt logic onto the hub.164- Surface identity and workflow ownership conflict in a way the shared router cannot classify.165166---167168## 5. REFERENCES169170- Workflow mode packets: `sk-code-quality/SKILL.md`, `sk-code-review/SKILL.md`.171- Surface evidence packets: `sk-code-ci/SKILL.md`, `sk-code-frontend/SKILL.md`, `sk-code-skilled/SKILL.md`.172- Shared workflow doctrine: `shared/references/workflow-implement.md`, `shared/references/workflow-debug.md`, `shared/references/workflow-verify.md` (symlinked into each surface).173- Registry: `mode-registry.json` (two-axis: `packetKind` discriminates workflow vs surface).174- Hub router signals + surface bundling: `hub-router.json`.175- Surface router and shared controls: `ROUTER.md`.176- Parent-skill pattern: `.skilled/skills/sk-doc/sk-create-skill/references/parent-skill/parent-skills-nested-packets.md`.177- Sibling example: `.skilled/skills/sk-prompt/`.