From b99c1e2be5c2464497ada809fd4f085e825f8cba Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Tue, 3 Nov 2026 13:17:05 +0100 Subject: [PATCH] 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//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 --- README.md | 8 ++++ skills/kvb-cleanup/SKILL.md | 5 +- skills/kvb-git-commit-next/SKILL.md | 6 +-- skills/kvb-skill-auto/SKILL.md | 7 +-- skills/kvb-skill-compile/SKILL.md | 74 +++++++++++++++++++++++++++++ skills/kvb-skill-dream/SKILL.md | 8 ++-- skills/kvb-skill-essence/SKILL.md | 3 ++ skills/kvb-skill-transcend/SKILL.md | 5 +- skills/kvb-skill-tune/SKILL.md | 6 ++- skills/kvb-think-listen/SKILL.md | 5 +- 10 files changed, 109 insertions(+), 18 deletions(-) create mode 100644 skills/kvb-skill-compile/SKILL.md diff --git a/README.md b/README.md index 48f0b1a..24de7bd 100644 --- a/README.md +++ b/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 diff --git a/skills/kvb-cleanup/SKILL.md b/skills/kvb-cleanup/SKILL.md index 386ab1e..e927a88 100644 --- a/skills/kvb-cleanup/SKILL.md +++ b/skills/kvb-cleanup/SKILL.md @@ -1,9 +1,8 @@ --- name: kvb-cleanup description: > - Free disk space agents filled: ask peers what they still need, - inventory /tmp, Docker and agent dirs, and delete only what the operator - picks. Trigger on /kvb-cleanup, "aufräumen", "bereinigen", "platte voll", "no + Free disk space agents filled: ask peers, inventory /tmp, Docker and agent + dirs, and delete only what the operator picks. Trigger on /kvb-cleanup, "aufräumen", "bereinigen", "platte voll", "no space left on device". --- diff --git a/skills/kvb-git-commit-next/SKILL.md b/skills/kvb-git-commit-next/SKILL.md index f3693f1..ae7c6ff 100644 --- a/skills/kvb-git-commit-next/SKILL.md +++ b/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 - --no-verify, then stage and brief the next bundle. Trigger on /kvb-git-commit-next - or a request to commit and stage the next bundle in one step. + Search every branch for the staged fix, commit it with --no-verify, then + stage and brief the next bundle. Trigger on /kvb-git-commit-next or a + request to commit and stage next. --- 1. `git fetch --all --prune --tags`, then hunt the staged fix across every diff --git a/skills/kvb-skill-auto/SKILL.md b/skills/kvb-skill-auto/SKILL.md index 4444186..df710c1 100644 --- a/skills/kvb-skill-auto/SKILL.md +++ b/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 - says they keep repeating themselves, and the pattern is reusable. + instruction, correction or prompt pattern a third time, or says they keep + 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. diff --git a/skills/kvb-skill-compile/SKILL.md b/skills/kvb-skill-compile/SKILL.md new file mode 100644 index 0000000..cd14770 --- /dev/null +++ b/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//scripts/.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/.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. diff --git a/skills/kvb-skill-dream/SKILL.md b/skills/kvb-skill-dream/SKILL.md index 4eed4ec..f678fce 100644 --- a/skills/kvb-skill-dream/SKILL.md +++ b/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 -scripts and tests the window's sessions wrote outside a repository. All keep +for the operator corrections the window revealed, `kvb-transcend` for the +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 diff --git a/skills/kvb-skill-essence/SKILL.md b/skills/kvb-skill-essence/SKILL.md index 856c385..2558976 100644 --- a/skills/kvb-skill-essence/SKILL.md +++ b/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: diff --git a/skills/kvb-skill-transcend/SKILL.md b/skills/kvb-skill-transcend/SKILL.md index ba81c4e..8ed1f70 100644 --- a/skills/kvb-skill-transcend/SKILL.md +++ b/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 -evidence. A script is portable only once its host paths, names and values +drop. A recurring deterministic move without a script goes to the +`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. diff --git a/skills/kvb-skill-tune/SKILL.md b/skills/kvb-skill-tune/SKILL.md index 9079084..432fefc 100644 --- a/skills/kvb-skill-tune/SKILL.md +++ b/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)`. diff --git a/skills/kvb-think-listen/SKILL.md b/skills/kvb-think-listen/SKILL.md index 5d4efe8..35fe847 100644 --- a/skills/kvb-think-listen/SKILL.md +++ b/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, - constraints or success criteria, and when another skill needs an - operator-only fact. + the task back. Trigger on unclear scope, constraints or success criteria, + or when a skill needs an operator-only fact. --- Do not act on a half-understood request. Listen actively until you could state