skill-review

name

skill-review

description

Audit Channing's authored skills for whether they earn their place — usefulness, overlap with other skills or Claude's built-in abilities, redundancy, gaps, and triggering quality. Use when asked to review, audit, critique, or prune skills; when wondering whether a skill is still worth keeping; or after writing or editing a skill. Reviews authored skills only: real dirs in ~/.claude/skills and ~/.claude/commands (symlinks skipped) plus the dev repo in ~/dev/skills/skills.

Skill Review

Audit Channing's authored skills and tell him, honestly, which ones earn their place and which are dead weight.

A skill costs context every session its description sits in the menu, and costs more when it loads. The bar for keeping one is not "is this reasonable advice" — it's "would Claude do worse without it?" Most skill bloat is advice Claude already follows by default, dressed up as instructions. Your job is to find that and call it out.

This is a critical review, not a rubber stamp. Be willing to recommend dropping or merging skills. A short report that says "three of these should be deleted" is more valuable than a polite one that keeps everything.

Scope

Default: review every authored skill. Discover them with the bundled script — it returns real dirs in ~/.claude/skills and ~/.claude/commands (skills exposed as slash commands, e.g. unison-update) plus everything in ~/dev/skills/skills. Symlinks are skipped on purpose: they point at install targets for third-party or already-published skills, which are out of authored scope (published ones are reviewed via their dev-repo source instead):

~/.claude/skills/skill-review/scripts/discover.sh

If Channing names a single skill, review just that one. Read each skill's full SKILL.md and skim any bundled scripts/, references/, or agents/ — a skill's weight includes what it pulls in.

What to judge

For each skill, work through these. They are ordered by how often they matter; the first is the heart of it.

1. Does it earn its place? Strip it down mentally to its claims. For each instruction ask: would Claude do this anyway? General language patterns, testing-framework basics, FP principles, "write clear commit messages", standard tool usage — Claude already does these. What remains should be project-specific tooling (e.g. devtool check, bloop detection), non-obvious conventions (e.g. opaque types over case classes for encapsulation), personal workflow (vault note layout, task-note sections), or fixed multi-step procedures Claude wouldn't reliably reconstruct. If little remains after stripping general knowledge, say so — the skill is a candidate to trim hard or drop.

2. Overlap with other skills. Compare against the full set of currently available skills (they are listed in your context as the available-skills menu) and against the other authored skills in this audit. Two skills with overlapping trigger conditions cause mis-routing — Claude picks the wrong one or hesitates. Flag pairs that do the same job, or where one is a strict subset of another, and recommend a merge or a sharper boundary.

3. Overlap with Claude's built-in abilities and harness. Some skills duplicate things the harness or built-in commands already do (git commit/PR flows, file search, running the app). If a skill is a thin wrapper over something Claude handles natively, that's a strike against it.

4. Triggering quality. The description is the only thing Claude sees when deciding to invoke. Does it say when to use the skill in concrete terms, not just what it does? Is it specific enough to fire on real phrasings but bounded enough not to fire on near-misses? Vague descriptions cause under-triggering (the common failure). Note descriptions that are all "what" and no "when".

5. Internal redundancy and bloat. Repetition across sections, restating Claude's defaults, heavy-handed ALWAYS/MUST/NEVER where a reason would work better, content duplicated from another skill it depends on. Note length relative to value.

6. Gaps and rot. Broken or stale pointers (a referenced script/path that no longer exists), TODOs, instructions that contradict each other, missing edge cases, references to defunct projects or tools. Cross-check bundled-resource paths against what's actually on disk.

Don't force every dimension onto every skill — report only what's true. A genuinely tight skill might get a one-line "earns its place, no changes".

Report

Print to the terminal. No files. Lead with the headline so Channing sees the verdict spread first.

# Skill review — <date from `date`>

Reviewed N skills.  Keep: a · Trim: b · Merge: c · Drop: d

## <skill-name>   —   <KEEP | TRIM | MERGE | DROP | REVISE>
<one-line rationale: the single most important reason for the verdict>

- <finding, tied to a dimension above, specific and actionable>
- <finding>
...

## <next skill> — ...

Verdicts:

• KEEP — earns its place, no material change.
• TRIM — keep, but cut identified bloat / general knowledge.
• MERGE — fold into another named skill; say which and why.
• DROP — delete; Claude does as well or better without it.
• REVISE — keep, but the content or triggering needs rework beyond trimming.

After the per-skill sections, add a short Cross-cutting block for issues spanning skills: overlapping pairs, a dependency that's itself weak, duplicated passages, gaps in coverage across the set.

Proposing edits

After the report, offer concrete edits for the skills that need them — but don't apply anything without approval. Channing reviews each change. Lead with the highest-leverage edits (a DROP or a big TRIM beats fixing a typo). For a TRIM, show what you'd cut. For a MERGE, show the combined description and where content moves. Apply only what he approves.