Refactor skills

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:

1. 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.
2. 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.
3. Imperative voice. "Run X" > "You should run X" > "It is recommended to run X". Cut auxiliaries.
4. Concrete over abstract. Replace "use appropriate tools" with the actual tool name; replace placeholder code with code that runs.
5. One claim per bullet. Split bullets that say "do A and B and C" — the agent skims faster and misses less.
6. Cut dead weight. Repeated rules, restated context, "let me know if you need anything else", filler intros — gone.
7. Co-locate constraints. Rules buried in a trailing "Notes" section get missed. Move them next to the step they constrain.
8. 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

1. Inventory. git status --porcelain + the Edit/Write tool history. List candidate files with line counts. Filter to .md / .tmpl / .prompt under in-scope paths.
2. Read each file in full. Note its frontmatter purpose and structural divisions.
3. 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.
4. Confirm with the user. Show the diff plan; ask whether any item crosses the behaviour line. Wait for approval before any edit.
5. Apply via Edit. Use the Edit tool, not Write — minimal diffs are reviewable; full rewrites hide regressions.
6. Verify behaviour preserved. Re-read each file end-to-end. Workflow steps, rules, allowed-tools, and trigger conditions must read the same.
7. 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.