Skill Cleaner

A focused editing pass over a single skill. The goal is a version that reads easily and flows well — for both a human and the agent executing it — with no instructions that contradict each other, while staying thorough and protecting every behavior. Often that means less prose, but not always: a skill that's long because it carries genuinely important information should stay that way. Length is not the enemy — confusion is. Tightening wordy passages, fixing structure that reads out of order, and reconciling instructions that fight across sections all serve that goal. Raw line-count reduction is a side effect, never the objective.

Skills accrete over time. Each incident adds a sentence, each correction adds a hedge, each new edge case adds a paragraph. After enough rounds the skill grows past the point where the model can hold it all in working memory, and ironically starts following it worse than the original draft. This skill is the counterweight: an honest pass that asks of every line "is this still pulling its weight?"

Accretion also breeds contradictions: a fix bolted onto a late step can quietly conflict with a rule written for an early one, or a "see the X skill / see Step Y" pointer can lead somewhere that undercuts the instruction that sent you there. Those are the most damaging defects to leave in — the agent can't tell which instruction wins, so it guesses, and the guess is what ships. Finding and resolving them matters as much as trimming filler.

What this skill is not

• Not a restyle. Don't impose a different writing style, don't introduce new conventions, don't rewrite passages just to sound different — the user's voice stays. Structural changes are in scope, but only to fix a real problem: reordering a prerequisite that's introduced too late, merging two sections that overlap or contradict, smoothing a jarring transition. The line is — restructure to fix a genuine readability or consistency defect, never for taste.
• Not a feature change. Don't add new instructions, don't broaden or narrow what the skill does, and don't fix a workflow bug you spot (an instruction that's simply wrong) — list those in the report instead. Resolving a contradiction between two existing instructions is different and is in scope: you're not changing what the skill does, you're making it say one thing instead of two opposing things. When the correct resolution is genuinely unclear (both sides look intentional), don't guess — pick the reading the skill's why supports, and flag it in the report so the user can confirm.
• Not aggressive. When in doubt, keep the line. The cost of an over-zealous trim (a regression months later that no one can trace) is much higher than the cost of leaving a slightly verbose paragraph alone.

Inputs

The user (or calling skill) names a target skill — usually by path (skills/<name>/SKILL.md) or short name (ship, ticket, etc.). If only a short name is given, find it under skills/ at the repo root. If multiple skills are named, clean them one at a time and produce one report per skill.

If the target is in .agents/skills/ or .claude/skills/, stop and tell the user. Those are external meta-skills installed via npx skills update and any edit will be overwritten on the next update. They are out of scope.