Kevin Veen-BirkenbachandClaude Opus 5.5
3c2f6c44b5
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>
1.9 KiB
1.9 KiB
Writing a skill
Persistence
Only under .claude/skills a skill is lost on the next install; only in the
repository it is not live until the next restart. Write both, in order:
- Locate the skills repository, first hit: the
SKILLS_REPOvariable; the current repository when it holdsskills-lock.jsonandskills/;pkgmgr path skills; a git checkout namedskillscarryingskills-lock.jsonunder~/Repositories/*/*/skills,~/git,~/srcor~/Projects. None: ask for the path with a single-select question; never write only the live copies. - Source of truth, the committed copy:
skills/<name>/SKILL.mdin that repository (portable) or in the current project (project-specific). - Mirror live: copy the whole skill directory, so hooks and references
come along, to
~/.claude/skills/<name>/and~/.agents/skills/<name>/; a project-specific one also to the project's.claude/skills/<name>/and.agents/skills/<name>/.
Report every written path. Delete or rename in reverse, mirrors included, or the old name keeps firing.
Content
- Frontmatter:
nameand adescriptionsaying what the skill does and when it triggers; it is the only part loaded in every session, so it decides whether the skill fires. - Body thin and single-purpose: the smallest instruction that changes behaviour; route to the authoritative doc instead of duplicating it.
- Optimizing makes a skill shorter or sharper, never longer: drop rules the
agent already follows, merge duplicates, cut every sentence that changes no
action. Route that compaction through the
kvb-skill-essenceskill (health pass for dead pointers and cross-skill duplicates first, ranked by what loads every session, diff before writing); answer its scope question with the skill being optimized. - Report the change in at most three lines, then
date +%s > ~/.claude/.autotune-stampso the next hint is an hour out.