| name | refactor-skills |
| description | Reviews the markdown and template files changed in the current session and tightens them for agent performance — sharper trigger descriptions, progressive disclosure, imperative voice, one-claim-per-bullet, fewer redundant rules — while preserving every workflow step, constraint, and trigger condition. Use when the user has just edited one or more skill or prompt files (`SKILL.md`, `references/*.md`, `recipes/*.md`, agent templates, slash-command prompts) and wants a tightening pass before committing, or invokes "/refactor-skills", "refactor this skill", "tighten the skill", "polish SKILL.md", "make this skill leaner". Behaviour-preserving only — never use this to add features, expand scope, or remove rules. |
| allowed-tools | Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git ls-files:*), Bash(rg:*), Bash(wc:*), Read, Edit, Grep |
Refactor Skills — agent performance ↑, behaviour =
Tightens the markdown / template / skill files touched in the current session. Every edit must make the file cheaper or clearer for an agent to load and act on, without changing what the skill does.
Inputs
- Default: every uncommitted
.md, .tmpl, .txt, and .prompt file under .claude/, ~/.claude/, docs/, or any path the session has been editing. Discover with git status --porcelain plus the Edit/Write tool history of the current conversation.
- If the user names specific files or a directory, restrict to those.
- Skip files outside
.claude/, docs/, or the user-specified scope; this skill is not a general prose editor.
Agent-performance heuristics
Apply in this order. Each is a no-behaviour-change edit:
- Sharper trigger description. The frontmatter
description is the only thing the harness sees when ranking skills. Lead with the capability in 1 sentence; follow with "Use when …" listing concrete phrases the user actually says. Drop hedging ("might be helpful for …") and synonyms that add no discoverability. Keep ≤ 1024 chars.
- Progressive disclosure.
SKILL.md stays under 100 lines. Anything longer, domain-heavy, or rarely needed → move to references/<topic>.md and link from SKILL.md. The agent only loads SKILL.md by default.
- Imperative voice. "Run X" > "You should run X" > "It is recommended to run X". Cut auxiliaries.
- Concrete over abstract. Replace "use appropriate tools" with the actual tool name; replace placeholder code with code that runs.
- One claim per bullet. Split bullets that say "do A and B and C" — the agent skims faster and misses less.
- Cut dead weight. Repeated rules, restated context, "let me know if you need anything else", filler intros — gone.
- Co-locate constraints. Rules buried in a trailing "Notes" section get missed. Move them next to the step they constrain.
- Examples match the description. If the description claims "use when X", an example must contain X verbatim.
What you must NOT change
These are behaviour. Touching them changes what the skill does:
- The set of workflow steps (rename or reorder for clarity, but never drop, add, or merge).
- Any explicit
must / do not / never rule — the user codified those deliberately.
- The
allowed-tools: list in frontmatter.
- Required artefact paths, file naming conventions, output formats.
- Trigger scope in the description (sharpen wording, never narrow or broaden which situations match).
- Examples that document edge cases — those are tests of the description's contract.
If unsure whether a change is performance or behaviour, ask the user before applying.
Workflow
- Inventory.
git status --porcelain + the Edit/Write tool history. List candidate files with line counts. Filter to .md / .tmpl / .prompt under in-scope paths.
- Read each file in full. Note its frontmatter purpose and structural divisions.
- Per-file diff plan. For each file, list heuristic violations as
heuristic → location → proposed change. One bullet per violation. Do not write the rewrite yet.
- Confirm with the user. Show the diff plan; ask whether any item crosses the behaviour line. Wait for approval before any edit.
- Apply via Edit. Use the Edit tool, not Write — minimal diffs are reviewable; full rewrites hide regressions.
- Verify behaviour preserved. Re-read each file end-to-end. Workflow steps, rules, allowed-tools, and trigger conditions must read the same.
- Report. Per file:
<path>: <before> → <after> lines. Key wins: <2-3 bullets>.
Final assistant-message summary
Refactored N file(s).
- <path>: <before> → <after> lines. <one-line headline change>
- <path>: <before> → <after> lines. <one-line headline change>
Behaviour preserved: workflow steps, rules, allowed-tools, triggers unchanged.
If any file was left untouched (already tight, or change would cross the behaviour line), say so explicitly with the reason.
