Skip to content
Get packs

Safe Refactor

Restructure code without changing behavior, verifying before and after each structural edit

Source Download skill
Repository
JuliusBrussee/caveman
Stars
116,835
Licence
Apache-2.0
Files
2 files

What it does

When installed, the agent treats code restructuring (extracting functions, consolidating duplicates, moving code between modules, cleaning up) as a careful, behavior-preserving task. It first defines what must stay the same, sets up a way to verify it, keeps feature changes out of the refactor, and moves one ownership boundary at a time so intermediate states still build and test. It then reruns the same checks after the change and stops once behavior matches and the requested structure is in place.

Great for

  • Developers who want to reorganize existing code without introducing regressions
  • Teams doing incremental cleanup or module splitting in a codebase that has tests
  • Anyone who wants an AI agent to avoid mixing feature work into a refactor

Skip it if

  • Projects with no tests or other way to verify behavior, since the skill's core approach depends on verification existing; the agent may be unable to prove the refactor is safe
  • Greenfield code or new features, which the skill explicitly scopes out
  • Changes where behavior is meant to change, because the skill is designed to preserve it

Try asking

  • “Extract the validation logic in this file into its own module without changing behavior”
  • “Consolidate these three duplicated API client functions into one, keeping the public interface the same”
  • “Move the billing code out of the user service one piece at a time, keeping tests green at each step”
  • “Clean up this legacy module and tell me how you verified nothing changed”
Step-by-step guide: how to use Safe RefactorInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 2 original files, the Apache-2.0 licence and an attribution note.

    safe-refactor.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip safe-refactor.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip safe-refactor.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point the agent at your existing test suite or a specific verification command so it has a concrete proof to run before and after the change.
  • State the structural goal clearly (for example, which boundary to move) so the agent knows when to stop.
  • Explicitly list any interfaces or behaviors that are allowed to change, since the skill otherwise preserves them.

What's inside

  • agents/openai.yaml
  • SKILL.md

Redistributed unmodified from JuliusBrussee/caveman under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.