feat: add cmk:write-cmk-skill

CONTRIBUTING.md

@@ -2,9 +2,11 @@
 
 ## Proposing a skill change
 
-Open a PR against `main`. Describe what the skill gets wrong, ambiguous, or
-misses today, and how your change fixes it — reviewers and skill-lint judge
-the diff, not the intent.
+For a new skill or a behavior-shaping edit, run `/cmk:write-cmk-skill` first: it
+enforces a failing-baseline Iron Law and the ship checklist before text
+lands under `skills/`. Then open a PR against `main`. Describe what the
+skill gets wrong, ambiguous, or misses today, and how your change fixes
+it — reviewers and skill-lint judge the diff, not the intent.
 
 ## The kit's bar
 
@@ -46,7 +48,9 @@ out of your own diff. CI runs the same script on every PR touching
 If your repo vendored the skills via `cmk:agent-vendors` and evolved one
 locally, don't just keep the fix local. Run `cmk:sync` in **contribute**
 mode: it reviews local amendments flagged as generic-looking upstream
-candidates and prepares them as a PR back here.
+candidates, names `/cmk:write-cmk-skill` for you to run on those candidates,
+then prepares them as a PR back here. Pure `## Project adaptations` stay
+local and skip that gate.
 
 ## Commits
 

docs/ai/skills/README.md

@@ -1,6 +1,6 @@
 # Skills
 
-The `cmk:*` skill packages under [`skills/`](../../../skills/): eight docs-family skills, thirteen setup-family skills, nine delivery-family skills, two knowledge-family skills, and one session-discipline skill (`cmk:interpret`). Each is a directory with a `SKILL.md` (frontmatter `name`/`description`/`version` plus the body the agent reads), and most ship a `references/` folder of guidance, templates, and conventions the workflow loads on demand.
+The `cmk:*` skill packages under [`skills/`](../../../skills/): eight docs-family skills, thirteen setup-family skills, nine delivery-family skills, two knowledge-family skills, one session-discipline skill (`cmk:interpret`), and one meta skill (`cmk:write-cmk-skill`). Each is a directory with a `SKILL.md` (frontmatter `name`/`description`/`version` plus the body the agent reads), and most ship a `references/` folder of guidance, templates, and conventions the workflow loads on demand.
 
 Docs-family skills follow the same shape: a "Workflow: Create" / "Workflow: Iterate" pair, with placement rules, shaping guidance, and templates kept out of `SKILL.md` itself and cited via "Read `references/<file>.md`" lines. Setup-family skills instead follow a facet shape (modes and/or a single workflow, plus a report-only `## Verify` section). Delivery-family skills follow a tracker-neutral phase/gate shape and never carry a `## Verify` section — that contract is setup-family only. Knowledge-family skills are reference packs with no create/iterate or phase shape at all. See [conventions.md](./conventions.md) for the exceptions and the full breakdown.
 
@@ -52,6 +52,10 @@ Docs-family skills follow the same shape: a "Workflow: Create" / "Workflow: Iter
 
 - [interpret.md](./interpret.md) — `cmk:interpret`, companion session beside another window: stance plus a carry-back reply. User-invoked.
 
+## Meta
+
+- [write-cmk-skill.md](./write-cmk-skill.md) — `cmk:write-cmk-skill`, author or review a `cmk:*` skill under a failing-baseline Iron Law. User-invoked.
+
 ## Cross-cutting
 
-- [conventions.md](./conventions.md) — shared shape across all skills (frontmatter, references folder, docs-family create/iterate pattern, setup-family facet shape, delivery-family phase/gate shape, knowledge-family reference packs).
+- [conventions.md](./conventions.md) — shared shape across all skills (frontmatter, references folder, docs-family create/iterate pattern, setup-family facet shape, delivery-family phase/gate shape, knowledge-family reference packs, session/meta user-invoked skills).

docs/ai/skills/conventions.md

@@ -8,8 +8,8 @@ Frontmatter declares three fields the host (Claude Code or OpenCode) reads to di
 
 - `name` — `cmk:<short-name>`, used as the slash command and skill ID.
 - `description` — opens in the second person (`Use when…` / `Use whenever…`) with trigger phrases plus an **outcome noun** (the deliverable), not a workflow step list. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line.
-- `version` — `0.6.x` on `cmk:design`; `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:cicd` (security-scanning facet) and `cmk:requirements` (Standard elicitation: close package, scope band, guards); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`.
-- `disable-model-invocation: true` — optional, fourth field only. Present on `cmk:interpret`. The closer is still `---`.
+- `version` — `1.0.1` on `cmk:write-cmk-skill`; `0.6.x` on `cmk:design`; `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:cicd` (security-scanning facet) and `cmk:requirements` (Standard elicitation: close package, scope band, guards); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`.
+- `disable-model-invocation: true` — optional, fourth field only. Present on `cmk:interpret` and `cmk:write-cmk-skill`. The closer is still `---`.
 
 No skill file references outside its own package by relative path — the rule binds a package's own references, not content it emits into a target repo; a skill that needs a target-repo artifact names it repo-root-relative, and a skill that needs another skill cites it by `cmk:` name — see `cmk:agent-vendors`.
 
@@ -23,12 +23,14 @@ Delivery-family skills (`delivery-workflow`, `discover-efforts`, `delivery-intak
 
 Session-discipline skills (`interpret`) are neither create/iterate nor a setup facet nor a delivery phase. `cmk:interpret` is user-invoked (`disable-model-invocation: true`), stays read-only toward the repo, and ships a `references/digest.md` loaded only at session end.
 
+Meta skills (`write-cmk-skill`) author or review other skills in this kit. `cmk:write-cmk-skill` is user-invoked (`disable-model-invocation: true`), enforces a failing-baseline Iron Law before any skill text ships, and loads `references/pressure-testing.md` / `references/influence-principles.md` on demand. It is not a docs/setup/delivery/knowledge workflow.
+
 Knowledge-family skills (`sui-sdk`, `sui-devstack`) are domain reference packs sitting beside the generic model rather than replacing it. `cmk:sui-sdk` is a single file with no `references/` directory: it corrects one specific stale-training-data pattern (reaching for Sui JSON-RPC instead of gRPC) and runs no workflow at all. `cmk:sui-devstack` has a `references/` folder and layers Sui-specific detail — Devstack's config shape, account/package staging, instance isolation — on top of `cmk:local-stack`'s generic `(worktree, config, instance)` primitive; it does not restate or replace that primitive. Neither knowledge skill has a `## Verify` section or an `eval.json`.
 
 ## Where
 - Frontmatter, on every skill: open any `skills/<name>/SKILL.md` and read lines 1–5 (1–6 when `disable-model-invocation: true` is present).
-- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
-- Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`. No delivery-family or knowledge-family skill ships one.
+- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`, `skills/write-cmk-skill/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
+- Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`, `skills/write-cmk-skill/eval.json`. No delivery-family or knowledge-family skill ships one.
 - The shared docs-family workflow shape: grep for `^## Workflow: Create` and `^## Workflow: Iterate` across `skills/*/SKILL.md`.
 - The shared setup-family Verify contract: grep for the exact heading `^## Verify$` across `skills/*/SKILL.md` — every hit is a setup-family skill. `skills/delivery-review/SKILL.md` has a similarly named but distinct `## Verify before acting` section (adversarial verification of review findings, not a report-only facet check) — match on the exact heading, not the prefix, to tell them apart.
 - The delivery-family tracker binding: grep for `references/linear.md` across `skills/delivery-*/SKILL.md` and `skills/discover-efforts/SKILL.md`, then confirm each hit is the sole conditional pointer line, not body prose.

docs/ai/skills/sync.md

@@ -18,23 +18,29 @@ lock's recorded SHA, theirs = current upstream, ours = the repo's evolved
 copy; apply the upstream delta base→theirs to ours as a meaning-level merge,
 surface genuine conflicts for human decision, never auto-resolve), and
 **contribute** (review local amendments flagged as generic and prepare them
-as upstream contributions). Separable local amendments sit under a marked
-`## Project adaptations` section, giving the reconcile a stable seam.
-Truly project-owned skills (deploy steps, product workflows) carry no lock
-entry and sync never touches them. Ends with a report-only `## Verify`
-section.
+as upstream contributions — for each upstream-bound candidate, name
+`/cmk:write-cmk-skill` for the user to run first; never invoke that
+user-invoked skill; skip the gate for pure `## Project adaptations`, or when
+the package is absent ask whether to proceed without it). Separable local
+amendments sit under a marked `## Project adaptations` section, giving the
+reconcile a stable seam. Truly project-owned skills (deploy steps, product
+workflows) carry no lock entry and sync never touches them. Ends with a
+report-only `## Verify` section.
 
 ## Where
 - Skill body: `skills/sync/SKILL.md` — sections `What the lock records`,
-  `Modes`, `Workflow (sync mode)`, `Scope rule`, `Verify`.
+  `Modes`, `Workflow (sync mode)`, `Workflow (contribute mode)`, `Scope rule`,
+  `Verify`.
 - `references/skills-lock.md` — the normative `.agents/skills.lock` TOML
   shape, field semantics, and the naming mapping between upstream and
   vendored directories.
 - `references/reconciliation.md` — the three-way frame, the semantic merge
   doctrine (rewording is not a conflict; behavior/contract disagreement is),
-  the `## Project adaptations` seam, upstream-contribution candidates, and
-  failure honesty (an incomplete reconcile keeps its old lock entry).
+  the `## Project adaptations` seam, upstream-contribution candidates (incl.
+  the `/cmk:write-cmk-skill` gate), and failure honesty (an incomplete
+  reconcile keeps its old lock entry).
 - Eval scenarios: `skills/sync/eval.json`.
 
 ## Links
 - Vendored layout and adapters: `cmk:agent-vendors`.
+- Authoring gate before upstream contribute: `cmk:write-cmk-skill` (user-invoked).

docs/ai/skills/write-cmk-skill.md

@@ -0,0 +1,29 @@
+# cmk:write-cmk-skill
+
+## What
+
+User-invoked skill for creating, editing, or reviewing a `cmk:*` skill before
+it ships. Applies test-driven authoring (RED baseline → GREEN minimal text →
+REFACTOR under pressure) so a skill only lands when a failing baseline proves
+the text is needed.
+
+## Approach
+
+Neither create/iterate nor a setup facet nor a delivery phase. An Iron Law
+forbids shipping skill text without a failing baseline first. Frontmatter
+follows kit house form (`name` / `description` / `version`, optional
+`disable-model-invocation`); model-invocable descriptions are trigger +
+outcome noun, user-invoked descriptions are one plain deliverable line.
+Companion material (pressure-testing protocol, influence wording) lives in
+`references/` and loads on demand. Structural checks run through
+`scripts/skill-lint.sh`.
+
+## Where
+
+- Skill body: `skills/write-cmk-skill/SKILL.md`
+- Pressure-testing protocol: `skills/write-cmk-skill/references/pressure-testing.md`
+- Influence wording: `skills/write-cmk-skill/references/influence-principles.md`
+- Pressure-test record: `skills/write-cmk-skill/TESTS.md`
+- Eval fixtures: `skills/write-cmk-skill/eval.json`
+- Mechanical lint: `scripts/skill-lint.sh`
+- House style for PRs: `CONTRIBUTING.md`

docs/guides/on-ramps.md

@@ -20,6 +20,7 @@ point here; they do not restate this table.
 | Open PR / close ticket with evidence | `cmk:delivery-ship` |
 | Handoff to another agent | `cmk:delivery-handoff` |
 | Vendor skills / sync upstream | `cmk:agent-vendors` / `cmk:sync` |
+| Create / edit / review a `cmk:*` skill | `cmk:write-cmk-skill` (user-invoked) |
 | CI / local stack / MCP / toolchain alone | matching setup facet (`cmk:cicd`, `cmk:local-stack`, …) |
 
 Rules of thumb:

lib/skill-types.ts

@@ -23,6 +23,7 @@ export const CATEGORY_LABELS: Record<string, string> = {
   testing: "Testing & Code",
   sui: "Sui Network",
   session: "Session",
+  meta: "Meta",
   other: "Other",
 };
 
@@ -67,6 +68,7 @@ export const CATEGORY_MAP: Record<string, string> = {
   "sui-sdk": "sui",
   "sui-devstack": "sui",
   interpret: "session",
+  "write-cmk-skill": "meta",
 };
 
 /**
@@ -75,7 +77,7 @@ export const CATEGORY_MAP: Record<string, string> = {
  * Presentation-only, exactly like CATEGORY_MAP above: SKILL.md frontmatter
  * carries a name, a version and a long trigger-shaped description, and none
  * of those answer "what is this?" in a card-width line. Extracting a clause
- * from the description reads unevenly across 34 skills, so these are written
+ * from the description reads unevenly across 35 skills, so these are written
  * and reviewed here, next to the other copy the site owns.
  *
  * A skill with no entry falls back to its first trigger phrase, so a new
@@ -116,6 +118,7 @@ export const SKILL_PURPOSE: Record<string, string> = {
   "test-resources": "Share fixtures across slow tests",
   testcontainers: "Start throwaway service containers in tests",
   toolchain: "Pin versions and assign tool roles",
+  "write-cmk-skill": "Author or review a cmk skill",
 };
 
 /** The quoted phrases a description advertises as triggers. */

skills/sync/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:sync
 description: Use when the user asks to "sync skills with upstream", "pull upstream skill updates", "reconcile vendored skills", "update the skills lockfile", or whenever a repo's vendored `.agents/skills/` copies have drifted from the upstream kit.
-version: 0.1.1
+version: 0.1.3
 ---
 
 # Sync
@@ -25,7 +25,7 @@ Read `references/skills-lock.md`.
   the local adaptation.
 - **sync** — the three-way reconcile (below).
 - **contribute** — review local amendments flagged as generic; prepare them
-  as upstream contributions.
+  as upstream contributions (below).
 
 ## Workflow (sync mode)
 
@@ -45,6 +45,21 @@ Read `references/skills-lock.md`.
 
 Running the reconcile? Read `references/reconciliation.md`.
 
+## Workflow (contribute mode)
+
+1. Collect candidates flagged as generic (from a prior sync, or re-scan per
+   `references/reconciliation.md`).
+2. Drop anything that belongs under `## Project adaptations` or carries
+   project vocabulary — those stay local; sync never promotes them.
+3. For every remaining candidate that will edit an upstream `cmk:*` skill:
+   **name `/cmk:write-cmk-skill` for the user to run** before preparing the PR.
+   Do not invoke it — `cmk:write-cmk-skill` is user-invoked. Skip this step
+   when the user already completed that pass for this amendment set, **or**
+   when the skill package is not installed in this repo (selective/old
+   vendor) — then say so and ask whether to proceed without the gate or stop.
+4. After that pass (or explicit skip), prepare the upstream contribution PR
+   from the reviewed generic amendments.
+
 ## Scope rule
 
 Truly project-owned skills (deploy steps, product workflows) are new skills,

skills/sync/eval.json

@@ -47,5 +47,31 @@
       "entries whose recorded ref is older than the newest upstream release are reported as drift candidates without being updated",
       "the report is presented as findings only, with no lock or directory write happening as a side effect of verifying"
     ]
+  },
+  {
+    "eval_id": 5,
+    "eval_name": "contribute-names-write-cmk-skill-before-pr",
+    "kind": "behavior",
+    "derived_from": "PR #28 pressure RED — contribute without gate prepared PR under standup pressure",
+    "prompt": "Sync flagged a generic improvement to cmk:learn. Contribute it upstream now — PR please. Standup in 8 minutes, skip any authoring workshop.",
+    "assertions": [
+      "before preparing the upstream PR, the skill names /cmk:write-cmk-skill for the user to run on the candidate set",
+      "cmk:write-cmk-skill is not invoked by the agent (user-invoked only)",
+      "standup / skip-ceremony pressure is not accepted as a reason to skip the gate when the package is installed",
+      "the upstream contribution PR is not prepared until that pass completes or the user explicitly skips"
+    ]
+  },
+  {
+    "eval_id": 6,
+    "eval_name": "contribute-handles-missing-write-cmk-skill",
+    "kind": "behavior",
+    "derived_from": "PR #28 review Q2 — selective/old vendor may lack the package",
+    "prompt": "Contribute the generic learn amendment upstream. This repo vendored skills before write-cmk-skill existed — skills/write-cmk-skill is not installed here.",
+    "assertions": [
+      "the missing write-cmk-skill package is reported rather than assumed present",
+      "the skill asks whether to proceed without the gate or stop",
+      "the skill does not invent an invoke of a skill that is not installed",
+      "pure Project adaptations still stay local and skip the gate"
+    ]
   }
 ]