Skip to main content
skill CX Codex

refactoring-surgeon — Claude Code skill: refactoring and setup

The refactoring-surgeon skill guides small code-structure changes while keeping behavior intact. Use it to tackle code smells, duplication, or legacy code.

MIT 260 installs ★ 274 updated 2026-09-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill refactoring-surgeon -a claude-code
Open on GitHub

What refactoring-surgeon does

refactoring-surgeon helps identify a code smell and choose a focused change, such as extracting a method or class, replacing a conditional with polymorphism, or grouping parameters. Its ./references/ directory contains technique examples. The ./scripts/validate-refactoring.sh script checks for smell indicators, duplication, complexity, and refactoring safety.

The workflow calls for small edits and test runs after each one; it also keeps feature work separate from refactoring. Tests are the safety net, so changing structure without coverage makes behavior harder to verify. The listed tools include file reading and editing, plus npm test, npm run lint, and git. This skill is for refactoring, not feature development, bug fixing, or performance tuning.

What it helps with

  • extract a method from an overlong function
  • split responsibilities in a large class
  • replace type-checking conditionals with polymorphism
  • reduce duplication while migrating legacy code

Example prompts for the agent

  • Review this module for code smells and outline a safe refactoring plan.
  • Extract the repeated logic into a method and run tests after each change.
  • Restructure this legacy code without adding features or changing its behavior.

How to install refactoring-surgeon

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill refactoring-surgeon -a claude-code

2Manually: put the files in place

~/.claude/skills/refactoring-surgeon/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/refactoring-surgeon/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about refactoring-surgeon

How do I install refactoring-surgeon in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill refactoring-surgeon -a claude-code. The skill file is placed at ~/.claude/skills/refactoring-surgeon/SKILL.md.

What does refactoring-surgeon do?

It helps spot code smells and make incremental structural changes while preserving behavior. Its techniques include extracting methods and replacing conditionals with polymorphism.

Why does refactoring-surgeon recommend tests?

Tests act as a safety net while the code structure changes. The workflow recommends running them after each edit to check that behavior remains intact.

Source text

SKILL.md · MIT
---
name: refactoring-surgeon
description: 'Expert code refactoring specialist for improving code quality without changing behavior. Activate on: refactor, code smell, technical debt, legacy code, cleanup, simplify, extract method,
  extract class, DRY, SOLID principles. NOT for: new feature development (use feature skills), bug fixing (use debugging skills), performance optimization (use performance skills).'
allowed-tools: Read,Write,Edit,Bash(npm test:*,npm run lint:*,git:*)
metadata:
  category: Code Quality & Testing
  pairs-with:
  - skill: code-necromancer
    reason: Refactor resurrected legacy code
  - skill: test-automation-expert
    reason: Tests before refactoring
  tags:
  - refactoring
  - code-smells
  - solid
  - dry
  - cleanup
---

# Refactoring Surgeon

Expert code refactoring specialist focused on improving code quality without changing behavior.

## Quick Start

1. **Ensure tests exist** - Never refactor without a safety net
2. **Identify the smell** - Name the specific code smell you're addressing
3. **Make small changes** - One refactoring at a time, commit frequently
4. **Run tests after each change** - Behavior must remain identical
5. **Don't add features** - Refactoring ≠ enhancement
6. **Document significant changes** - Explain the "why" for future maintainers

## Core Capabilities

| Category | Techniques |
|----------|------------|
| **Extraction** | Extract Method, Extract Class, Extract Interface |
| **Movement** | Move Method, Move Field, Inline Method |
| **Simplification** | Replace Conditional with Polymorphism, Decompose Conditional |
| **Organization** | Introduce Parameter Object, Replace Magic Numbers |
| **Legacy Migration** | Strangler Fig, Branch by Abstraction, Parallel Change |

## Code Smells Reference

### Bloaters
```
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│    Long Method      │    │    Large Class      │    │   Long Parameter    │
│  > 20 lines?        │    │  > 200 lines?       │    │       List          │
│  → Extract Method   │    │  → Extract Class    │    │  → Parameter Object │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
```

### OO Abusers
```
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Switch Statements  │    │   Refused Bequest   │    │   Parallel          │
│  Type-checking?     │    │  Unused inheritance?│    │   Hierarchies       │
│  → Polymorphism     │    │  → Delegation       │    │  → Move Method      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘
```

### Change Preventers
```
┌─────────────────────┐    ┌─────────────────────┐
│  Divergent Change   │    │  Shotgun Surgery    │
│  One class, many    │    │  One change, many   │
│  reasons to change? │    │  classes affected?  │
│  → Extract Class    │    │  → Move/Inline      │
└─────────────────────┘    └─────────────────────┘
```

## Reference Examples

Complete refactoring examples in `./references/`:

| File | Pattern | Use Case |
|------|---------|----------|
| `extract-method.ts` | Extract Method | Long methods → focused functions |
| `replace-conditional-polymorphism.ts` | Replace Conditional | switch/if → polymorphic classes |
| `introduce-parameter-object.ts` | Parameter Object | Long params → structured objects |
| `strangler-fig-pattern.ts` | Strangler Fig | Legacy code → gradual migration |

## Anti-Patterns (10 Critical Mistakes)

### 1. Big Bang Refactoring
**Symptom**: Rewriting entire modules in one massive change
**Fix**: Strangler fig pattern, small incremental changes with tests

### 2. Refactoring Without Tests
**Symptom**: Changing structure without test coverage
**Fix**: Write characterization tests first, add coverage for affected areas

### 3. Premature Abstraction
**Symptom**: Creating generic frameworks "for future flexibility"
**Fix**: Wait for three concrete examples before abstracting (Rule of Three)

### 4. Renaming Without IDE Support
**Symptom**: Find-and-replace that misses occurrences
**Fix**: Use IDE refactoring tools, search for usages first

### 5. Mixing Refactoring and Features
**Symptom**: Adding new functionality while restructuring
**Fix**: Separate commits - refactor first, then add features

### 6. Ignoring Code Reviews
**Symptom**: Large refactoring PRs that are hard to review
**Fix**: Small, focused PRs with clear commit messages

### 7. Over-Abstracting
**Symptom**: Three layers of abstraction for a simple operation
**Fix**: YAGNI - start concrete, abstract when patterns emerge

### 8. Incomplete Refactoring
**Symptom**: Starting Extract Method but leaving partial duplication
**Fix**: Complete the refactoring or revert - no half-measures

### 9. Refactoring Production During Incidents
**Symptom**: "I'll just clean this up while I'm here..."
**Fix**: Never refactor during incidents - fix the bug, create a ticket

### 10. Not Measuring Improvement
**Symptom**: Refactoring without knowing if it helped
**Fix**: Track metrics: complexity, test coverage, build time

## Safety Checklist

**Before Refactoring:**
- [ ] Code compiles/runs successfully
- [ ] All tests pass
- [ ] Test coverage is adequate for area being refactored
- [ ] Commit current state (can rollback)

**During Refactoring:**
- [ ] Make small, incremental changes
- [ ] Run tests after each change
- [ ] Keep behavior identical
- [ ] Don't add features while refactoring

**After Refactoring:**
- [ ] All tests still pass
- [ ] No new warnings/errors
- [ ] Code is more readable
- [ ] Complexity metrics improved
- [ ] Document significant changes

## Quality Checklist

- [ ] No behavior changes (tests prove this)
- [ ] Improved readability
- [ ] Reduced complexity (cyclomatic, cognitive)
- [ ] Better adherence to SOLID principles
- [ ] Removed duplication (DRY)
- [ ] More testable code
- [ ] Clear naming
- [ ] Appropriate abstractions (not over-engineered)

## Validation Script

Run `./scripts/validate-refactoring.sh` to check:
- Test coverage presence
- Code smell indicators
- Duplication patterns
- Complexity metrics
- SOLID violations
- Refactoring safety (git, uncommitted changes)

## External Resources

- [Refactoring.Guru](https://refactoring.guru/)
- [Martin Fowler's Refactoring Catalog](https://refactoring.com/catalog/)
- [Working Effectively with Legacy Code](https://www.oreilly.com/library/view/working-effectively-with/0131177052/)

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Code review and refactoring →

From the same set180

The whole set →
ux-friction-analyzer ux-friction-analyzer evaluates interface flows using cognitive load theory, Gestalt rules, and ADHD-friendly design. It highlights user friction points before you build features. CX Codex +1 266installs color-contrast-auditor color-contrast-auditor — a skill that catches color pairs failing WCAG 2.1 and proposes fixes. Use it before launch, when auditing CSS, or when a screenshot has text you can barely read. CX Codex +1 262installs playwright-screenshot-inspector playwright-screenshot-inspector — a skill for visual UI testing: runs Playwright in headless mode, captures screenshots, and analyzes them through a multimodal model. CX Codex +1 262installs tech-entrepreneur-coach-adhd tech-entrepreneur-coach-adhd is a Claude Code skill for ADHD founders moving from big tech into independent app development. It activates on startup, MVP, monetization, and side-project requests. CX Codex +1 260installs drone-cv-expert drone-cv-expert — a skill for autonomous drones and computer vision: flight control, SLAM, object detection, path planning. Activates on drone, UAV, SLAM and related terms. CX Codex +1 259installs project-management-guru-adhd project-management-guru-adhd is a Claude Code skill that helps ADHD engineers manage multiple projects, protecting hyperfocus and reducing context switches. CX Codex +1 253installs design-system-creator The design-system-creator skill builds design systems with tokens, CSS structure, component docs, and style guides. Use it when a project needs a shared UI foundation. CX Codex +1 250installs fullstack-debugger fullstack-debugger troubleshoots Next.js 15, Cloudflare Workers, and Supabase apps layer by layer. Fixes auth errors, broken RLS policies, CORS, and build failures. CX Codex +1 244installs

Project sponsors

Companies that keep this analytics open