# Sk Code Skilled

> sk-code SKILLED surface: system-code evidence (TypeScript/Python/shell/Rust/config standards, language-agnostic patterns, hooks, alignment verification, and skill/agent/command/MCP authoring checklists) plus shared implement/debug/verify workflow doctrine.

- Skill: `michelkerkmeester/sk-code-skilled` (Agent Skill, multi-file: 155 files)
- Install (CLI): `npx get-skill add michelkerkmeester/sk-code-skilled`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/sk-code-skilled/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/sk-code-skilled

---


# Skilled Surface — System-Code Evidence

**Domain evidence** and shared workflow doctrine for SKILLED system code (the `.skilled/` tree: skills, agents, commands, plugins, MCP servers, config, changelogs, and runtime bridge wiring). This surface carries the implement -> debug -> verify doctrine through the workflow references below, then slices evidence by the detected language so a TypeScript task never pulls the Python/shell/config guides.

Detection has two steps:

- First, select the Skilled surface for work under `.skilled/`. This includes `SKILL.md`, descriptors, commands, agents, plugins, MCP servers, assets, scripts and changelogs.
- Then use file extensions and local markers to select the language trio:
  - `.cjs`/`.mjs`/`.js` -> JavaScript
  - `.ts`/`.tsx`/`.mts`/`.d.ts` -> TypeScript
  - `.py` plus `argparse` -> Python
  - `.sh`/`.bash` -> shell
  - `.rs` -> Rust
  - `.json`/`.jsonc`/`.yaml`/`.yml` plus `graph-metadata` or `spec-folder` -> config

For Rust, when no `.rs` file is present, local `Cargo.toml`/`Cargo.lock` markers select it after the Skilled surface is established.
napi-rs and wasm-bindgen vocabulary are additional intent signals, not cross-project surface detectors.

## 1. WHEN THE HUB BUNDLES THIS

- The task touches `.skilled/` system code — a skill, agent, command, plugin, MCP server, or descriptor/config.
- The active workflow phase needs a language standard, a language-agnostic organization pattern, a hook contract, an alignment-verification procedure, or an authoring checklist.
- The paired workflow mode owns edits, tests and verification, and applies the workflow references this surface carries. Hand off formal findings-first review to `sk-code-review` and author-side quality gates to `sk-code-quality`.

---

## 2. SMART ROUTING

The hub bundles this surface when the task touches `.skilled/` system code — a skill, agent, command, plugin, MCP server, descriptor or config — and a language or authoring signal then selects the leaf. The first leaves it loads are the shared tier under `references/shared/` and `references/shared/workflow-guardrails.md`, because every language standard builds on them.

The parent hub `RESOURCE_MAP` carries this map re-prefixed with `sk-code-skilled/` plus the parent-owned universal tier, and the router-sync guard (`assets/scripts/verify-router-sync.cjs`, leg 2) checks that equality. A new doc under `references/` or `assets/` needs a `RESOURCE_MAP` entry here, or leg 1b fails.

Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.

---

## 3. REFERENCE MAP

Language standards — after `.skilled/` selects this surface, load the exact split resources for the detected language:
- TypeScript:
  - `references/typescript/style-guide/overview-strict-and-naming.md`
  - `references/typescript/style-guide/formatting-imports-and-coexistence.md`
  - `references/typescript/quality-standards/overview-and-type-system.md`
  - `references/typescript/quality-standards/tsdoc-errors-and-async.md`
  - `references/typescript/quality-standards/tsconfig-and-modules.md`
  - `references/typescript/quick-reference/template-naming-and-types.md`
  - `references/typescript/quick-reference/imports-errors-and-tsconfig.md`
- Python — `references/python/style-guide.md`, `references/python/quality-standards.md`, `references/python/quick-reference.md`
- Shell:
  - `references/shell/style-guide/overview-structure-and-naming.md`
  - `references/shell/style-guide/variables-functions-and-output.md`
  - `references/shell/quality-standards/overview-and-priority-blockers.md`
  - `references/shell/quality-standards/validation-security-and-shellcheck.md`
  - `references/shell/quick-reference/template-variables-and-loops.md`
  - `references/shell/quick-reference/functions-strings-and-checklist.md`
- Rust:
  - Style guide:
    - `references/rust/style-guide/overview-and-file-header.md`
    - `references/rust/style-guide/toolchain-and-project-structure.md`
    - `references/rust/style-guide/naming-conventions.md`
    - `references/rust/style-guide/formatting-and-imports.md`
    - `references/rust/style-guide/commenting-and-rustdoc.md`
    - `references/rust/style-guide/interop-model.md`
    - `references/rust/style-guide/interop-errors-and-parity.md`
  - Quality standards:
    - `references/rust/quality-standards/overview-and-data-ownership.md`
    - `references/rust/quality-standards/modeling-collections-and-api.md`
    - `references/rust/quality-standards/docs-errors-and-async.md`
    - `references/rust/quality-standards/build-and-organization.md`
    - `references/rust/quality-standards/determinism-and-parity.md`
  - Quick reference:
    - `references/rust/quick-reference/overview-and-boundary-template.md`
    - `references/rust/quick-reference/naming-ordering-and-signatures.md`
    - `references/rust/quick-reference/collections-imports-and-errors.md`
    - `references/rust/quick-reference/rustdoc-and-cargo.md`
    - `references/rust/quick-reference/determinism-parity-and-related.md`
- Config (JSON/JSONC/YAML descriptors and route assets) — `references/config/style-guide.md`, `references/config/quality-standards.md`, `references/config/quick-reference.md`, `assets/checklists/config-checklist.md`
- JavaScript (CommonJS/ESM plugins) — `references/javascript/style-guide.md`, `references/javascript/quality-standards/overview-modules-and-docs.md`, `references/javascript/quality-standards/security-testing-and-exemptions.md`, `references/javascript/quick-reference.md`

Language-agnostic shared tier (`references/shared/`, always kept within SKILLED regardless of language):
- `references/shared/universal-patterns/naming-and-commenting.md`, `references/shared/universal-patterns/organization-security-and-examples.md`, `references/shared/code-organization/overview-and-module-organization.md`, `references/shared/code-organization/imports-and-exports.md`, `references/shared/code-organization/directory-and-test-conventions.md`
- `hooks.md` — runtime hook entrypoints, checked-in Claude wiring, OpenCode plugin-bridge delivery, and wrapper reachability; defer to that file for current hook infrastructure instead of duplicating it here
- `alignment-verification-automation.md` — the alignment-drift verifier
- `workflow-guardrails.md`: SKILLED-only implementation guardrails, the verification command chain and runtime build traps, applied on top of the shared implement and verify workflow

Authoring and validation assets:

- Checklists:
  - `assets/checklists/agent-authoring.md`
  - `assets/checklists/command-authoring.md`
  - `assets/checklists/javascript-checklist.md`
  - `assets/checklists/js-css-style/overview-header-and-comments.md`
  - `assets/checklists/js-css-style/naming-init-formatting-and-css.md`
  - `assets/checklists/js-css-style/verification-quick-reference-and-related.md`
  - `assets/checklists/mcp-server-authoring.md`
  - `assets/checklists/python-checklist.md`
  - `assets/checklists/rust-checklist/overview-and-p0-parity.md`
  - `assets/checklists/rust-checklist/p0-safety-and-boundary-discipline.md`
  - `assets/checklists/rust-checklist/p1-required.md`
  - `assets/checklists/rust-checklist/p2-evidence-validation-and-resources.md`
  - `assets/checklists/shell-checklist.md`
  - `assets/checklists/skill-authoring.md`
  - `assets/checklists/typescript-checklist.md`
  - `assets/checklists/universal-checklist.md`
- Scripts:
  - `assets/scripts/README.md`
- References:
  - `references/shared/alignment-verification-automation.md`
  - `references/shared/hooks.md`

Workflow: `references/workflow-implement.md`, `references/workflow-debug.md` and `references/workflow-verify.md` link to the hub's shared implement -> debug -> verify doctrine in `../shared/references/`; the split shared, language, hook and alignment resources above apply on top of it.

---

## 4. SURFACE STANDARDS (the non-negotiables)

- **Plugins never write to the TUI.** OpenCode plugins must not print to the process stdout/stderr (no overlay on the chat input); user/agent-visible output goes through system-context injection, tools, or append-only log files; DEBUG-gated stderr is allowed only behind an env flag. See `references/javascript/quality-standards/overview-modules-and-docs.md` and the plugin exemption tier.
- **Descriptors are load-bearing.** `graph-metadata.json` / `description.json` shape drives discovery; validate JSON/JSONC against `references/config/quality-standards.md`.
- **Alignment drift is a verification gate.** Before any completion claim, re-run the four live sk-code drift guards on a system-code change through the single entry point `scripts/run-all-drift-guards.sh`.
  - `assets/scripts/verify_alignment_drift.py` checks language integrity, plus dead RESOURCE_MAP routes with `--check-router`.
  - `assets/scripts/verify_stack_folders.py` checks that language reference folders resolve.
  - `assets/scripts/verify-router-sync.cjs` is the router-sync guard, and the wrapper runs every leg of it. `references/shared/alignment-verification-automation.md` lists its four checks, the legs and what covers each. That file is the one place the list is kept.
  - `.github/workflows/routing-registry-drift.yml` covers the compiled side of (3) and (4) in CI only, with the admission step warn-only.
  - The documentation claim guard (`assets/scripts/verify-doc-claims.cjs`) reads the sk-code prose the other guards skip, from the hub folder on disk.
    It checks that path references resolve and that no retired packet name remains.
    It also checks that every surface count matches the surface modes in `mode-registry.json`, and that every file the `ROUTER.md` load-tier prose says loads on every route is in `DEFAULT_RESOURCE`.
    Lines that keep a legacy name on purpose sit in its allowlist with a reason. See `references/shared/alignment-verification-automation.md`.
  The wrapper scans repository content only: the files git tracks, so ignored trees, sibling worktrees and vendored clones stay out of a gate they can never pass. When Git is missing or the hub is not a repository, the orphan-doc walk keeps the full walked list. It exits 0 on a clean tree, so a completion claim requires wrapper rc 0 rather than a delta against a backlog.
- **Rust preserves the TypeScript contract.** Rust napi-rs, WASM/WASI, and sidecar modules are compatibility implementations, not independent behavior authorities. JS-visible bytes, six-decimal numeric behavior, comparator tie-breaks, deterministic IDs, collection order, DTOs, and error shapes must remain identical to the TypeScript oracle.
- **Touched-language set, not one-per-task.** Most `.skilled/` tasks touch a single language. Keep that slice tight and use the shared tier for cross-language rules.

An interop task that spans a language pair, such as a napi-rs / WASM / sidecar Rust module held to its TypeScript oracle, legitimately touches both languages.
The router selects the languages the task actually touches and loads both trios plus the shared tier.
You cannot hold Rust byte-identical to TypeScript without seeing both standards.

---

## 5. SUPPORTING ASSETS

Component authoring (`assets/checklists/`): `skill-authoring.md`, `agent-authoring.md`, `command-authoring.md`, `mcp-server-authoring.md`

Language quality gates (`assets/checklists/`): `universal-checklist.md`, `typescript-checklist.md`, `python-checklist.md`, `shell-checklist.md`, `javascript-checklist.md`, `rust-checklist/` (split into topic parts), `config-checklist.md`

Verifier assets (`assets/scripts/`): alignment-drift and stack-folder verifier scripts, the router-sync guard (`verify-router-sync.cjs`) with its replay library (`router-replay-lib.cjs`) and the documentation claim guard (`verify-doc-claims.cjs`), used by this surface. `scripts/run-all-drift-guards.sh` is the single entry point that runs all four as one gate (non-zero if any fails).

Changelog directories (`changelog/`): real skill and packet changelog files are part of the Skilled surface inventory, not out-of-scope documentation noise.

Daemon IPC/socket wiring: daemon-backed CLIs and plugin bridges resolve runtime Unix socket paths such as `daemon-ipc.sock`; sockets are runtime artifacts, so checked-in evidence lives in launcher, bridge, and config files rather than in committed `.sock` files.

Spec-folder authoring lives in system-spec-kit (`.skilled/skills/system-spec-kit/references/workflows/spec-folder-write-recipe.md` + `spec-folder-authoring-checklist.md`), not in this surface. Checklists are pulled on demand by the active workflow phase.

---

## 6. QUALITY CHECKLIST MAP

This is this repository's quality checklist map, not a universal one.
The quality runner resolves checklists from two sources: the rows owned by the quality mode in `../sk-code-quality/assets/quality-defaults.json` and each surface's `quality.checklists` declaration in `../mode-registry.json`.
This table renders both sources in that order.
`scripts/tests/quality-checklist-map.test.cjs` fails when the two differ.
In any repository, run `node ../sk-code-quality/scripts/quality-gate.cjs --explain <path>` to see the checklists for a file and why they apply.

A SKILLED row applies only to a file that resolves to SKILLED.
A `sk-code-ci` row applies by path alone because that surface declares no detection block.
A FRONTEND row applies only to a file that resolves to FRONTEND.
The spec-folder row applies only inside this hub's own repository.
Applies to lists path globs and extensions. A row with several values matches on any of them.
The MCP server checklist, `assets/checklists/mcp-server-authoring.md`, has no path to declare, so no row below names it. Load it when the target is MCP server source: a file that defines an MCP server, registers its tools or sets how it starts. The hub [`ROUTER.md`](../ROUTER.md) §4 states this rule once.

| Owner | Applies to | Checklist |
| --- | --- | --- |
| quality defaults | `**` | `../shared/references/universal/code-quality-standards.md` |
| quality defaults | `specs/**` | `../../system-spec-kit/references/workflows/spec-folder-authoring-checklist.md` |
| SKILLED | `.skilled/**` | `assets/checklists/universal-checklist.md` |
| SKILLED | `.skilled/skills/**` | `assets/checklists/skill-authoring.md` |
| SKILLED | `.skilled/agents/**` | `assets/checklists/agent-authoring.md` |
| SKILLED | `.skilled/commands/**` | `assets/checklists/command-authoring.md` |
| SKILLED | `.js`, `.cjs`, `.mjs` | `assets/checklists/javascript-checklist.md` |
| SKILLED | `.js`, `.css` | `assets/checklists/js-css-style/overview-header-and-comments.md` |
| SKILLED | `.js`, `.css` | `assets/checklists/js-css-style/naming-init-formatting-and-css.md` |
| SKILLED | `.js`, `.css` | `assets/checklists/js-css-style/verification-quick-reference-and-related.md` |
| SKILLED | `.ts`, `.tsx`, `.mts`, `.cts` | `assets/checklists/typescript-checklist.md` |
| SKILLED | `.py` | `assets/checklists/python-checklist.md` |
| SKILLED | `.sh`, `.bash` | `assets/checklists/shell-checklist.md` |
| SKILLED | `.rs` | `assets/checklists/rust-checklist/overview-and-p0-parity.md` |
| SKILLED | `.rs` | `assets/checklists/rust-checklist/p0-safety-and-boundary-discipline.md` |
| SKILLED | `.rs` | `assets/checklists/rust-checklist/p1-required.md` |
| SKILLED | `.rs` | `assets/checklists/rust-checklist/p2-evidence-validation-and-resources.md` |
| SKILLED | `.json`, `.jsonc`, `.yaml`, `.yml` | `assets/checklists/config-checklist.md` |
| sk-code-ci | `.github/workflows/**` | `../sk-code-ci/references/ci-workflow-standards.md` |
| FRONTEND | `.css`, `.scss`, `.html`, `.tsx`, `.jsx`, `.vue`, `.svelte` | `../sk-code-frontend/references/frontend-practice.md` |

