Skip to content
Get packs

Code Refactoring Assistant

Guides safe, test-backed refactoring of code using Martin Fowler's smell and catalog method

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

What it does

When installed, the agent follows a structured refactoring process instead of rewriting code freely. It checks for existing tests, identifies code smells (such as long methods, duplicated code, or large classes), proposes a written plan using Fowler's named refactorings, and makes small changes one at a time, asking for your approval at each phase. Optional helper scripts can scan Python, JavaScript, or TypeScript files for smells and measure complexity before and after changes.

Great for

  • Developers who want to clean up legacy or messy code in a controlled, step-by-step way
  • Teams reducing technical debt who want a written plan and approval checkpoints
  • Anyone who wants before-and-after complexity metrics to show a refactoring helped

Skip it if

  • Projects with no tests, unless you accept the risk of behaviour changes that go unnoticed; the skill recommends writing tests first but can proceed without them with your confirmation
  • Quick one-line fixes or new feature work, since the multi-phase process is heavier than needed
  • Languages other than Python, JavaScript and TypeScript for the bundled scripts, which only analyse those; the agent can still apply the general method to other languages

Try asking

  • “Refactor the payment module in this repo to reduce its long methods, keeping behaviour the same”
  • “Find code smells in src/orders.py and propose a prioritised refactoring plan”
  • “Measure the cyclomatic complexity of utils.js before and after we clean it up”
  • “Reduce the technical debt in this legacy service, starting with an inventory and tests check”
Step-by-step guide: how to use Code Refactoring AssistantInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 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

  • Point the agent at a specific file or module rather than the whole repository to keep the plan focused
  • Make sure tests pass and commit your work before starting, so each refactoring step can be reviewed or reverted
  • Review the proposed plan and the scripts' output before approving changes, since the agent will run commands in your project

What's inside

  • references/code-smells.md
  • references/refactoring-catalog.md
  • scripts/analyze-complexity.py
  • scripts/detect-smells.py
  • 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.