Guide · Agent skill
How to use the Code Refactoring Guide agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The refactor skill is a set of instructions and reference files that teaches an AI coding agent to refactor code in a structured way, based on Martin Fowler's methodology in Refactoring (2nd Edition). It is useful for developers with legacy code, or teams planning a cleanup of technical debt before adding features. After this guide you will know what the skill does, how to install it, how to phrase a request so it triggers, and what it needs to run.
Code Refactoring Guideluongnv89/claude-howto · MIT Download the skill Quick start
- 1Download the skill. Download the ZIP for the refactor skill from the directory page.
- 2Unzip into a skills folder. Unzip the folder into ~/.claude/skills/ for personal use, or into .claude/skills/ in your project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Check your tests. Make sure your project's test command, such as npm test, pytest or mvn test, runs successfully before refactoring.
- 5Ask for a refactoring in plain language. Describe the file or module and the problem, for example that the code is hard to maintain or has duplication.
- 6Approve each phase. Review the findings, smell report and plan, and approve each phase before the agent makes changes.
What does the refactor skill make the agent do?
Instead of rewriting code in one pass, the skill makes the agent work through six phases: research and analysis, test coverage assessment, code smell identification, refactoring plan creation, incremental implementation, and review and iteration. The core rules are that external behavior must not change, each change should be small and testable, tests act as the safety net, and the user approves at each phase.
When the agent finds smells, it uses a catalog of named refactorings such as Extract Method and Move Method, and applies them one change at a time. Each change is followed by running tests and committing if they pass.
- Checks for existing tests before changing anything
- Identifies code smells such as long methods, duplicated code and large classes
- Chooses named refactorings from Fowler's catalog to address each smell
- Applies small changes one at a time, verifying with tests after each
How do you install the refactor skill?
Download the ZIP for the skill from the directory page and unzip it. For a personal install, place the unzipped folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.
You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload it there.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
How do you trigger the skill with a natural request?
You do not need a special command. The skill's description tells the agent when to use it, so ask in plain language about refactoring, improving structure, reducing technical debt, cleaning up legacy code, eliminating code smells, or improving maintainability.
Mention the scope where you can, such as a file or module, and any parts that must not change. The skill's first phase asks these questions anyway, so a clear request saves a round trip.
- "Refactor the payment module in src/billing to reduce duplication."
- "This legacy order service is hard to maintain. Can you clean up its structure step by step?"
- "Find the code smells in utils/parser.py and propose a refactoring plan."
- "Reduce the technical debt in the checkout code before we add the new feature."
What do you need before you start?
The bundled helper scripts need Python 3. The scripts are scripts/detect-smells.py and scripts/analyze-complexity.py. The skill also runs your project's own test tooling for its test-check steps, such as npm, pytest or mvn, so those must already work in your project.
The skill makes no network requests. It does run scripts, so review them before use.
- Python 3 for the bundled scripts
- Your project's test tooling (npm, pytest or mvn, depending on the language)
- Tests in the project. The skill warns that refactoring without tests is risky and proceeds only after you explicitly acknowledge that risk
python scripts/detect-smells.py <file>What are the safety notes for scripts and network use?
The skill runs scripts, so it can execute code on your machine. Check the scripts in the skill folder before running them, and run the agent in a project you trust. The skill does not use the network.
The skill's own rules protect your code during the work. It asks for approval at each phase and will not proceed without tests unless you acknowledge the risk.
- Runs scripts: yes
- Uses network: no
- Review scripts/detect-smells.py and scripts/analyze-complexity.py before first use
What tips help the refactoring go well?
Start with tests. If tests are missing, the skill offers to write them first, which is its recommended option. Keep each request to a limited scope so approvals stay meaningful.
Work through the phases in order. The skill introduces changes in stages: quick wins such as renaming and removing dead code first, then structural changes like extracting methods, and architectural changes like replacing conditionals with polymorphism last. The plan template in templates/refactoring-plan.md helps you record goals, risks and rollback steps.
- Use the refactoring plan template to track goals, constraints, risks and rollback
- Ask for quick wins before structural or architectural changes
- If any single step takes more than 10 minutes, the catalog advises breaking it down further
- Commit after each green step so you can roll back easily
What people use it for
- Cleaning up a legacy module with long methods before changing it
- Removing duplicated logic across several files in small, tested steps
- Planning a technical debt reduction sprint with a phased, reviewable plan
- Finding smells in a Python, JavaScript or TypeScript file with the bundled scripts
Frequently asked questions
How do I install the refactor agent skill?
Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What do I need to run the refactor skill?
Python 3 is needed to run the bundled scripts, scripts/detect-smells.py and scripts/analyze-complexity.py. Your project also needs working test tooling, such as npm, pytest or mvn, for the test-check steps.
Is the refactor skill free?
This page does not state a price or licence terms beyond the item's licence, which is MIT. Check the licence file in the source before redistributing or modifying it.
Can the skill refactor code without tests?
It warns that refactoring without tests is risky. It can proceed without tests only after you explicitly acknowledge that risk, and it recommends writing tests first.
Which languages does the refactor skill support?
The bundled smell scanner covers Python, JavaScript and TypeScript files. The skill is not suited to non-code documents or languages outside those covered, where the scripts will not help.
Does the refactor skill need internet access?
No. The skill uses no network. It does run scripts, so review them before use.
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 have legacy code with tests, or you are willing to write them, and want changes made in small, approved, verifiable steps. Pick something else for urgent bug fixes or feature work, where the phased process adds overhead, or for projects with no tests and no plan to write them.
Download the skill