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

+19 -23
View File
@@ -6,29 +6,25 @@ description: >
repeating themselves.
---
Its objective is the `kvb-skill-tune` skill's **Objective** section: a skill is worth
creating only when it cuts tokens or time and raises quality; judge every
candidate against its three axes and rules.
Its objective is the `kvb-skill-tune` skill's **Objective** section: a skill is
worth creating only when it cuts tokens or time and raises quality; judge
every candidate against its three axes and rules.
When you notice the operator repeating the same kind of instruction,
correction, or prompt pattern (about three occurrences, exact wording may
vary), do the following:
When the operator repeats the same kind of instruction, correction or prompt
pattern (about three times, wording may vary):
1. Finish the current task first; never interrupt work in progress.
2. Then propose, in one short paragraph: the repeated pattern you observed,
a skill name suggestion, the trigger phrasing, and what the skill would
do. Ask whether to create it.
3. On approval, write the skill: persist it exactly as the
`kvb-skill-tune` skill's **Persistence** section specifies — locate the
operator's skills repository, write `skills/<name>/SKILL.md` there (or in
the current project for project-specific behavior), then mirror the skill
directory into `~/.claude/skills/` and `~/.agents/skills/`, plus the
project's `.claude/skills/` and `.agents/skills/` when it is
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. 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.
2. Then propose in one short paragraph: the observed pattern, a skill name,
the trigger phrasing and what the skill would do. Ask whether to create
it.
3. On approval, persist it exactly as the `kvb-skill-tune` skill's
**Persistence** section specifies: write `skills/<name>/SKILL.md` in the
operator's skills repository (or the current project for project-specific
behavior), then mirror the skill directory into `~/.claude/skills/` and
`~/.agents/skills/`, plus the project's `.claude/skills/` and
`.agents/skills/` when project-specific. Follow the local naming
conventions; keep the skill thin and single-purpose, routing to an
authoritative doc instead of duplicating it. Its deterministic steps
become a script through the `kvb-skill-compile` skill, not prose.
4. No skill for one-off work, secrets, or repetition an existing skill
already covers; when one almost fits, propose extending it instead.