feat(essence): compact skills and memory by what loads every session

Skills and MEMORY.md grow by accretion, and the cost is not spread evenly. MEMORY.md and every skill description load into every session; bodies load only when the skill fires; memory files only on recall. A 200-line body that fires twice a month costs less than four bloated pointers. essence ranks the work that way and reports the saving for the always-loaded surface separately, because that is the number the run exists for.

A health pass runs before anything is cut: pointers without a file and files without a pointer, dead wikilinks, memories citing a file:line that no longer exists, one rule restated across several skills, a first-party skill shadowing a locked one, and a description that says what a skill does but never when it fires. Dead entries are deleted rather than compacted, and nothing is compacted around a stale citation, or the error survives in denser form.

Two things are never cut: the evidence behind a memory, because a rule stripped of its incident degrades into an exhortation and stops changing behaviour, and any fact with no other home. Two memories whose evidence differs are never merged.

Writing is in place, since an essence beside the original saves nothing. Guarded by a clean git status for the rewritten paths, .pre-essence copies for ~/.claude and ~/.agents which are not under git, and a diff with the saved lines and characters before one confirmation. Scope is asked with checkboxes and nothing outside it is touched.

autotune routes its optimisation step here instead of trimming by hand. essence still asks for its scope on that path; the operator answers with the skill being optimised.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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`.
 

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
+  `<file>.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.