Guide · Agent skill
How to use the Safe Refactor agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Safe Refactor is an agent skill that tells an AI coding agent to restructure existing code while keeping its behavior the same. It is for developers and teams who want to extract functions, consolidate duplicates, move code between modules or clean up a codebase that already has tests. This guide shows you what the skill changes about the agent's behavior, how to install it, how to ask for it in natural language, and where it fits and does not fit.
Safe RefactorJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the safe-refactor ZIP from this page and unzip it to get agents/openai.yaml and SKILL.md.
- 2Place the skill folder. Put the unzipped folder in ~/.claude/skills/ for personal use or in .claude/skills/ inside your project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm your tests exist. Make sure the code you plan to restructure has tests or another way to verify behavior, since the skill depends on it.
- 5Describe the restructure. Ask for the change in plain language, naming what should move or be extracted and what must stay the same.
- 6Review the result. Check the diff and the rerun results yourself before merging.
What the Safe Refactor skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when the task matches the skill's description. When the safe-refactor skill is active, the agent treats restructuring work as a behavior-preserving task rather than a general edit.
In practice the skill asks the agent to define the behavior-preservation boundary and set up verification before making structural edits. It keeps feature changes out of the refactor, moves one ownership boundary at a time, and keeps intermediate states buildable and testable. After the change, it reruns the same proof and stops once behavior matches and the requested structure is in place.
- Preserve public interfaces, failure behavior, ordering and compatibility unless you explicitly scope them for change.
- Avoid adding dependencies or configuration unless correctness requires it.
- Stop when behavior matches and the requested structure is achieved, rather than continuing to tidy up.
Install the Safe Refactor skill
Download the safe-refactor ZIP from this page and unzip it. The skill contains two files: agents/openai.yaml and SKILL.md. Then install it using one of these options.
For a personal install across all your projects, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/ (available to every project on your machine).
- Project: .claude/skills/ inside your repository (shared with anyone who works in that repo).
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP.
Trigger the skill with natural requests
You do not need a special command. Describe the restructuring you want in plain language, and say what must not change. The skill's description covers extraction, consolidation, ownership moves and cleanup where verification must bracket structural edits, so requests that name those kinds of work are the most likely to activate it.
State the boundary in your request when you can. For example, say which module owns the code after the move, or which public functions must keep their signatures.
- "Extract the validation logic from checkout.js into its own function without changing behavior."
- "Consolidate these three duplicate date parsers into one, keeping the existing error messages."
- "Move the billing code from the orders module into a billing module, one piece at a time, and keep the tests green."
- "Clean up this file's helper functions. Don't add features or change the public API."
What to expect when the skill runs
The agent first works out what must stay the same and how to check it, typically by identifying the existing tests or other checks in the project. It then makes structural changes in small steps, so the code still builds and tests still run between steps.
When the structural work is done, the agent reruns the same checks it set up earlier. If behavior matches and the structure you asked for is in place, it stops. Review the diff yourself, since the skill does not replace your own judgment about the result.
- Feature work is kept separate. If you also ask for new behavior, expect the agent to treat it as outside the refactor.
- Checks are rerun after the change, using the same proof as before.
What people use it for
- Extracting a long function into smaller named functions while the existing tests keep passing.
- Consolidating duplicate helper code spread across several files into one shared module.
- Moving code from one module to another in stages so each intermediate state still builds and tests.
- Cleaning up a file's structure without adding features or changing its public interface.
Frequently asked questions
Is the Safe Refactor skill free?
The source for this skill is licensed under Apache-2.0, which is stated on this page. Check the license file in the repository for the full terms before you use or redistribute it.
What do I need to use the safe-refactor skill?
The skill's listed requirements are none. It does not run scripts and does not use the network. Its core approach does depend on your code having tests or another way to verify behavior.
Where do I put the skill folder?
Put it in ~/.claude/skills/ for personal use across projects, or in .claude/skills/ inside a specific project. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.
Does the skill work on a project with no tests?
Not well. The skill is built around verification existing, and without tests or another way to check behavior, the agent may be unable to prove the refactor is safe.
Can I use it to add new features while refactoring?
No. The skill keeps feature changes outside the refactor, and it is not meant for greenfield code or new features. Make feature changes in a separate step.
Does the skill change behavior if I ask it to?
It is designed to preserve behavior. If you want behavior to change, this skill is the wrong tool, so use a normal coding request instead.
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
Safe Refactor is a good fit for developers and teams who want to reorganize code that already has tests and avoid regressions, and who want the agent to keep feature work out of the change. It is a poor fit for projects with no tests or other way to verify behavior, for new code, and for any change where behavior is meant to be different.
Download the skill