Code Refactoring Skill

A stable refactoring skill for any AI coding agent. Safe, incremental, behavior-preserving code improvements for any programming language.

Works with Claude Code, Cursor, Aider, Continue, GitHub Copilot, OpenAI Assistants, or any LLM that accepts a system prompt.

Built on Martin Fowler’s refactoring catalog, extended with modern patterns for functional programming, async/await, reactive systems, dependency injection, and architectural patterns (MVVM, MVP, Clean Architecture, Hexagonal, Repository, Use Case).

---

What It Does

• Detects code smells across 6 families (Bloat, OO Abusers, Change Preventers, Dispensables, Couplers, Architectural Violations)
• Applies 70+ refactoring operations from the complete Fowler catalog + modern patterns + architectural patterns
• Handles architectural refactoring — safely migrates toward MVVM, MVP, Clean Architecture, Repository pattern, and more
• Works in any language — TypeScript, Python, Go, Rust, Java, Kotlin, C#, Swift, Ruby, C/C++, SQL, and more
• Tests gate every step — runs your test suite after each change; reverts immediately on failure
• One operation at a time — no bundled changes, every step is independently verifiable
• Safety-first — explicit red lines for public APIs, serialization formats, concurrent code, and architectural layer violations

---

Installation

Interactive installer

npx code-refactoring-skill

Prompts for:

1. Scope — Global (home dir, all projects) or Project (current directory)
2. Agent(s) — pick one, several, or all

Manual install (any agent)

Copy PROMPT.md into your agent’s system prompt, custom instructions, or rules file. That’s the complete self-contained skill — no other files needed.

curl -O https://raw.githubusercontent.com/MuhiminOsim/code-refactoring-skill/main/PROMPT.md

For a generic global install:

mkdir -p ~/.agents/skills/refactor
curl -o ~/.agents/skills/refactor/PROMPT.md \
  https://raw.githubusercontent.com/MuhiminOsim/code-refactoring-skill/main/PROMPT.md

Claude Code (git install)

git clone https://github.com/MuhiminOsim/code-refactoring-skill \
  ~/.claude/skills/refactor

The skill auto-activates — no configuration needed.

Agent-specific setup guides

---

Usage

Trigger the skill by asking Claude Code to refactor, with any of these phrases:

Example session

You: This function is too long, clean it up

Claude: Reading processOrder() at orders.ts:45 (142 lines)...

Detected smells (ranked):
1. [Blocker] Long Method — processOrder() is 142 lines with 4 internal sections
2. [Major] Duplicate Code — discount logic at lines 67–89 also appears in cart.ts:23
3. [Minor] Primitive Obsession — price passed as raw float

Plan:
1. Extract calculateDiscount() from lines 67–89
2. Extract applyTaxes() from lines 91–110
3. Extract formatOrderSummary() from lines 112–130
Confirm? (tests will run after each step)

You: Yes, go

Claude: Step 1: Performing Extract Method — calculateDiscount()

BEFORE: [lines 67–89 inline in processOrder()]
AFTER:  [new calculateDiscount(user, price) function]

Running tests... npm test ✓ (all 47 tests pass)
Step 1 complete.

Step 2: Performing Extract Method — applyTaxes()
...

---

How It Works

The skill follows a strict 5-phase process for every refactoring request:

Phase 1: Intake      → Read all target files, detect language, find test harness
Phase 2: Diagnose    → Detect and rank code smells
Phase 3: Plan        → Decompose into atomic, verifiable steps
Phase 4: Execute     → Apply one change at a time, run tests after each
Phase 5: Wrap-up     → Summarize changes, suggest (not apply) follow-ons

Full detail: references/process.md

---

File Structure

.
├── SKILL.md                      ← Skill entry point (triggers, decision tree)
└── references/
    ├── process.md                ← Universal 5-phase workflow
    ├── smells.md                 ← Code smell catalog (6 families, 30+ smells)
    ├── safety.md                 ← Red lines, yellow lines, rollback + architectural protocol
    ├── catalog-composing.md      ← Extract, Inline, Split, Decompose
    ├── catalog-simplifying.md    ← Conditionals, Guards, Polymorphism
    ├── catalog-organizing.md     ← Move, Organize, Encapsulate
    ├── catalog-api.md            ← Rename, Parameter Objects, Factory
    ├── catalog-inheritance.md    ← Inheritance, Composition over Inheritance
    ├── catalog-modern.md         ← FP, Async, Reactive, DI patterns
    ├── catalog-architecture.md   ← MVVM, MVP, Repository, Use Case, Layer Fixes
    └── language-profiles.md      ← Per-language idioms, test commands, linters

---

Refactoring Operations Covered

Composing Methods

Extract Method/Function, Inline Method/Function, Extract Variable, Inline Variable, Replace Temp with Query, Split Temporary Variable, Remove Assignments to Parameters, Substitute Algorithm, Split Loop, Replace Loop with Pipeline

Simplifying Conditionals

Decompose Conditional, Consolidate Conditional Expression, Remove Control Flag, Replace Nested Conditional with Guard Clauses, Replace Conditional with Polymorphism, Introduce Null Object, Introduce Assertion, Separate Query from Modifier (CQS), Remove Dead Code, Simplify Boolean

Organizing Data & Moving Features

Move Method/Function, Move Field, Extract Class, Inline Class, Hide Delegate, Remove Middle Man, Replace Data Value with Object, Replace Array with Object, Encapsulate Variable/Field, Rename Field

API & Method Signatures

Rename Function/Method/Variable/Class, Add/Remove Parameter, Parameterize Function, Remove Flag Argument, Preserve Whole Object, Replace Parameter with Query, Replace Query with Parameter, Introduce Parameter Object, Replace Constructor with Factory Function, Replace Error Code with Exception/Result Type, Return Modified Value

Inheritance & Hierarchy

Pull Up/Push Down Method/Field, Extract Superclass, Extract Interface/Protocol, Collapse Hierarchy, Replace Subclass with Delegate, Replace Superclass with Delegate, Remove Subclass

Modern Patterns

FP: Immutable Reduce, Pipeline Composition, Pure Functions
Async: async/await migration, Parallel consolidation (Promise.all / Task.WhenAll)
DI: Extract Interface for Testability, Replace Static with Injected Dependency, Repository Pattern
Reactive: Replace Polling with Observable, State Machine, Command Object
Idioms: Exhaustive Pattern Matching, Named Arguments, Value Types/Records

Architectural Patterns

Extract ViewModel (MVC/MV* → MVVM), Introduce Presenter (→ MVP), Push Business Logic to Domain (Anemic → Rich Model), Introduce Repository (scattered data access → Repository pattern), Extract Use Case / Interactor (fat controller → Clean Architecture), Fix Layer Violation (restoring clean layering), Separate Read/Write Model (CQRS lite)

---

Language Support

Don’t see your language? The skill will ask you for the test command and proceed with language-agnostic operations.

---

Safety Model

The skill has three tiers of safety enforcement:

Red Lines (stop and ask before ANY change)

• Public API changes (exported symbols, function signatures, module paths)
• Serialization format changes (JSON keys, database columns, proto fields)
• Concurrency behavior changes (lock ordering, async boundaries)
• Error contract changes (types thrown, messages matched by callers)
• Files with no test coverage
• Files with recent concurrent edits
• Moving code with side effects (emails, payments, queues) between layers
• Introducing a new architectural layer where none existed
• Moving code that participates in a transaction boundary
• Agentic Hallucinations: Guessing file paths, symbol names, or test failures instead of verifying via active tool executions.

Yellow Lines (warn, require confirmation)

• Renaming a symbol with >20 call sites
• Splitting a class used in >5 modules
• Changing parameter order with >10 callers
• Inlining a function present in multiple files

Rollback Protocol

On any test failure after an edit:

1. Revert the edit immediately
2. State exactly which test failed and with which error
3. Diagnose root cause
4. Propose a safer decomposition

The skill never fixes forward. A refactoring that breaks a test is reverted, diagnosed, and re-approached safely.

Architectural Safety (§8)

Architectural refactoring gets its own stricter protocol:

• Map first: Current architecture is mapped (layers + violations) before any file is touched
• Confirm target: User must confirm the target pattern before step 1
• The Moving Invariant: Never change logic AND location in the same step. Every move follows: Introduce → Redirect → Remove, with tests passing after each sub-step
• High confidence required: Medium confidence is not sufficient for architectural changes — blast radius is too large

Full detail: references/safety.md

---

Code Smell Detection

Before applying any operation (when no specific operation is requested), the skill diagnoses:

Full catalog with grep patterns: references/smells.md

---

Design Principles

Why one operation at a time?
Bundling changes makes failures hard to diagnose and reverts destructive. Each atomic step can be verified independently, and any failure has a clear, minimal cause.

Why smell detection before acting?
Jumping straight to a requested operation can optimize the wrong thing. Smells are diagnosed first so the most impactful change is done first — not the first one mentioned.

Why separate catalog files?
A single 60-operation reference would consume too much context. The decision tree in SKILL.md routes to exactly the catalog file needed — a composing refactoring never loads inheritance knowledge.

Why token-sparing and lazy loading?
AI agents suffer from context fatigue and cost overhead in long sessions. The skill specifies a lazy-loading rule: agents locate sections via targeted searches (grep_search) first and load only specific line-ranges (e.g., lines 40–100) using restricted view tools rather than reading whole reference guides.

Why is safety.md standalone?
Safety protocols must be read in full and are not operation-specific. Scattering stop conditions across catalog files creates inconsistent behavior. A dedicated file makes the red lines impossible to miss.

Why does architectural refactoring need its own protocol?
Code-level refactoring touches 1–3 files and has a small blast radius. Architectural refactoring is multi-file by definition, moves logic across layer boundaries, and can produce behavioral differences even when the code looks identical (transaction scope changes, side-effect timing changes, dependency direction reversal). The Moving Invariant — never change logic AND location in the same step — is what makes this safe. The Introduce → Redirect → Remove sequence ensures tests validate behavior at every sub-step.

---

Contributing

Pull requests welcome. Areas that would strengthen the skill:

• Agent setup guides for additional tools (Amp, Cline, Goose, etc.)
• Additional language profiles (PHP, Dart, Elixir, Haskell, Scala)
• Domain-specific patterns (database query refactoring, API design patterns)
• More modern idioms per language as standards evolve
• Additional smell detection grep patterns

When contributing catalog entries, use the existing format: Intent → Mechanics (numbered steps) → Example (before/after) → Inverse → Watch-outs

When contributing agent guides, follow the structure in agents/cursor.md.

---

License

MIT — use freely in personal and commercial projects.