refactor · sethgammon — Claude Code skill: what it does, how to install
Multi-file refactoring with automated Git rollback, typechecking, and test baseline verification across edits.
MIT ★ 937 updated 2026-10-29
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat refactor does
This skill executes multi-file structural code modifications through a phased protocol. It starts by establishing a baseline using npm run typecheck and your test suite. If existing type errors are present, execution halts immediately. The agent then maps out every import, re-export, and call site before writing any edits.
Changes apply in a strict sequence: new files are created first, references are redirected, the source file updates, and deprecated files are deleted last. After applying edits, it re-runs tests against the baseline. If regressions occur, the skill permits two fix attempts before running git checkout to restore your working tree.
What it helps with
- rename a symbol or module across all project files
- extract a component or function into a separate file
- split a large file into smaller logical modules
- inline a function back into its call sites
Example prompts for the agent
- /refactor extract UserService from src/services/api.ts
- /refactor rename OldButton to PrimaryButton
- /refactor --dry-run split src/utils/helpers.ts
How to install refactor
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill refactor -a claude-code3Manually: put the files in place
~/.claude/skills/refactor/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/refactor/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill refactor -a codex2Manually: put the files in place
.agents/skills/refactor/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill refactor -a cursor2Manually: put the files in place
.cursor/skills/refactor/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/refactor2Manually: put the files in place
.github/skills/refactor/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill refactor -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/refactorManually: put the files in place
.devin/skills/refactor/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about refactor
How to install refactor in Claude Code?
Run /plugin marketplace add SethGammon/Citadel followed by /plugin install citadel@citadel-local. You can also run npx skills add SethGammon/Citadel --skill refactor -a claude-code.
What does the refactor skill do?
It restructures code across multiple files, keeps imports in sync, and verifies that no new typecheck or test errors appear.
What happens if tests fail after refactoring?
The skill makes two attempts to resolve the detected errors. If verification still fails, it discards changes using git checkout and removes new files.
Source text
SKILL.md · MIT
---
name: refactor
license: MIT
description: >-
Safe multi-file refactoring with automatic rollback. Establishes a type/test
baseline, plans all changes, executes file-by-file, and verifies zero
regressions. Reverts if verification fails after two fix attempts.
Handles renames, extracts, moves, splits, merges, and inlines.
user-invocable: true
auto-trigger: false
trigger_keywords:
- refactor
- rename
- extract
- inline
- move file
- split file
- merge files
last-updated: 2026-03-20
---
# /refactor — Safe Multi-File Refactoring
## Orientation
Use `/refactor` when you need to:
- Rename a symbol, file, or module across the codebase
- Extract a function, component, hook, class, or module from existing code
- Inline a function or module back into its callers
- Move a file or set of files to a new location
- Split a large file into smaller pieces
- Merge related files into one
- Change a function signature and update all call sites
**Don't use when:** debugging a specific bug (use /systematic-debugging); adding new features (use /marshal or /scaffold); deleting dead code (use /marshal for a targeted cleanup).
**Boundary with /organize:** /refactor changes code structure within files (extract, inline, split, merge, rename) and moves files as part of those operations. Repository-wide file/directory placement, naming sweeps, and where-does-this-belong decisions are /organize.
**Behavior does not change.** Tests pass before and after, no new type errors — the refactoring is correct.
## Commands
| Command | Behavior |
|---|---|
| `/refactor rename [old] to [new]` | Rename symbol, file, or module |
| `/refactor extract [target] from [source]` | Extract function/component/module |
| `/refactor inline [target]` | Inline a function/module into callers |
| `/refactor move [source] to [dest]` | Move file(s) with import updates |
| `/refactor split [file]` | Split a file into logical pieces |
| `/refactor merge [files...]` | Merge related files into one |
| `/refactor [freeform description]` | Auto-detect refactoring type from description |
| `/refactor --dry-run [any above]` | Plan only, show what would change |
## Protocol
### Phase 1: BASELINE
Run typecheck (via `node scripts/run-with-timeout.js 300 npm run typecheck`) and tests. Record error/failure counts — pre-existing issues are not your responsibility, but you must not add to them. Warn if there are uncommitted changes in files you plan to modify.
```
Baseline established:
Typecheck: {pass | N errors (pre-existing)}
Tests: {pass | N failures (pre-existing) | no test suite found}
Git: {clean | M files with uncommitted changes}
```
### Phase 2: PLAN
Analyze the refactoring target and produce a concrete plan.
1. **Identify scope**: Search the codebase for every reference to the target.
Use grep/search for:
- Import statements referencing the target
- Usage sites (function calls, type references, component usage)
- Re-exports from index files
- Test files that reference the target
- Documentation or comments mentioning the target
- Config files (e.g., route definitions, dependency injection)
2. **Classify the refactoring type** and apply type-specific analysis:
**Rename (symbol):** all imports + usage sites + string references + dynamic access patterns (`obj[key]`)
**Rename (file/module):** all import paths + path aliases + dynamic imports + index re-exports
**Extract (function/component/module):** code to extract, enclosing-scope dependencies, return values back to caller, destination file, interface design
**Move (file):** every import of old path → compute new relative paths, check alias boundary changes, barrel updates
**Split (file):** logical groupings, internal cross-references, which group keeps the original path, new files per group, index if needed
**Merge (files):** duplicates/conflicts, import consolidation, merged file organization
3. **Produce the plan** — list every file that will change and what changes:
```
Refactoring Plan: {type} — {description}
Files to modify:
1. {file}: {what changes and why}
2. {file}: {what changes and why}
...
Files to create:
- {file}: {extracted from where, contains what}
Files to delete:
- {file}: {contents moved to where}
Risk assessment:
- {any concerns: dynamic references, string-based lookups, config files}
```
4. If `--dry-run` was specified, output the plan and stop.
### Phase 3: EXECUTE
Apply changes in this order to minimize intermediate breakage:
1. Create new files first (exports only, not yet imported)
2. Update importers to point to new locations/names
3. Update the source file (remove extracted code, rename, etc.)
4. Delete old files last (only after all importers are updated)
5. Update index/barrel files
Read each file before editing. Make the minimal change needed — do not reformat unrelated code.
### Phase 4: VERIFY
Run typecheck and tests from Phase 1. Compare against baseline — any NEW errors or failures? Search for import paths referencing old/deleted files.
```
Verification: PASS
Typecheck: {pass | same N pre-existing errors}
Tests: {pass | same N pre-existing failures}
No new broken imports detected.
```
### Phase 5: FIX (if verification fails)
Two attempts: read errors, identify root cause (missed import update, missing re-export, type mismatch), fix, re-run verification. After 2 failed attempts: REVERT.
### Phase 6: REVERT (if fixes fail)
1. Use `git checkout -- [files]` to restore every modified file
2. Remove any newly created files
3. Verify the revert: typecheck should match baseline exactly
4. Report what went wrong
```
REVERTED — Refactoring could not be completed cleanly.
Root cause: {why the refactoring failed}
Errors encountered:
- {error 1}
- {error 2}
Suggestion: {what the user might do differently}
```
## Fringe Cases
- **No test baseline**: no test suite found in Phase 1 — output: "No tests found. Refactor proceeds without a safety net — abort or continue? Recommend running /test-gen first." Wait for user confirmation before continuing.
- **Baseline typecheck fails**: typecheck errors exist before any refactor changes — output: "Baseline typecheck failed. Fix existing type errors before refactoring to establish a clean baseline." Do not proceed.
- **Build fails after refactor commit**: Phase 4 build regression detected — revert the commit with `git revert HEAD --no-edit`, then report which verification step introduced the regression and what the failing error is.
- **Circular dependency detected**: import cycle surfaces during scope analysis — treat as a blocker; output: "Circular dependency detected in [file]. Resolve the cycle before proceeding." Do not modify that file without explicit user decision.
- **Target file exceeds 500 lines**: output: "Warning: [file] is [N] lines. Refactoring may split this file into multiple pieces. Confirm scope before proceeding." Show the proposed split in the plan and wait for user approval.
## Quality Gates
- **Zero new type errors** — zero NEW ones, not just fewer.
- **Zero new test failures** — baseline failures accepted, new failures are not.
- **All imports resolve** — no dangling references to old paths or removed exports.
- **Behavior unchanged** — adding logic or changing return values is scope creep; stop and do it separately.
- **Minimal diff** — no reformatting, unrelated cleanups, or whitespace changes in untouched files.
- **Plan matches execution** — every planned file modified, no unplanned files touched.
## Exit Protocol
Report the result:
```
=== Refactor Report ===
Type: {rename | extract | inline | move | split | merge}
Target: {what was refactored}
Changes:
Modified: {N} files
Created: {N} files
Deleted: {N} files
Verification:
Typecheck: {pass | same baseline errors}
Tests: {pass | same baseline failures | no test suite}
Key decisions:
- {any non-obvious choices made during execution}
```
```
---HANDOFF---
- Refactored {target}: {what changed}
- {N} files modified, {N} created, {N} deleted
- Typecheck and tests pass (no regressions)
- {any follow-up suggestions}
- Reversibility: green -- single atomic commit, revert with git revert HEAD
---
```
© SethGammon · MIT · SethGammon/Citadel
Similar skills
All skills for Code review and refactoring →refactor by other authors comes first.