refactor(skills): cap every SKILL.md at 600 words and cut agent messages

Every loaded SKILL.md and every listed description is paid on every turn of every session, and every delivered message costs its recipient a full turn. scripts/budget.py gains SKILL_WORDS = 600, enforced by test_lock, and test_naming forbids a skill naming its own slash command; 53 descriptions and 10 body lines drop it. The 18 longest skills move details into 31 side files read only in their situation (organize's capacity, succession, peers, offices, relay and lineage; cleanup's docker, worktrees, execute and ask; code-tune, changelog, triage, dream, split and others), so all SKILL.md files shrink from 33866 to 26291 words without dropping a rule; an independent review of HEAD against the new text found no loss in 60 of 64 skills and three weakenings, now restored (WSJF re-estimates after an objective change, cleanup's volume checklist, essence's absolute dates).

The kvb-org-organize Peer protocol sends status that asks nothing to the news board, answers nothing that asks nothing, keeps messages terse, and lets light runs admit themselves in the operator's wording; the skills follow it (operator reads the register, relax and wakeup reply through the news, evening collects them there, wsjf asks only for missing estimates, cleanup and triage batch their questions). Skills that explore code ask the codebase-memory-mcp graph first, subagent briefs scale with the stakes and cap their answers, and the skills that need the full register or council tables call show --wide or list --long.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-04 17:07:23 +01:00
1 parent 34b434a744
commit 3c2f6c44b5
99 files changed
+2110 -2086

No files matched your search

+23 -24
View File
@@ -2,20 +2,19 @@
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.
Trigger on 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.
A deterministic step's result follows from its inputs alone: fixed command
sequences, output parsing and filtering, counting, thresholds and arithmetic,
format checks, sorting and lookups, state bookkeeping. Such steps become
scripts and their prose shrinks to the call; choosing, explaining and asking
stay prose. Nothing changes 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:
The skills named after the command, else every skill of the current
repository. 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
@@ -24,23 +23,22 @@ repository when none is named. Per skill, its owning repository:
- **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.
compiled; propose the change upstream.
## 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:
Read-only. Per skill, every deterministic step 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:
Compile what runs often or went wrong; a one-off stays 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.
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.
@@ -58,13 +56,14 @@ 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.
(`${CLAUDE_SKILL_DIR}/scripts/<verb>.py ...`) and one line on reading its
output.
- Every script gets a unit test with a negative control shown once, run once
`watch.py admit --kind test-nostack` (the `kvb-org-organize` skill) prints
`grant`; `make test` keeps the chair's grant.
- 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