Guide · Agent skill
How to use the Code Refactoring Assistant agent skill (refactor)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The refactor skill is an agent skill for Claude that guides the agent through a structured code refactoring process based on Martin Fowler's book Refactoring (2nd edition). Instead of rewriting code freely, the agent investigates the code, checks tests, finds code smells, writes a plan and makes small changes after your approval. This guide explains what agent skills are, how to install this one, how to trigger it, and what to watch for.
Code Refactoring Assistantluongnv89/claude-howto · MIT Download the skill Quick start
- 1Download the ZIP. Get the refactor skill ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Check tests. Confirm the project has tests and that the test command runs, such as npm test, pytest -v or mvn test.
- 5Ask for a refactoring with a natural request. Describe the code and the goal, and name any parts that must stay the same.
- 6Review the plan and approve each phase. Read the written plan with its named refactorings and risks, then approve phases one at a time.
What is an agent skill and what does refactor make the agent do?
An agent skill is a folder of instructions and optional files that an AI agent loads when a request matches the skill's description. The refactor skill's main file, SKILL.md, describes a six-phase workflow: investigation and analysis, test coverage assessment, code smell detection, planning, incremental implementation, and review and iteration.
The skill is built on five principles: preserve behaviour, make small steps, rely on tests as a safety net, treat refactoring as ongoing work, and get user approval at every phase.
- Asks scoping questions first: which files, what goals, what must not change, deadline pressure, and the state of the tests.
- Checks for existing tests and runs them if the project tooling allows it.
- Identifies smells such as long methods, duplicated code, large classes, feature envy and dead code.
- Proposes a written plan that names specific Fowler refactorings such as Extract Method or Replace Conditional with Polymorphism.
- Applies changes in phases: quick wins first, then structural changes, then architectural changes, asking to continue at each step.
Install the refactor skill from a ZIP file
Download the ZIP for the refactor skill from this page, then unzip it. You can install it for yourself across all projects, or only for one project.
For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. The skill folder should contain SKILL.md along with the references, scripts and templates folders.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
Check the requirements before you start
The skill itself needs no special setup for planning and review. Two things matter for the rest of the workflow.
Python 3 is needed to run the bundled analysis scripts. Test tooling such as npm, pytest or mvn is needed if you want the agent to run your tests. The skill makes no network requests.
- Python 3 for scripts/detect-smells.py and scripts/analyze-complexity.py
- npm, pytest or mvn for running your project's tests
- The project's own test suite, ideally in place before refactoring
How to trigger the skill with natural requests
You do not need a special command. Describe what you want in plain language that matches the skill's purpose: refactor, improve structure, reduce technical debt, clean up legacy code, remove code smells, or improve maintainability.
Mention the files or module when you can, and say if there are parts that must not change. The agent will ask the rest.
- Refactor the payment module in src/payments to make it easier to maintain.
- This service has long methods and duplicated logic. Find the code smells and propose a plan.
- Clean up the legacy order-processing code, but do not change the public API.
- Reduce the technical debt in utils/ and show me the plan before editing anything.
Run the smell and complexity scripts
The bundled scripts analyse Python, JavaScript and TypeScript files. detect-smells.py scans for smells, and analyze-complexity.py measures complexity so you can compare before and after a change. The skill's documented smell-detection command takes a file path.
Use the scripts on a single file path. The source does not list other flags, so do not assume any.
python scripts/detect-smells.py <file>Know the safety notes
The skill runs scripts, so read them before you trust them, as with any skill you install. The skill does not use the network, according to its assessment. Run the test commands the agent suggests yourself if you prefer to see the output directly.
The skill recommends writing tests before refactoring. If there are no tests, it asks you to choose: write tests first (recommended), add tests as you go, or continue without tests, which is risky and needs your confirmation.
- Scripts are included in the skill and can run on your machine.
- Keep your work in version control so every step can be reverted.
- Expect a plan with rollback steps for each refactoring.
What people use it for
- Cleaning up a legacy module with long methods before adding a feature.
- Finding duplicated logic across a Python or JavaScript codebase and extracting it into shared methods.
- Reducing a large class by extracting responsibilities into smaller classes, one step at a time.
- Measuring complexity before and after a refactoring to show the change helped.
Frequently asked questions
How do I install the refactor agent skill?
Download the ZIP from this 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 required to run the bundled analysis scripts. Project test tooling such as npm, pytest or mvn is needed if you want the agent to run tests.
Is the refactor skill free?
The skill is released under the MIT licence, according to this listing. Check the licence file in the source repository for the full terms.
Can I use the refactor skill on a project with no tests?
The skill recommends writing tests first. It can continue without them, but only after you confirm, because behaviour changes may go unnoticed.
Which languages does the refactor skill support?
The bundled scripts analyse only Python, JavaScript and TypeScript. The agent can still apply the general refactoring method to other languages.
Does the refactor skill send my code over the network?
The listing states that the skill does not use the network. It does run bundled 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 maintain legacy or messy code and want a controlled, step-by-step process with a written plan and approval at each phase, especially if you have tests. Pick something else for quick one-line fixes, new feature work, or projects with no tests where you cannot accept the risk of unnoticed behaviour changes.
Download the skill