Skip to content
Get packs

Guide · Agent skill

How to use the Safe Code Refactoring agent skill (refactor)

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 teaches an AI agent to restructure existing code carefully: check the tests first, find code smells, propose a phased plan, then change the code in small steps with your approval at each stage. It is aimed at developers working on legacy or messy codebases who want cleanup without a big-bang rewrite. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what it needs to run safely.

Safe Code Refactoringluongnv89/claude-howto · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP for this skill from this page and unzip it to get the refactor folder containing SKILL.md.
  2. 2Place it in the right folder. Move the folder into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder for team use. In the Claude apps, upload it under Settings → Capabilities → Skills instead.
  3. 3Confirm your test suite runs. Make sure your project's tests pass using the runner you already use, such as npm test, pytest or mvn test.
  4. 4Describe the refactoring goal. Ask in plain language, naming the file or module and your goal, for example: clean up src/orders.js without changing behaviour.
  5. 5Answer the scope and test questions. Tell the agent what must not change, your time pressure and whether tests exist. Choose how to handle missing tests.
  6. 6Approve the plan and phases. Review the smell report and phased plan, then approve Phase A before any code changes. Approve each later batch separately.
  7. 7Review the commits and results. Check each small commit and the final before and after summary, tests and remaining technical debt.

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file of instructions that an AI agent loads when a request matches the skill's description. This skill is based on Martin Fowler's book Refactoring (second edition) and is built around one principle: changing the internal structure of code without changing its external behaviour.

When you ask for cleanup, restructuring or less technical debt, the agent follows six phases: research and analysis, test coverage assessment, code smell identification, refactoring plan creation, incremental implementation, and review and iteration. It asks you to confirm scope and goals up front and requests approval before it starts changing code and before each phase.

  • Checks whether tests exist and pass before touching code, and stops if they fail.
  • Looks for common code smells such as Long Method, Duplicated Code and Large Class.
  • Writes a plan with risks and rollback steps for each refactoring.
  • Changes code one small step at a time, running tests after each change and suggesting a commit for each green step.

How do you install the refactor skill?

Download the ZIP for this skill from this page and unzip it. You have two places to put the resulting folder, depending on how you want to use it. For a personal setup available across your projects, place it in ~/.claude/skills/. To share it with one project and your team, place it in that project's .claude/skills/ folder.

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

  • Personal: unzip into ~/.claude/skills/ so the skill is available in all your projects.
  • Project: unzip into the project's .claude/skills/ folder so it applies to that repository.
  • Claude apps: upload the skill under Settings → Capabilities → Skills.

How do you trigger the skill with natural requests?

You do not need a special command. The skill is meant to load when your request matches its description, which covers refactoring code, improving code structure, reducing technical debt, cleaning up legacy code, removing code smells and improving maintainability. Describe the goal in plain language and name the file or module if you can.

Expect the agent to ask questions before it edits anything. It will want to know the scope, your goal (readability, performance or maintainability), any areas that must not change, time pressure, and whether tests exist and pass.

  • Clean up the order processing code in src/orders.js without changing behaviour.
  • Our billing module is hard to follow. Find the code smells and propose a phased refactoring plan.
  • Reduce the technical debt in the user service, starting with low-risk changes.
  • Review the code quality of payments.py before and after we refactor it.

What happens during a refactoring session?

The agent first reads the target code and reports a summary, the problem areas and initial recommendations, then waits for your go-ahead. It then checks the test suite by running the commands for your stack. If tests are missing or incomplete, it offers three options: write tests first (recommended), add tests during the refactor, or proceed without tests, which the skill calls risky and requires your explicit consent for.

Once you approve a plan, changes are grouped into phases. Phase A covers low-risk quick wins such as renaming variables, extracting obvious duplicates and deleting dead code. Phase B covers structural changes such as extracting methods and introducing parameter objects. Phase C covers architecture changes such as replacing conditionals with polymorphism. The agent asks for approval before each batch and stops if tests fail.

  • Test commands the skill uses include npm test, pytest -v and mvn test, plus coverage variants.
  • Commit messages follow patterns such as refactor: Extract calculateTotal() from processOrder().
  • After the work, the agent runs a checklist covering passing tests, new warnings, compilation and unchanged behaviour.
Change → Test → Green? → Commit → Next step

What do you need before you start?

The skill works best on code that already has an automated test suite and a working test runner, such as npm test, pytest or mvn test. The skill itself says that refactoring without tests is risky and needs explicit consent. Without tests, you lose the safety net that lets the agent verify behaviour after each step.

Two helper scripts are referenced by the skill, scripts/detect-smells.py and scripts/analyze-complexity.py. They are optional and are not included in the files provided with this skill, so the skill will work without them, but the automated analysis and complexity comparison steps will not run unless you supply them.

  • An existing test suite and a runner for your language.
  • Optional: scripts/detect-smells.py and scripts/analyze-complexity.py, which are not included in the provided files.
  • Access to the codebase so the agent can read and edit the target files.

Is it safe to run the refactor skill?

This skill runs scripts and does not use the network, according to its listing. The scripts it references are optional helpers for smell detection and complexity analysis. Because the agent edits your code, review each proposed change, check the commits it makes, and keep your work in version control so you can revert easily.

The skill is designed to stop rather than guess. It says the agent should pause and ask when business logic is uncertain, when a change could affect external APIs, when test coverage is inadequate, or when risk rises or unexpected complexity appears. It also forbids mixing refactoring with feature work and refactoring during a production incident.

  • Review the plan and each phase before approving it.
  • Keep the codebase under version control so each small commit can be reverted.
  • Do not use it on code you do not understand or on undocumented business logic without answering the agent's questions first.
  • Do not let it refactor during an active production incident, per the skill's rules.

Tips for getting good results

Start with one module or one function rather than the whole repository. The skill's own guidance is to avoid changing everything at once and to split any step that takes more than about ten minutes into smaller ones. Ask for the plan first and approve only Phase A at the beginning.

Use the refactoring plan template bundled with the skill to keep track of goals, constraints, risk level, and rollback steps. If you want a checklist without any code changes, say so explicitly and ask only for the smell report and plan.

  • Pick a single file or function as the scope.
  • Ask for the plan and approve phases one at a time.
  • Keep refactoring and new features in separate commits or sessions.
  • Ask for the before and after metrics comparison if you have the optional complexity script.

What people use it for

  • Untangling a 150-line order processing function by extracting validation, totals and notifications into separate functions, testing after each step.
  • Finding and removing dead code and duplicated logic in a legacy service before adding new features.
  • Producing a documented refactoring plan with risks and rollback steps for a team to review before any code changes.
  • Running a structured code quality review of a module before and after a refactor.

Frequently asked questions

Is the refactor skill free to use?

The source lists this skill under the MIT licence, which is the licence it is published under. The source does not state any price, so check the licence text for the terms that apply.

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. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to use the refactor skill?

You need an existing project test suite and a test runner, for example npm test, pytest or mvn test. Two helper scripts, scripts/detect-smells.py and scripts/analyze-complexity.py, are referenced but not included in the provided files.

Does the refactor skill run scripts or use the internet?

According to its listing, it runs scripts and does not use the network. Review what the scripts do before running them on your machine.

Can the agent refactor code that has no tests?

The skill recommends writing tests first. It only proceeds without tests if you explicitly accept the risk, and it warns that this is risky.

How is this different from just asking an agent to clean up my code?

This skill forces a staged process: it checks tests, identifies named code smells, proposes a phased plan with rollback steps, and waits for your approval at each phase instead of rewriting everything at once.

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 this skill if you maintain a legacy or messy codebase that has tests and you want cleanup done in small, reviewable, approved steps with documented risks. Pick something else if your project has no tests, you need a quick one-line fix, or you are building new features, since the multi-phase process adds overhead and the skill itself warns against unguarded changes.

Download the skill