diff --git a/skills/autotune/SKILL.md b/skills/autotune/SKILL.md index 9e63ac4..c440cfb 100644 --- a/skills/autotune/SKILL.md +++ b/skills/autotune/SKILL.md @@ -105,7 +105,11 @@ reverse — remove the mirrors too, or the old name keeps firing. behaviour. Route to an authoritative doc instead of duplicating it. - Optimizing an existing skill means the file gets shorter or sharper, not longer. Delete rules the agent already follows, merge duplicated ones, and - cut every sentence that does not change an action. + cut every sentence that does not change an action. Route that compaction + through the `essence` skill instead of trimming by hand: it runs a health + pass for dead pointers and rules duplicated across skills before cutting + anything, ranks by what loads in every session, and shows the diff before it + writes. It asks for its own scope — answer with the skill being optimized. - Report what changed in at most three lines, then refresh the reminder stamp so the next hint is an hour out: `date +%s > ~/.claude/.autotune-stamp`. diff --git a/skills/essence/SKILL.md b/skills/essence/SKILL.md new file mode 100644 index 0000000..cd17a06 --- /dev/null +++ b/skills/essence/SKILL.md @@ -0,0 +1,117 @@ +--- +name: essence +description: > + Compact skills and memory down to their essence so every session loads less + context, after a health pass that finds the dead weight first. Trigger on + /essence, or when the operator says the skills or MEMORY.md have grown too + long, carry duplicates, or eat too much context. Portable across projects. +--- + +Shorter, not thinner. Every fact that still earns its place survives; what goes +is repetition, narration, and entries nothing loads any more. + +## What actually costs context + +Compact by how often a thing is loaded, not by how large it is: + +1. **`MEMORY.md`** and every skill's **`description`** frontmatter load into + *every* session. A wasted line here is paid on every single turn. Highest + leverage by a wide margin. +2. **Skill bodies** load when the skill fires. Worth tightening, paid only on use. +3. **Memory files** load on recall. Lowest leverage — and the place where + cutting evidence does the most damage. + +A 200-line skill body that fires twice a month costs less than four bloated +`MEMORY.md` pointers. Rank the work accordingly and say so in the report. + +## Step 1: ask for the scope + +Never assume the target. Ask once with `AskUserQuestion` and +`multiSelect: true`, so the operator can tick several: + +- **Skills repository** — the portable `skills/*/SKILL.md` set. +- **This project** — its `.claude/skills` and `.agents/skills`, plus the + project's memory directory and `MEMORY.md`. +- **Home** — `~/.claude` and `~/.agents` (skills, rules, commands, agents). + +Take nothing outside what was ticked. + +## Step 2: doctor + +Before compacting anything, find what is already broken or dead. Report each +finding with its path: + +- A `MEMORY.md` pointer whose file is gone, and a memory file no pointer names. +- A dead `[[wikilink]]` — no memory of that name exists. +- A memory asserting a `file:line`, function, or flag that no longer exists. + Verify against the current tree; a stale citation is worse than no memory, + because it reads as checked. +- The same rule stated in two or more skills. One is authoritative, the rest + are drift. +- A first-party skill shadowing a locked/vendored one. +- Frontmatter missing `name` or `description`, or a `description` that says + what the skill does but never when it fires — such a skill costs context in + every session and never triggers. + +Dead entries are deleted, not compacted. Fix the broken ones or report them; +never compact around a stale citation, or the error survives in denser form. + +## Step 3: compact + +Cut: + +- Anything the repository already records — code structure, git history, what + `CLAUDE.md`/`AGENTS.md` already say. +- A rule the agent follows anyway without being told. +- 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. + +Keep, always: + +- The **why** and the evidence behind a memory — the date, the incident, the + quoted correction. A rule stripped of its evidence degrades into an + exhortation and stops changing behaviour. +- Any fact with no other home. If it exists nowhere else, it is not redundancy. +- Trigger wording in a `description`. Tighten it, never drop the "when". + +Dates stay absolute. Never introduce "recently" while shortening. + +## Step 4: show the diff, then write + +Writing happens in place — an essence that lives beside the original saves +nothing, because the original is still what loads. + +Preconditions, per target: + +- A git repository must have a clean status for the paths being rewritten, so + every edit is revertable with git alone. Not clean: report and stop. +- `~/.claude` and `~/.agents` are usually not under git. Copy each file to + `.pre-essence` first. + +Then present, per file: the diff, and the lines and characters saved. Ask for +one confirmation covering the batch. Write only after it. + +## Step 5: verify + +- Re-run the target's own validation if it has one (in a skills repository, + its test suite: frontmatter, lock, shadowing). +- Re-read each rewritten file and confirm every kept fact is still stated, not + merely implied by something shorter. +- Report the before/after loaded-context figure for the always-loaded surface + (`MEMORY.md` plus all descriptions) separately from the rest. That number is + the point of the run. + +## Rules + +- Deleting is the goal; rewriting shorter is the fallback. Prefer removing an + entry over polishing it. +- Never merge two memories whose evidence differs. Two incidents supporting one + rule are stronger than one; two rules sharing one incident is a fabrication. +- A skill that has never fired is a candidate for deletion, not compaction — + say so and let the operator decide. +- Nothing is written without the Step 4 confirmation, and nothing outside the + scope ticked in Step 1. +- `caveman-compress` is not a rival: it rewrites the wording of one named file, + this removes what should not be there at all. Run this one first — compressing + a dead entry is pure waste.