Guide · Agent skill
How to use the refactor agent skill: safe, staged code cleanup
Updated · 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 an AI agent how to restructure existing code carefully. It is based on Martin Fowler's refactoring method and asks the agent to check tests, list code smells, write a plan with rollback steps, and make small changes one at a time. After this guide you will know how to install the skill, how to ask for a refactor in plain language, and what to check before you let it touch your code.
Code Refactoring Assistantluongnv89/claude-howto · MIT Download the skill Quick start
- 1Download the skill ZIP. Download the ZIP for the refactor skill from this page.
- 2Unzip into a skills folder. Place the refactor folder with SKILL.md in ~/.claude/skills/ for personal use, or in .claude/skills/ inside your project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check your tests. Make sure your project has a working test runner such as npm test, pytest, or mvn test, because the skill relies on tests to verify each change.
- 4Ask for a specific refactor. Describe the file or function and the problem, for example long functions or duplicated logic, and mention any parts that must not change.
- 5Approve each stage. Review the findings and plan, then approve one stage at a time. Check the test results and commits the agent reports after each step.
What the refactor skill makes the agent do
An agent skill is a folder with a SKILL.md file that tells the agent how to handle a certain kind of task. When you ask for cleanup, restructuring, or less technical debt, this skill makes the agent follow six stages: research and analysis, test coverage check, code smell identification, refactoring plan, incremental implementation, and review.
The skill's core rules are to keep external behaviour unchanged, move in small testable steps, treat tests as the safety net, and confirm with you at each stage. Common smells it looks for include long functions, duplicated logic, large classes, long parameter lists, and dead code.
- Asks scoping questions first: which files, what goal, which areas must not change, and whether tests exist.
- Writes a plan where each refactoring lists its target, smell, technique, steps, risks, and rollback.
- Runs tests after every change and commits each working step with a clear message.
- Stops and asks you when tests fail, business logic is unclear, or an external API might change.
Install the refactor skill
Download the ZIP for this skill from this page. Unzip it so that the refactor folder, containing SKILL.md, sits inside one of these locations: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a specific project to share it with that project.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/refactor/
- Project install: .claude/skills/refactor/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. The skill is meant to be used when you ask for work like the examples below. Be specific about the files or functions, and say what problem you want solved, such as readability or maintainability. Mention if you have constraints, such as a public API that must not change.
- Refactor the order processing code in src/orders.js. It is hard to follow.
- This function is 150 lines long. Can you reduce its complexity without changing behaviour?
- Find code smells in the billing module and propose a prioritised plan.
- Clean up the old export code in reports/ and remove dead code, but ask me before changing anything public.
- Reduce the technical debt in this Python package and run the tests after each change.
What you need before you start
The skill works best when your project has a test runner the agent can call. The source gives examples for JavaScript and TypeScript, Python, and Java. Coverage tools are optional and make the test-coverage check more useful.
The source also refers to two helper scripts, scripts/detect-smells.py and scripts/analyze-complexity.py. These scripts are not included in the files listed for this skill, so the skill's automated analysis steps may not run unless you add them yourself. The manual review steps still work without them.
- A project test runner such as npm test, pytest, or mvn test
- Optional coverage: npm run test:coverage or pytest --cov=.
- Optional helper scripts, which are not among the provided files
npm test
pytest -v
mvn test
pytest --cov=.Safety notes on scripts and network access
This skill runs scripts, so review them before use. According to the skill's description, it does not use the network. Check the referenced helper scripts in your own environment before trusting their output or running them on sensitive code.
The skill itself sets safety limits: it says not to refactor code without tests unless you explicitly accept the risk, and to stop and restore the code if a test fails. Keep your work under version control so each step can be reverted.
- Runs scripts: yes. Uses network: no.
- Review scripts/detect-smells.py and scripts/analyze-complexity.py before running them, since they are not included in the provided files.
- Commit before starting so each stage can be rolled back.
Tips for getting good results
Give the agent a narrow scope. The skill is designed for small steps, so a single long function or one module works better than the whole codebase. Read the plan before approving it, and approve one stage at a time.
Do not use this skill for behaviour changes or new features, since the skill is designed for refactoring only. It also advises against refactoring during a production outage.
- Start with stage A, low-risk changes such as renaming, extracting obvious duplication, and removing dead code.
- Ask for the metrics comparison at the end to see changes in line count and complexity.
- Keep refactoring and new features in separate commits.
Example: cleaning up a long function
Suppose you ask the agent to refactor a 150-line processOrder function. The skill first confirms that tests cover it. Then it extracts validation into validateOrder, the total calculation into calculateOrderTotal, and notifications into notifyCustomer, running the tests after each extraction.
At the end, processOrder only calls those three functions and returns the result. Each extraction is a separate commit, so you can review or revert any one of them.
function processOrder(order) {
validateOrder(order);
const total = calculateOrderTotal(order);
notifyCustomer(order, total);
return { order, total };
}What people use it for
- Splitting a 150-line function into smaller named functions with tests run between each extraction.
- Removing duplicated validation or calculation logic spread across a codebase.
- Finding and removing dead code in an older module before adding features.
- Producing a written, prioritised refactoring plan with rollback steps for a team to review.
Frequently asked questions
How do I install the refactor agent skill?
Download the ZIP from this page and unzip it so the refactor folder with SKILL.md is in ~/.claude/skills/ or in a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to run the refactor skill?
You need a project test runner, such as npm test, pytest, or mvn test, because the skill runs tests after each change. Coverage tools are optional. The helper scripts it mentions are not included in the provided files.
Is the refactor skill free?
The source lists the skill under the MIT licence. Pricing details are not stated in the source, so check the repository for any other terms.
Can the refactor skill work on code without tests?
The skill says not to refactor without tests unless you explicitly accept the risk. It recommends writing tests first, or adding them during the refactor, and it will ask you to confirm if you choose to proceed without them.
Does the refactor skill use the internet?
The skill description says it does not use the network. It does run scripts, so review any scripts before running them.
How is this different from asking an agent to just clean up my code?
This skill enforces a staged process: it checks tests, lists named code smells, writes a plan with rollback steps, and makes small committed changes with your approval at each stage. A general request usually does not include those checkpoints.
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 long functions or duplication and want a careful, reviewable cleanup in small committed steps with approval checkpoints. Pick something else if your code has no tests and you are not willing to accept the risk, or if you need an urgent fix during a production incident, since the skill advises against refactoring in those situations.
Download the skill