feat(kvb-skill-compile): compile deterministic skill steps into scripts

kvb-skill-compile finds the steps of a skill whose result follows from its inputs alone (fixed command sequences, parsing, counting, thresholds, format checks, bookkeeping) and turns them into tested scripts in the repository that owns the skill: skills/<skill>/scripts/ with a test under tests/ in the skills repository, that repository's own convention elsewhere, and an upstream proposal for third-party skills. The prose shrinks to the call. Wired into kvb-skill-tune (finding and shape option), kvb-skill-dream step 7, kvb-skill-auto, kvb-skill-transcend and kvb-skill-essence. Four descriptions are trimmed to stay inside the 1300-word listing budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -69,6 +69,7 @@ flowchart LR
   skill --> skill_auto[kvb-skill-auto]
   skill --> skill_essence[kvb-skill-essence]
   skill --> skill_transcend[kvb-skill-transcend]
+  skill --> skill_compile[kvb-skill-compile]
   none --> cleanup[kvb-cleanup]
   none --> help[kvb-help]
   none --> transcend_all[kvb-transcend]
@@ -145,6 +146,7 @@ flowchart LR
     autoskill[kvb-skill-auto]
     essence[kvb-skill-essence]
     skill_transcend[kvb-skill-transcend]
+    compile[kvb-skill-compile]
   end
   subgraph cat_none [no category]
     cleanup[kvb-cleanup]
@@ -231,6 +233,12 @@ flowchart LR
   skill_transcend --> autotune
   code_transcend --> active_listening
   autotune -. own scripts .-> skill_transcend
+  dream --> compile
+  autotune -. deterministic prose .-> compile
+  autoskill -. deterministic steps .-> compile
+  skill_transcend -. deterministic moves .-> compile
+  essence -. procedures .-> compile
+  compile --> active_listening
   tune -. measurements .-> code_transcend
 
   test --> triage

skills/kvb-cleanup/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: kvb-cleanup
 description: >
-  Free disk space agents filled: ask peers what they still need,
+  Free disk space agents filled: ask peers, inventory /tmp, Docker and agent
-  inventory /tmp, Docker and agent dirs, and delete only what the operator
+  dirs, and delete only what the operator picks. Trigger on /kvb-cleanup, "aufräumen", "bereinigen", "platte voll", "no
-  picks. Trigger on /kvb-cleanup, "aufräumen", "bereinigen", "platte voll", "no
   space left on device".
 ---
 

skills/kvb-git-commit-next/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: kvb-git-commit-next
 description: >
-  Check every branch for the staged fix, commit the staged bundle with
+  Search every branch for the staged fix, commit it with --no-verify, then
-  --no-verify, then stage and brief the next bundle. Trigger on /kvb-git-commit-next
+  stage and brief the next bundle. Trigger on /kvb-git-commit-next or a
-  or a request to commit and stage the next bundle in one step.
+  request to commit and stage next.
 ---
 
 1. `git fetch --all --prune --tags`, then hunt the staged fix across every

skills/kvb-skill-auto/SKILL.md

@@ -2,8 +2,8 @@
 name: kvb-skill-auto
 description: >
   Turn operator repetition into a skill. Trigger when the operator repeats an
-  instruction, correction or prompt pattern a third time in a conversation, or
+  instruction, correction or prompt pattern a third time, or says they keep
-  says they keep repeating themselves, and the pattern is reusable.
+  repeating themselves.
 ---
 
 Its objective is the `kvb-skill-tune` skill's **Objective** section: a skill is worth
@@ -27,7 +27,8 @@ vary), do the following:
    project-specific.
    Follow the local naming conventions and keep the skill a thin,
    single-purpose instruction; route to an authoritative doc when one
-   exists instead of duplicating it.
+   exists instead of duplicating it. Its deterministic steps become a script
+   through the `kvb-skill-compile` skill, not prose.
 4. Do not propose a skill for one-off work, secrets, or anything whose
    repetition is already covered by an existing skill; when an existing
    skill almost fits, propose extending it instead.

skills/kvb-skill-compile/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: kvb-skill-compile
+description: >
+  Turn deterministic skill steps into tested scripts in the skill's own repo.
+  Trigger on /kvb-skill-compile or a skill step that is a fixed command
+  sequence.
+---
+
+A deterministic step is one whose result follows from its inputs alone:
+fixed command sequences, output parsing and filtering, counting, thresholds
+and arithmetic, format checks, sorting and lookups, state bookkeeping. This
+skill compiles such steps into scripts and cuts the prose down to the call. Choosing, explaining and asking stay prose.
+It changes nothing before the operator confirms.
+
+## Step 1: scope and owner
+
+The skills named after the command, or every skill of the current
+repository when none is named. Per skill, its owning repository:
+
+- **Skills repository**: a first-party skill under its `skills/`, and every
+  installed copy of one (`~/.claude/skills`, `~/.agents/skills`, a project's
+  rendered `.claude/skills`); edit the source, never the copy, by the
+  `kvb-skill-tune` skill's **Persistence** section.
+- **Another repository**: a skill tracked in that repository's own tree
+  (`git ls-files` lists it there), such as a project's `.claude/skills`.
+- **Third party**: a `skills-lock.json` entry from a foreign source is not
+  compiled; propose the change upstream instead.
+
+## Step 2: inventory
+
+Read-only. Per skill, every step that is deterministic, with its evidence:
+how often sessions ran it (transcripts, `rasci.py tools` of the
+`kvb-org-rasci` register) and where an agent got it wrong. One line each:
+`skill:step -> deterministic part -> inputs -> output -> runs per use`.
+
+## Step 3: classify
+
+Compile what runs often or went wrong; leave a one-off as prose. Per
+candidate:
+
+- **Language and form**: the owning repository's own (Python standard
+  library in the skills repository); no new language, framework or
+  dependency without the operator.
+- **Interface**: every host path, name and value an explicit parameter (the
+  `kvb-code-no-defaults` skill), documented exit codes, `--json` when another
+  script or skill consumes the output.
+- **Location**: `skills/<skill>/scripts/<verb>.py` with a test under `tests/`
+  in the skills repository; elsewhere the owning repository's convention,
+  read from its `AGENTS.md`, `CONTRIBUTING` and `Makefile` first.
+
+## Step 4: listen and confirm
+
+Run the `kvb-think-listen` skill on the open points. Then `AskUserQuestion`:
+one `multiSelect` with the candidates, nothing preselected, and per pick a
+single-select `Write it` / `Revise it` / `Discard` showing the drafted script
+and the prose diff.
+
+## Step 5: write
+
+- Write the script, then replace the compiled prose with its call
+  (`${CLAUDE_SKILL_DIR}/scripts/<verb>.py ...`) and the one line on reading
+  its output.
+- Every script gets a unit test with a negative control shown once. Tests
+  run only on the resource chair's grant (the `kvb-org-organize` skill).
+- In another repository follow its agent rules (claims, worktree, branch);
+  a file another line owns goes to that line through the
+  `kvb-org-coordinate` skill.
+- Leave the result uncommitted for the `kvb-git-commit-next` skill.
+
+## Output
+
+| Skill | Step | Script | Repository | Prose lines cut | Verdict |
+
+Steps left as prose stay with their reason.

skills/kvb-skill-dream/SKILL.md

@@ -109,12 +109,14 @@ as radio buttons: the improvement, the evidence behind it, and the options
 `Apply now`, `Record as a task`, `Skip`. Ranked by evidence, one question per
 improvement. No repository file changes before an answer comes back.
 
-## Step 7: kvb-skill-tune, kvb-skill-auto, kvb-transcend
+## Step 7: kvb-skill-tune, kvb-skill-auto, kvb-transcend, kvb-skill-compile
 
 With the dialectic done and memory written, run `kvb-skill-tune` — hand it this run's
 findings as its evidence so it does not re-collect them — then `kvb-skill-auto`
-for the operator corrections the window revealed, and `kvb-transcend` for the
+for the operator corrections the window revealed, `kvb-transcend` for the
-scripts and tests the window's sessions wrote outside a repository. All keep
+scripts and tests the window's sessions wrote outside a repository, and
+`kvb-skill-compile` for the skill steps the window's sessions worked through
+by hand although they are deterministic. All keep
 their own confirmation steps; the dream never writes a skill on their behalf.
 
 Close the run by refreshing this repository's reminder stamp, so the next hint

skills/kvb-skill-essence/SKILL.md

@@ -65,6 +65,9 @@ Cut:
 - The second and third statement of one rule; keep the authoritative one and
   point at it.
 - Narration, hedging, and worked examples beyond the one that carries the point.
+- A deterministic procedure spelled out step by step: hand it to the
+  `kvb-skill-compile` skill, which replaces it with a script call, instead of
+  shortening it.
 
 Keep, always:
 

skills/kvb-skill-transcend/SKILL.md

@@ -31,8 +31,9 @@ One line each: `candidate -> source -> evidence`.
 
 Per candidate one target: a script under an existing skill's `scripts/`, a
 new skill, a sharper step in an existing skill, a memory entry instead, or
-drop. Recurring moves without a script go to the `kvb-skill-tune` skill as
+drop. A recurring deterministic move without a script goes to the
-evidence. A script is portable only once its host paths, names and values
+`kvb-skill-compile` skill, any other recurring move to the `kvb-skill-tune`
+skill as evidence. A script is portable only once its host paths, names and values
 became explicit parameters (the `kvb-code-no-defaults` skill); one that needs
 a secret, a credential or a single host is dropped or stays a memory entry.
 

skills/kvb-skill-tune/SKILL.md

@@ -65,6 +65,9 @@ where readable, from the project's memory and agent instruction files:
 - **Own scripts**: helpers the agent wrote outside any repository belong to
   the `kvb-skill-transcend` skill, which carries them over; this skill
   takes the frictions they reveal.
+- **Deterministic prose**: a skill step the agent worked through by hand
+  although its result follows from its inputs belongs to the
+  `kvb-skill-compile` skill, which turns it into a script.
 
 List each finding as one line: `symptom -> cost -> candidate fix`. Skip
 anything that happened once and is not a pattern.
@@ -86,7 +89,8 @@ Ask in this order, at most four questions per call:
 3. **Shape** - for a new skill: `Standalone skill`, `Extend an existing
    skill`, `Memory entry instead of a skill`.
    For an optimization: `Tighten wording only`, `Change the trigger`, `Add
-   rules`, `Split into two skills`, `Merge into another skill`.
+   rules`, `Split into two skills`, `Merge into another skill`, `Compile
+   deterministic steps into a script` (the `kvb-skill-compile` skill).
 4. **Placement** - `Operator skills repository (portable)` or
    `This project's skills directory (project-specific)`.
 

skills/kvb-think-listen/SKILL.md

@@ -2,9 +2,8 @@
 name: kvb-think-listen
 description: >
   Ask focused questions until every requirement is pinned down, then reflect
-  the task back. Trigger at the start of any task with unclear scope,
+  the task back. Trigger on unclear scope, constraints or success criteria,
-  constraints or success criteria, and when another skill needs an
+  or when a skill needs an operator-only fact.
-  operator-only fact.
 ---
 
 Do not act on a half-understood request. Listen actively until you could state