Guide · Agent skill

How to use the Code Refactoring (Fowler method) agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The refactor skill is a set of instructions that tells a Claude agent how to restructure existing code using the approach from Martin Fowler's book Refactoring (2nd edition). Instead of editing freely, the agent works through six stages: research, test coverage, code smell identification, planning, incremental changes, and review. This guide explains what the skill does, how to install it, how to trigger it, and where its limits are.

Code Refactoring (Fowler method)luongnv89/claude-howto · MIT Download the skill

Quick start

1Download and unzip. Download the skill ZIP from this page and unzip it. The folder should contain SKILL.md.
2Place the folder. Move the refactor folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for one project.
3Or upload it in the apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
4Make a scoped request. Ask for a refactor in plain language and name the file, module or function you want to change.
5Answer the clarifying questions. Tell the agent the goal, any code that must not change, and whether tests exist and pass.
6Approve the smell report and plan. Review the prioritised smells and the staged plan, then approve each stage before edits begin.
7Review each change. Check the small changes as they are made and ask the agent to pause or repeat a stage if needed.

What the refactor skill makes the agent do

Refactoring means changing the internal structure of code without changing its external behaviour. The skill is built on five core principles: behaviour must be preserved, changes should be small and testable, tests act as the safety net, refactoring is continuous, and the user must approve at each stage.

When you ask for a cleanup, the agent first asks clarifying questions about scope, goals, areas that must not change, time pressure, and whether tests exist and pass. It then checks for tests, identifies code smells such as long methods or duplicated code, and proposes a plan that maps each smell to a standard refactoring.

Stage 1: Research and analysis, ending with a summary you must approve
Stage 2: Test coverage review, with a decision point if tests are missing or failing
Stage 3: Code smell identification, with a prioritised report
Stage 4: Refactoring plan, grouped into quick wins, structural changes and architectural changes
Stage 5: Incremental implementation
Stage 6: Review and repeat

Install the refactor skill

Download the ZIP file for the skill from this page. The skill is distributed as a folder containing SKILL.md, so you need to unzip it and place the folder where your agent can find it.

For a personal install that works across projects, unzip the skill into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/refactor/
Single project: .claude/skills/refactor/ inside your project folder
Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need a special command. The skill's description says it should be used when you ask to refactor code, improve code structure, reduce technical debt, clean up legacy code, remove code smells, or improve maintainability. Plain requests in those terms are the right way to trigger it.

Be specific about the scope. Naming a file, module or function helps the agent answer its first clarifying question without guessing.

"Refactor the payment module in src/billing to reduce duplication."
"Clean up the legacy order-processing code without changing its behaviour."
"Find code smells in utils/parser.py and propose a plan before changing anything."
"Reduce technical debt in the reporting service. Ask me about constraints first."

Run the test checks the skill expects

The skill checks whether tests exist and pass before it changes anything. It looks for test files and runs the test command your project uses. The source lists npm test for JavaScript and TypeScript, pytest -v for Python, and mvn test for Java, and it suggests coverage commands where available.

If the tests fail, the skill says to stop and fix them first. If tests are missing, it offers three options: write tests first (recommended), add tests while refactoring, or continue without tests after you accept the risk.

Tests pass: the agent moves on to code smell identification
Tests missing: choose to write tests first, add them gradually, or accept the risk
Tests failing: the agent stops and asks whether to fix the tests first

npm test
pytest -v
mvn test

Review the plan and approve each stage

The skill is designed to pause for sign-off. After the smell report, you approve the priorities. After the plan, you approve each stage before implementation starts. The agent is expected to explain its reasoning at these points.

Plan changes are ordered from lowest to highest risk. Quick wins such as renaming variables for clarity or removing dead code come first; architectural changes such as replacing conditionals with polymorphism come last.

Approve the smell priorities before planning starts
Approve the plan and ask "Should I proceed with Stage A?" before any edits
Ask for a pause or a smaller stage if a change feels too large

Optional smell detection script

The skill refers to an optional script, scripts/detect-smells.py, that can run automated smell analysis on a file. This script is not included in the provided file, so the skill will fall back to manual review if it is not present in your setup.

If you add the script yourself, the skill's instructions show it being called with a file path as the argument.

python scripts/detect-smells.py <file>

What people use it for

Cleaning up a long, duplicated function in an existing service without changing what it returns.
Adding tests and then extracting methods from a long method in code with weak coverage.
Planning the removal of dead code and renaming of unclear variables as low-risk quick wins.
Breaking up a large class by extracting a class, with a rollback plan written for each step.
Reviewing a legacy module for code smells and producing a prioritised list before any editing starts.

Frequently asked questions

Is the refactor skill free to use?

The source material for this skill is released under the MIT licence, as listed on this page. The source does not describe any pricing, so check the repository and your own Claude plan for access details.

What do I need to install the refactor skill?

You need the SKILL.md folder, which you can download as a ZIP from this page, and a place for it: ~/.claude/skills/, a project's .claude/skills/ folder, or the Claude apps under Settings → Capabilities → Skills. To run the test checks, your project needs its own test tooling, such as npm test, pytest or mvn test.

Does the refactor skill need internet access?

The listing says the skill does not use the network. It does run scripts, and it refers to an optional script, scripts/detect-smells.py, which is not included in the provided file.

Can I use the refactor skill on a project with no tests?

The skill recommends writing tests first. If you continue without tests, the skill asks you to acknowledge the risk. The listing advises against using it on projects with no tests that you cannot test.

Is this skill good for quick one-line fixes?

No. The multi-stage process adds overhead and is designed for structural improvement. For a small, single-line change, a direct request to the agent is more suitable.

Why does the agent keep asking me for approval?

The skill requires user sign-off at several checkpoints: after research, after the smell report, and before each implementation stage. This is intentional and is meant to keep changes cautious and visible.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the refactor skill if you maintain an existing codebase, especially legacy code with weak tests, and want the agent to plan, explain and pause for approval before editing. Pick something else if you need quick one-line fixes, new feature work, or if you are not comfortable reading code, running tests and tools like npm, pytest or Maven.

Download the skill