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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The

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 `/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 `/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.0` 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,28 @@ 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
+`/write-cmk-skill` for the user to run first; never invoke that user-invoked
+skill; skip the gate for pure `## Project adaptations`). 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 `/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,28 @@
+# 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`
+- 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:

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.2
 ---
 
 # 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,19 @@ 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 `/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
+ only when the user already completed that pass for this amendment set.
+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/references/reconciliation.md

@@ -45,6 +45,11 @@ generic skill is flagged with its file, section, and a one-line rationale.
 Flagging is sync's job; actually preparing and contributing it back upstream
 is *contribute* mode's job, never a side effect of running sync.
 
+Before contribute prepares that PR, name `/write-cmk-skill` for the user to
+run on the candidate set — the kit's authoring Iron Law and ship checklist
+live there. Do not invoke `cmk:write-cmk-skill` from sync (user-invoked).
+Pure `## Project adaptations` stay local and skip that gate.
+
 ## Failure honesty
 
 A skill whose reconcile did not complete keeps its old lock entry. The