Refactoring Assistant
Proposes a refactor plan, then a minimal behavior-preserving diff — insisting tests pass before and after, in small safe steps.
What this skill does
Key features
- Writes a step-by-step refactor plan before touching any code
- Runs the test suite first and refuses to proceed if it is red
- Produces a minimal diff that preserves observable behavior
- Splits large changes into small, independently reviewable steps
Use cases
- Untangling a long function without changing what it does
- Renaming and reorganizing modules ahead of a feature
- Reducing duplication before adding new behavior
SKILL.md
The skill definition — its metadata and the exact instructions an agent follows. Copy it into a SKILL.md file in your agent's skills folder.
| name | refactor-assistant |
|---|---|
| description | Plan and produce a minimal, behavior-preserving refactor with tests green before and after. |
| allowed-tools | Read, Grep, Edit, Bash(git diff:*), Bash(npm test:*), Bash(pytest:*) |
| output | refactor plan + minimal diff |
| intent | behavior-preserving |
Musts
- Run the existing test suite BEFORE any change and record the result; if it is red or absent, stop and report that first.
- Write a numbered refactor plan (each step small and independently reversible) and present it before editing code.
- Keep every change behavior-preserving: no new features, no changed outputs, no altered public signatures unless the step is explicitly a rename with call sites updated.
- Produce a minimal diff — touch only what the step requires; do not reformat or reorder unrelated code.
- Re-run the full test suite after the change and confirm it is green; if it is not, revert the step rather than patching over it.
Guidelines
- Prefer many small steps (extract function, inline variable, rename) over one large rewrite.
- Name extracted units by what they do, not how; leave a one-line comment only where intent is non-obvious.
- When you spot a latent bug during refactoring, note it separately — do not fix it inside the refactor diff.
- Suggest, don’t apply blindly: propose the diff and let a human approve before it lands.
Output format
## Refactor plan
1. <small step> — why it is safe
2. <small step> — why it is safe
## Baseline
tests: <pass/fail/none> (<command run>)
## Step 1 diff
<unified diff, minimal>
## After step 1
tests: <pass/fail> (<command run>)FAQ
Will it change what the code does?
No. A refactor here is behavior-preserving by definition. If a genuine behavior change is needed, it stops and flags it separately rather than smuggling it into the refactor.
What if there are no tests?
It says so plainly and proposes the smallest characterization test that pins current behavior before refactoring. It will not refactor blind and claim safety it cannot back up.
Before running any skill, read its instructions and the tools it's allowed to use, and test it on a safe target first. See LLM security best practices.