refactoring-code — Claude Code skill: what it does, how to install
refactoring-code is a Claude Code skill that stages simplification refactors: approve the plan before edits, then check that behaviour stays the same.
no license 124 installs ★ 3 updated 2026-10-25
npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-codeWhat refactoring-code does
This skill runs a simplification refactor in stages, with behaviour as the thing you must not break. No edit lands before the plan is approved, and each run handles one target file. Raw code and diffs stay inside subagents, so only short reports travel between phases.
Four subagents do the work: behavior-mapper records the baseline and the risky spots, chunk-analyst takes one analysis dimension per chunk, refactor-implementer applies the approved plan, refactor-reviewer returns two verdicts — behaviour preserved, and did the code get simpler. The reuse ladder and deletion test sit in references/simplification-heuristics.md, hard stops in references/protected-surfaces.md, reports in .handoffs/refactoring-code/. Only TARGET_PATH is required, and MAX_LINES defaults to 250.
AUTO_APPROVE=true keeps the gates. The plan card passes on its own only when it carries no size waiver, no validation command outside safe, and no protected-surface carve-out; anything else ends the run as NEEDS_CLARIFICATION. Touching a protected surface stops the run, and re-approving a wider fix scope under AUTO_APPROVE always returns BLOCKED.
What it helps with
- split a large file without changing behaviour
- strip duplication before adding new code
- rename or move a module and keep tests green
- find out which files a refactor must not touch
- follow a refactor through short reports instead of raw diffs
Example prompts for the agent
- Simplify
src/billing/invoice.ts, keep behaviour identical, tests:npm test -- invoice - Split
src/api/router.ts, cap at 300 lines, leave protected surfaces alone - Look at
src/queue/worker.tsand tell me what could be simplified, plan only
How to install refactoring-code
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code2Manually: put the files in place
~/.claude/skills/refactoring-code/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/refactoring-code/
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill refactoring-code -a codex2Manually: put the files in place
.agents/skills/refactoring-code/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill refactoring-code -a cursor2Manually: put the files in place
.cursor/skills/refactoring-code/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install b-mendoza/agent-skills skills/refactoring-code2Manually: put the files in place
.github/skills/refactoring-code/SKILL.md1Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill refactoring-code -a gemini-cli2Platform CLI
gemini skills install https://github.com/b-mendoza/agent-skills --path skills/refactoring-codeManually: put the files in place
.devin/skills/refactoring-code/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add b-mendoza/agent-skills --skill refactoring-code -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about refactoring-code
How do I install refactoring-code in Claude Code?
Run npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code. The skill ends up at ~/.claude/skills/refactoring-code/SKILL.md.
What does refactoring-code do?
It drives a simplification refactor through phases: baseline, plan, approved edits, then a check that behaviour did not change. Code and diffs never leave the subagents.
What happens if an edit reaches a protected surface?
The run stops. Crossing references/protected-surfaces.md counts as a hard stop until the user reframes the task outside this skill.