Skip to content
Get packs

Safe Code Refactoring

Guides the agent through test-backed, step-by-step refactoring of existing code using Martin Fowler's method.

Source Download skill
Repository
luongnv89/claude-howto
Stars
46,401
Licence
MIT
Files
4 files

What it does

When you ask the agent to clean up, restructure, or reduce technical debt in code, this skill makes it follow a careful process instead of rewriting everything at once. It checks for tests first, looks for common code smells (such as overly long functions or duplicated code), proposes a phased plan, and then changes the code in small steps, pausing for your approval at each stage. The goal is to improve structure without changing how the software behaves.

Great for

  • Developers maintaining legacy or messy codebases who want safer, incremental cleanup
  • Teams that want refactoring plans with risks and rollback steps documented before changes are made
  • Engineers who want a structured checklist for reviewing code quality before and after a refactor

Skip it if

  • Projects with no tests where you do not want the agent to make changes without a strong safety net; the skill itself warns this is risky and requires explicit consent
  • Quick one-line fixes or new feature work, since the multi-phase process adds overhead
  • Code that relies on undocumented business logic or external APIs, where the skill says the agent should stop and ask rather than guess

Try asking

  • “Refactor the processOrder function in src/orders.js, which has grown too long, using small tested steps”
  • “Review this Python module for code smells and propose a prioritised refactoring plan before changing anything”
  • “Help me remove dead code and reduce duplication in our legacy Java service, one change at a time”
  • “Assess our test coverage and tell me whether it is safe to start refactoring the billing module”
Step-by-step guide: how to use Safe Code RefactoringInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 4 original files, the MIT licence and an attribution note.

    refactor.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip refactor.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip refactor.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Start by confirming your tests exist and pass, since the skill will stop and ask if they do not.
  • Approve the plan phase by phase; the skill is designed to pause for your decision before implementing each stage.
  • Ask for a review of the diff and metrics at the end, and keep the commits the skill proposes so changes can be reverted easily.

What's inside

  • references/code-smells.md
  • references/refactoring-catalog.md
  • SKILL.md
  • templates/refactoring-plan.md

Redistributed unmodified from luongnv89/claude-howto under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.