Refactor

Skill pvnarp/agent-skills/skills/refactor

Skills I use with Claude Code across my projects. Architecture, code review, testing, security, deployment, and more.

Install

npx -y skills add pvnarp/agent-skills --skill refactor

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Plans and executes safe code refactoring. Identifies code smells, proposes transformations, ensures behavior preservation, and validates with tests. Use when restructuring code, extracting modules, or cleaning up technical debt.

SKILL.md

3.5 KB, as published. Nobody here has run it

Refactoring

Refactoring changes structure, not behavior. If behavior changes, that's a feature or a bug fix - not a refactor.

Before Starting

Tests exist and pass. If they don't, write them first. Refactoring without tests is just moving code around and hoping.
Define the goal. Why refactor? "Cleaner" isn't a goal. "Extract payment logic so we can add Stripe" is.
Scope it. Refactor ONE thing at a time. Don't refactor the module while also adding a feature.

Code Smells to Look For

Smell	Signal	Action
God object	Class/module does 5+ unrelated things	Extract into focused modules
Shotgun surgery	One change requires editing 10 files	Consolidate related logic
Feature envy	Method uses another class's data more than its own	Move method to where the data lives
Primitive obsession	Passing 5 strings instead of a typed object	Introduce a domain type
Long parameter list	Function takes 6+ parameters	Group into config/options object
Duplicated logic	Same pattern in 3+ places	Extract shared function (NOT for 2 places - wait for the third)
Deep nesting	4+ levels of if/for/try	Early returns, extract helper, guard clauses
Dead code	Unused functions, unreachable branches	Delete it. Git remembers.
Unclear naming	Need to read the implementation to understand the name	Rename to reveal intent

Safe Refactoring Steps

Run tests - green baseline
Make one small change - rename, extract, move, inline
Run tests - still green?
Commit - small, atomic commit with clear message
Repeat - next change

Never batch multiple refactoring steps into one commit. If something breaks, you need to know exactly which change caused it.

Refactoring Patterns

Extract Function

WHEN: A block of code does a distinct thing and can be named
TRANSFORM: Move into a named function. Pass inputs as parameters, return outputs.
VERIFY: Behavior identical. No side effects changed.

Extract Module/Class

WHEN: A file has grown to handle multiple responsibilities
TRANSFORM: Group related functions + data into a new module. Update imports.
VERIFY: All call sites work. No circular dependencies introduced.

Inline

WHEN: An abstraction adds complexity without value (single-use helper, trivial wrapper)
TRANSFORM: Replace calls with the implementation. Delete the wrapper.
VERIFY: Behavior identical. Readability improved.

Rename

WHEN: Name doesn't reveal intent or is misleading
TRANSFORM: Rename across all usages. Update docs if any.
VERIFY: No broken references. Search for string-based references (configs, serialization).

Move

WHEN: Code lives in the wrong module (feature envy, wrong layer)
TRANSFORM: Move to the module where it belongs. Update imports.
VERIFY: Dependency direction still correct. No circular deps.

Anti-Patterns

Refactoring code you don't understand yet (read first, refactor second)
Refactoring and changing behavior in the same commit
Creating abstractions "for the future" (YAGNI)
Refactoring stable, working code that nobody needs to change
Replacing simple repeated code with a clever generic solution

Gives 4 of the 12 instructions most refactoring skills give

Counted across 521 of the 525 authors here whose files we hold, read 2026-08-06

run tests after each changehere, and in 59 of 521, across 56 files
write tests before refactoringhere, and in 27 of 521, across 24 files
preserve external behaviorin 26 of 521, across 22 files
remove dead codehere, and in 25 of 521, across 24 files
make small incremental changesin 20 of 521, across 17 files
break the implementation into tiny commitsin 18 of 521, across 5 files
ask the user about alternative optionsin 17 of 521, across 4 files
create a GitHub issue with the planin 17 of 521, across 4 files
explore the repository to verify assertionsin 17 of 521, across 4 files
interview the user about the refactorin 16 of 521, across 3 files
check the codebase for test coveragein 16 of 521, across 3 files
refactor one thing at a timehere, and in 16 of 521, across 12 files

Said here and by no other author read

define a specific refactoring goal

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.