refactor
Provides a structured workflow for safely refactoring code while maintaining functional integrity.
Install
mkdir -p .claude/skills/refactor-jimzandueta && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/18699" && unzip -o skill.zip -d .claude/skills/refactor-jimzandueta && rm skill.zipInstalls to .claude/skills/refactor-jimzandueta
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
- Restructuring code without changing external behavior. - Extracting reusable modules or functions from duplicated code. - Simplifying complex logic or reducing cyclomatic complexity. - Migrating to a new pattern or convention. - Addressing tech debt identified during code revieKey capabilities
- →Restructure code without changing external behavior
- →Extract reusable modules or functions
- →Simplify complex logic
- →Migrate to new patterns or conventions
- →Address technical debt
- →Ensure test coverage before changes
How it works
The workflow defines a goal, ensures test coverage, checks memory for context, plans the refactor, applies changes incrementally, and verifies behavior preservation. It concludes with running checklists and updating memory.
Inputs & outputs
When to use refactor
- →Reducing cyclomatic complexity
- →Extracting reusable logic
- →Refactoring for tech debt
About this skill
Skill: Refactor
Use When
- Restructuring code without changing external behavior.
- Extracting reusable modules or functions from duplicated code.
- Simplifying complex logic or reducing cyclomatic complexity.
- Migrating to a new pattern or convention.
- Addressing tech debt identified during code review.
Workflow
- Define the goal: What specific improvement does this refactor achieve? (Better readability, less duplication, clearer interfaces, improved testability.)
- Ensure test coverage: Before changing anything, confirm existing tests cover the code being refactored. Add tests first if coverage is insufficient.
- Check memory: Read
memory/learned-patterns.mdandmemory/decisions.mdfor context on why the code is structured this way. There may be a reason. - Plan the refactor: List files to change. Identify the transformation (extract function, move module, rename, simplify conditional, etc.). Keep changes to one transformation type per PR.
- Apply incrementally: Make small, verifiable steps. Run tests after each step. If tests fail, revert the last step.
- Verify behavior preservation: After the refactor, the test suite must produce identical results. No behavior change is allowed unless explicitly documented.
- Run checklists: Complete
checklists/pre-commit.md. - Update memory: Document the new pattern in
memory/learned-patterns.md. If the refactor represents a decision, add an ADR tomemory/decisions.md.
Common Refactoring Operations
| Operation | When | Risk |
|---|---|---|
| Extract function | Logic block is reused or too long | Low — tests catch regressions |
| Extract module | File does too many things | Medium — import paths change |
| Rename | Name is misleading or doesn't follow convention | Low — find-and-replace |
| Inline | Abstraction adds complexity without value | Low — removes indirection |
| Move file | File is in the wrong directory | Medium — import paths change |
| Simplify conditional | Deep nesting or complex boolean logic | Medium — logic can be subtle |
| Replace algorithm | Better approach exists for the same problem | High — must prove equivalence |
Rules
- No behavior changes: A refactor PR must not change what the code does — only how it's structured.
- Tests first: If the code lacks tests, add them before refactoring. Never refactor untested code.
- One transformation per PR: Don't mix extract + rename + move in a single PR.
- Check for dependents: Before renaming or moving, find all callers/importers.
- Preserve the public interface: Internal restructuring is fine; changing function signatures requires a separate task.
- Don't refactor during a bug fix: Fix the bug first. Refactor afterward in a separate PR.
Done
- All existing tests pass — no behavior change.
- Code is measurably simpler (fewer lines, less duplication, lower complexity, clearer interfaces).
checklists/pre-commit.mdcompleted.- New pattern documented in
memory/learned-patterns.md. - No anti-patterns from
anti-patterns/general.mdintroduced.
When not to use it
- →When changing external behavior is the primary goal
- →When fixing a bug (fix the bug first, then refactor)
Limitations
- →A refactor PR must not change what the code does
- →If the code lacks tests, they must be added before refactoring
- →Only one transformation type is allowed per PR
How it compares
This workflow enforces a strict 'no behavior changes' rule and incremental application of changes with continuous testing, ensuring that refactoring improves code quality without introducing regressions, unlike ad-hoc refactoring that might
Compared to similar skills
refactor side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| refactor (this skill) | 0 | 3mo | No flags | Intermediate |
| effective-go | 323 | 9mo | No flags | Beginner |
| solid-principles | 57 | 9mo | No flags | Intermediate |
| typescript-review | 39 | 1mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
effective-go
openshift
Apply Go best practices, idioms, and conventions from golang.org/doc/effective_go. Use when writing, reviewing, or refactoring Go code to ensure idiomatic, clean, and efficient implementations.
solid-principles
SmidigStorm
Enforce SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) in object-oriented design. Use when writing or reviewing classes and modules.
typescript-review
metabase
Review TypeScript and JavaScript code changes for compliance with Metabase coding standards, style violations, and code quality issues. Use when reviewing pull requests or diffs containing TypeScript/JavaScript code.
ast-grep
ast-grep
Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.
serena
massgen
This skill provides symbol-level code understanding and navigation using Language Server Protocol (LSP). Enables IDE-like capabilities for finding symbols, tracking references, and making precise code edits at the symbol level.
typescript
lobehub
TypeScript code style and optimization guidelines. Use when writing TypeScript code (.ts, .tsx, .mts files), reviewing code quality, or implementing type-safe patterns. Triggers on TypeScript development, type safety questions, or code style discussions.