Audit CLAUDE.md and .claude/rules for always-loaded content that should become an on-demand skill. Use when CLAUDE.md feels bloated, trimming context, or promoting a rule into a skill.
Audit CLAUDE.md and .claude/rules for always-loaded content that should become an on-demand skill. Use when CLAUDE.md feels bloated, trimming context, or promoting a rule into a skill.
args
[scope-path]
argument-hint
[scope-path]
name
meta-context-diet
meta-context-diet
Audit always-loaded context — CLAUDE.md files and .claude/rules/*.md — for material that would be cheaper and clearer as an on-demand skill, then migrate approved candidates — per-candidate confirmation for lossy edits, batched approval for the safe ones.
The premise: CLAUDE.md and unscoped rules are paid for on every turn. A skill costs only its name + description in the listing budget until its intent fires, then loads its body on demand. Anything that is not a hard, always-respected invariant is a candidate to move off the always-loaded surface.
When to Use This Skill
Use this skill when...
Use a different skill when...
CLAUDE.md or .claude/rules/ has grown heavy and you want to find what can move to on-demand skills
You want to move rules/skills between scopes (project → user-global) — use meta-promote
A rule is really a procedure/workflow triggered by intent, not an always-true invariant, and should be a skill
You want to turn a finished session's learnings into new rules — use session-distill
You want a per-item keep / path-scope / promote-to-skill / consolidate decision over the always-loaded surface
You want skill-to-skill overlap and split-pressure analysis — use health-skill-audit
You suspect rules duplicate plugin skills already loaded for the session
You only want frontmatter/size hygiene on existing skills — use scripts/plugin-compliance-check.sh
User-global rules are resolved during execution (Step 1), not here — $HOME paths and error redirection are disallowed in Context commands.
Parameters
Parse $ARGUMENTS:
scope-path (optional, default ) — the directory whose and are audited. Use a child path (e.g. ) to scope the diet to one area. The user-global surface is audited too unless names a non- project.
.
CLAUDE.md
.claude/rules/
someplugin
~/.claude/
scope-path
.
Your task
Execute this audit and, on approval, migrate each candidate. Never make a lossy or destructive edit to an always-loaded file without explicit per-candidate confirmation — CLAUDE.md and rules are shared, every-turn context and a lossy edit degrades every downstream turn. Non-destructive dispositions on a large surface may be batch-approved (Step 4).
1. Inventory the always-loaded surface
Build the candidate list from three sources:
Source
Path
Loaded
Root memory
<scope>/CLAUDE.md (+ nested CLAUDE.md)
Every turn, in full
Unscoped rules
<scope>/.claude/rules/*.mdwithout a paths: frontmatter glob
Every turn, in full
Path-scoped rules
<scope>/.claude/rules/*.mdwith a paths: glob
Only when editing matching files
When scope-path is . (or names the user-global tree), also Glob(pattern="$HOME/.claude/rules/**/*.md") and the root $HOME/.claude/CLAUDE.md during execution — that surface is the heaviest every-turn cost. The plugin-skill list already loaded for this session is in the session prompt; scan it by name when checking the Consolidate disposition.
For each file, record its size (wc -c, est. tokens ≈ chars/4 — same proxy as skill-quality.md) and, for CLAUDE.md, treat each ## section as a separately-classifiable unit. Path-scoped rules already pay only on matching turns — flag them only if they are also intent-shaped (a better skill) or duplicate a loaded plugin skill.
2. Classify every unit against the diet rubric
For each rule file or CLAUDE.md section, assign exactly one disposition. The deciding question is "must this be true on every turn regardless of what the user asked?"
Disposition
The unit is…
Signal
Keep — hard invariant
An always-respected constraint whose violation is a bug even when unmentioned (security boundaries, "never force-push", commit-format that drives release automation, destructive-op guards)
Imperative, unconditional, cheap to keep; the cost of missing it is high
Keep but lean
A hard invariant wrapped in explanation, examples, or tables that belong in a linked doc/REFERENCE
The invariant is one sentence; the file is 200 lines
Path-scope
Always-true only when working on a specific file shape (a language, a config format, a directory)
Advice keyed to "when editing X"; currently unscoped so it loads on every turn
Promote to skill
A procedure/workflow triggered by intent — steps you run when doing a task, not a constraint you hold while doing anything
Reads as "to do X: step 1…step N"; has a clear trigger ("when releasing", "when the build fails"); rarely relevant per-turn but heavy when present
Consolidate
Duplicates another rule, a loaded plugin skill, or upstream ~/.claude/rules
The same guidance exists elsewhere already paid for
Drop
Stale, obsoleted, or superseded
References removed tooling / closed migrations
The dominant find is usually Promote to skill: a rule that began life as "write down this procedure so I don't forget it" but is really an intent-triggered workflow. The litmus test — if the user never raises this topic, does the guidance still need to be in context? If no, it is a skill.
3. For each promote-to-skill candidate, design the target skill
A rule only earns promotion if it can carry a description good enough to auto-trigger — otherwise moving it off the always-loaded surface silently loses the guidance. Draft, before proposing:
Skill home + name — a new skill in an existing plugin, named per skill-naming.md (<namespace>-<name>). If no plugin fits, recommend keep-but-lean instead.
Description — front-load tool/verb/domain, then a Use when… clause with the literal phrases a user would say; target ≤150 chars (skill-quality.md). This is the load-bearing artifact: if you cannot write a description that fires on the right intent, the content is not skill-shaped — reclassify as keep-but-lean or path-scope.
Body shape — the procedure as imperative ## Execution steps (skill-execution-structure.md); large tables go to REFERENCE.md.
Residual stub — typically a one-line pointer (> For the X workflow, see the \plugin:skill` skill.`) so a reader at the old location is routed without re-paying the body cost.
4. Confirm before writing — per candidate, batch only the safe dispositions
For each candidate, present:
The file/section and its size (chars + est. tokens).
The recommended disposition with a one-sentence justification.
For promote-to-skill: the drafted skill home, name, and description.
The disposition menu via AskUserQuestion (Keep / Lean / Path-scope / Promote-to-skill / Consolidate / Drop / Skip).
Only proceed on explicit approval. Order the prompts by impact (largest always-loaded char count first) so the biggest wins surface early.
The confirmation shape depends on how lossy the disposition is, not on convenience:
The guidance survives in place — leaning trims explanation, path-scoping only narrows when it loads. Nothing is removed from the always-loaded surface's meaning.
Each removes guidance from an always-loaded file: Drop deletes it, Consolidate-that-deletes replaces it with a pointer, Promote-to-skill moves the body off the every-turn surface. A wrong call degrades every downstream turn, so the user confirms each individually.
Batch-approval mode for large surfaces
For a large audit — roughly ~15+ candidates, where the per-candidate loop is ~15+ round-trips — prompting individually for every non-destructive disposition is needless friction. In that case, group the non-destructive candidates by disposition tier and offer one tier-grouped multi-select AskUserQuestion per tier: the user checks the candidates to approve in a single round-trip (e.g. "Path-scope these 9 rules", "Keep-but-lean these 6"). Put each candidate's file, size, and one-sentence justification in its option so the user can deselect any to hold back.
Per-candidate confirmation stays mandatory for the destructive/ambiguous tier — Drop, Consolidate-that-deletes, and Promote-to-skill are never batched, regardless of audit size. The invariant is unchanged: no lossy or destructive edit to an always-loaded file lands without an explicit per-candidate confirmation. Batch mode only fast-paths the dispositions that preserve the guidance in place.
For a small audit (fewer than ~15 candidates) the per-item loop is cheap — prompt each candidate individually and skip batch mode.
5. Execute the approved disposition
Disposition
Mechanics
Keep — hard invariant
No change. Optionally note why it stays in the report.
Keep but lean
Edit the rule to the invariant + a link; move examples/tables to a co-located doc or the rule's own REFERENCE-style sidecar. Do not change the invariant's wording.
Path-scope
Edit the rule's frontmatter to add a paths: glob so it loads only on matching turns. Verify the glob matches the directory shape the rule actually targets.
Promote to skill
Scaffold <plugin>/skills/<name>/SKILL.md with the drafted frontmatter + imperative body; move reference material into the new skill's REFERENCE.md; trim the source rule to a one-line pointer (or delete it if nothing remains and nothing references it). Then update the plugin metadata per the Plugin Lifecycle in CLAUDE.md (README skills table; no marketplace.json/release-config edits — those are plugin-scoped, not skill-scoped, per skill-consolidation.md). Run /reload-skills so the new skill is invocable immediately.
Consolidate
Edit the source to a pointer at the canonical owner by plugin:skill name (never a cross-plugin file path — see skill-consolidation.md); or delete the redundant rule if a loaded plugin skill already covers it.
Drop
Delete the stale file.
After every write, run git status so the user sees exactly what changed before any commit. Do not commit — leave a clean tree the user can review and split. When promoting out of a CLAUDE.md or rule that lives in a chezmoi-managed tree (~/.claude/), surface that the source is chezmoi-managed so the edit lands in the source, not the target.
6. Report
Emit a final table and the net context saving:
Unit
Size (tok)
Disposition
Target
Always-loaded delta
.claude/rules/foo.md
~1,200
Promote to skill
someplugin:foo-workflow
−1,200
CLAUDE.md § Bar
~300
Keep but lean
linked docs/bar.md
−260
.claude/rules/baz.md
~400
Path-scope
paths: "**/*.py"
conditional
End with: total tokens removed from the every-turn surface, the new skills created (with their trigger descriptions), and the next step (review git status, commit per concern with conventional-commit messages — this skill does not commit).
Anti-patterns to avoid
Don't
Do
Promote a hard invariant to a skill because it "looks like a procedure"
Keep anything whose violation is a bug even when the user never mentions it — a skill only fires on intent
Move a rule to a skill with a weak description
The description must auto-trigger on the real intent; if you can't write one ≤150 chars that fires, it is not skill-shaped — lean it or path-scope it instead
Bundle a destructive disposition (Drop / Consolidate-that-deletes / Promote-to-skill) into a batch approval
Per-candidate AskUserQuestion for anything lossy; batch only the non-destructive tier (Keep / Lean / Path-scope) on a large surface
Delete the rule entirely after promotion when something still references it
Leave a one-line pointer stub; grep -rn the old rule name first
Edit the chezmoi target (~/.claude/...) directly
Edit the chezmoi source (chezmoi source-path), then apply
Commit the diet as part of the skill
Leave a clean working tree; the user commits per concern
Notes
Reads broad, writes narrow — discovery scans the whole always-loaded surface; the write phase touches only approved files.
Inverse of session-distill (creates rules from sessions), orthogonal to meta-promote (moves config between scopes). The three compose: distill captures learnings as rules, the diet promotes the intent-shaped ones to skills, meta-promote lifts shared ones up a scope.
