refactoring-surgeon

Q: How do I install refactoring-surgeon?

Run npx skills add https://github.com/curiositech/some_claude_skills --skill refactoring-surgeon in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/refactoring-surgeon/ (personal) or .claude/skills/refactoring-surgeon/ (project).

by curiositechCode Quality & Workflow

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).

Installs: 248
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/curiositech/some_claude_skills --skill refactoring-surgeon

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads refactoring-surgeon automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Refactoring Surgeon

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

Quick Start

Ensure tests exist - Never refactor without a safety net
Identify the smell - Name the specific code smell you're addressing
Make small changes - One refactoring at a time, commit frequently
Run tests after each change - Behavior must remain identical
Don't add features - Refactoring ≠ enhancement
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:

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

FAQ

What does the refactoring-surgeon skill do?

How do I install refactoring-surgeon?

Run npx skills add https://github.com/curiositech/some_claude_skills --skill refactoring-surgeon in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/refactoring-surgeon/ (personal) or .claude/skills/refactoring-surgeon/ (project).

Which AI agents can use refactoring-surgeon?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is refactoring-surgeon safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains refactoring-surgeon?

It is published by curiositech in curiositech/some_claude_skills. It has 248 recorded installs.