safe-refactor Skill for Claude: Restructure Code Without Changing Behavior

safe-refactor makes your coding assistant restructure code in small steps while proving behavior has not changed.

Installs: 113.4K; on skills.sh
Stars: 116.7K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

safe-refactor tells the assistant to define what must not change, and to set up a way to check it, before any structural edit. Then it moves one ownership boundary at a time. It keeps public interfaces, failure behavior and ordering as they were, and keeps every in-between state buildable and testable.

It loads when you ask for extraction, consolidation, ownership moves or cleanup. After the change it runs the same proof again and stops once behavior matches and the requested structure is in place. It bundles no scripts, and its SKILL.md names no keys or tools.

Good for

Developers extracting, merging or moving code
Reviewers who want each refactor to come with proof
Teams that keep feature work out of cleanup PRs

Install safe-refactor

Claude Code

Copy this prompt.

Install the safe-refactor skill in Claude Code. Run this command:

npx skills add https://github.com/juliusbrussee/caveman --skill safe-refactor

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Restructure code while preserving behavior. Use for extraction, consolidation, ownership moves, or cleanup where verification must bracket structural edits.

Key facts

Author: Julius Brussee (repo owner juliusbrussee)
Repository: juliusbrussee/caveman, folder skills/safe-refactor
Installs on skills.sh: 113,353 (as of 2026-11-02)
Repo stars: 116,702 (whole repository, as of 2026-11-02)
License: Apache-2.0
Last repo commit: 2026-11-01
Files in the skill folder: 2 files: SKILL.md and agents/openai.yaml
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Define what behavior must be preserved before editing
Names the behavior-preservation boundary and sets up verification before any structural edit.
Read · Set the boundary
No feature changes inside a refactor
Feature changes stay outside the refactor.
Keep features out
Move a single ownership boundary per step
Moves one ownership boundary at a time.
Write · One boundary at a time
Keep public interfaces, failure behavior, ordering
Preserves public interfaces, failure behavior, ordering and compatibility unless the task says otherwise.
Preserve interfaces
Every intermediate state builds and tests
Keeps intermediate states buildable and testable.
Runs code · Stay buildable
No new dependencies or config without a correctness need
Avoids dependency or configuration growth without a correctness need.
No config growth
Run the same proof after, then stop
Runs the same proof after the change and stops when behavior matches and the requested structure is achieved.
Runs code · Prove and stop

From the official docs

Permissions

Low risk

The skill has the assistant edit your code and run your checks, so the risk is a bad edit, not a data leak.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It edits your code and runs your checks
The skill tells the assistant to change code structure and re-run verification. Work on a branch and review the diff before you merge.

Questions

What does the safe-refactor skill do?

It makes the assistant treat a refactor as a behavior-preserving change. It sets up verification first, moves one boundary at a time, and re-runs the same proof at the end.

How do I install safe-refactor in Claude Code, the Claude app or Codex?

Use the install box at the top of the page and pick your client. The SKILL.md bundles no scripts and lists no other requirements. The folder also includes an agents/openai.yaml file. The README says your agent picks these work patterns up when a task fits, so you do not need to call it by name.

Does safe-refactor need an API key or an account?

No. The SKILL.md asks for no key, login or tool. It is plain instructions for the assistant, and it bundles no scripts.

Is safe-refactor safe to use?

It is a short instruction file and bundles no scripts. What it changes is how the assistant behaves when it edits your project, so review the diff and keep your usual git and test setup. The permissions section below lists what to watch.

How is safe-refactor different from surgical-patch?

safe-refactor is for restructuring: extraction, consolidation, ownership moves and cleanup. surgical-patch is for bug fixes and small behavior changes at the narrowest responsible layer. Use safe-refactor when behavior must stay identical and surgical-patch when behavior should change in one place.

Information

updated Nov 2, 2026

Repository: juliusbrussee/caveman
Folder: skills/safe-refactor

juliusbrussee/caveman skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

safe-refactor SKILL.md · github.com
caveman README · github.com
safe-refactor openai.yaml · github.com
surgical-patch SKILL.md · github.com