refactor · rsmdt — Claude Code skill: what it does and how to install
The refactor skill analyzes a chosen part of a codebase and guides step-by-step cleanup while preserving behavior. Use it to improve readability without changing business logic.
MIT ★ 587 updated 2026-10-26
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startupWhat refactor does
The skill looks for structural issues such as duplicated code, dense expressions, unclear names, and magic numbers. Specialist agents handle the analysis; the skill then deduplicates and ranks their findings, and asks you to choose a working mode. Each finding includes a location, a suggested technique, and a risk.
It runs existing tests before edits, then checks tests after every individual change. If a check fails, it reverts that edit. When coverage is missing, the skill asks whether to add tests, continue without coverage, or cancel. Refactoring untested code requires user approval, so you stay in control of that risk.
The scope is internal code structure. External behavior, public API contracts, and business logic results must remain unchanged. A full test run follows the edits, and the skill asks what you want to do next.
What it helps with
- replace nested ternaries with clearer branching
- give abbreviated variables descriptive names
- extract magic numbers into named constants
- remove duplication while keeping behavior intact
- verify each refactoring change with tests
Example prompts for the agent
/refactorsimplify this method without changing what it does./refactorfind duplicated code insrc/and suggest an order for fixing it./refactorreplace magic numbers in this file with named constants.
How to install refactor
1Plugin marketplace
/plugin marketplace add rsmdt/the-startup/plugin install start@the-startupThis installs the whole start plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill refactor -a claude-code3Manually: put the files in place
~/.claude/skills/refactor/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/refactor/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill refactor -a codex2Manually: put the files in place
.agents/skills/refactor/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill refactor -a cursor2Manually: put the files in place
.cursor/skills/refactor/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/start/skills/refactor2Manually: put the files in place
.github/skills/refactor/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill refactor -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/start/skills/refactorManually: put the files in place
.devin/skills/refactor/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about refactor
How do I install refactor in Claude Code?
Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install start@the-startup.
What does refactor do?
It delegates code analysis to specialist agents, ranks the findings, and guides you through changes one at a time, running tests after each edit.
What happens when the target code has no test coverage?
The skill asks whether you want to add tests first, proceed without coverage, or cancel. It requires your approval before refactoring untested code.
Source text
SKILL.md · MIT
---
name: refactor
description: Refactor, simplify, or clean up code for improved maintainability without changing business logic
user-invocable: true
argument-hint: "describe what code needs refactoring and why"
---
## Persona
Act as a refactoring orchestrator that improves code quality while strictly preserving all existing behavior.
**Refactoring Target**: $ARGUMENTS
## Interface
Finding {
impact: HIGH | MEDIUM | LOW
title: string // max 40 chars
location: string // shortest unique path + line
problem: string // one sentence
refactoring: string // specific technique to apply
risk: string // potential complications
}
State {
target = $ARGUMENTS
perspectives = [] // from reference/perspectives.md
mode: Standard | Agent Team | Dynamic Workflow
baseline: string
findings: Finding[]
}
**In scope:** Code structure, internal implementation, naming, duplication, readability, dependencies. Specific techniques: nested ternaries to if/else or switch, dense one-liners to multi-line with clear steps, clever tricks to obvious implementations, abbreviations to descriptive names, magic numbers to named constants.
**Out of scope:** External behavior, public API contracts, business logic results, side effect ordering.
## Constraints
**Always:**
- Delegate all analysis tasks to specialist agents.
- Establish test baseline before any changes.
- Run tests after EVERY individual change.
- One refactoring at a time — never batch changes before verification.
- Revert immediately if tests fail or behavior changes.
- Get user approval before refactoring untested code.
**Never:**
- Change external behavior, public API contracts, or business logic results.
## Reference Materials
- reference/perspectives.md — analysis perspectives
- reference/code-smells.md — smell catalog
- reference/output-format.md — output guidelines
- examples/output-example.md — output example
## Workflow
### 1. Establish Baseline
Locate target code from $ARGUMENTS. Run existing tests to establish baseline.
Read reference/output-format.md and format the baseline report accordingly.
match (baseline) {
tests failing => stop, report to user
coverage gaps => ask the user to choose: Add tests first (recommended) | Proceed without coverage | Cancel
ready => continue
}
### 2. Select Mode
Ask the user to choose:
Standard (default) — parallel fire-and-forget analysis agents
Agent Team — persistent analyst teammates with coordination
Dynamic Workflow — one inline workflow script fans out the analysts and collects their findings (analysis only; changes stay sequential)
Recommend Agent Team when scope >= 5 files, multiple interconnected modules, or large codebase.
Recommend Dynamic Workflow instead when those thresholds apply but the analysts need no coordination with each other.
### 3. Analyze Issues
Read reference/perspectives.md for perspective definitions.
Determine perspectives based on target intent: use simplification perspectives for within-function readability work, standard perspectives for structural/architectural refactoring.
match (mode) {
Standard => launch parallel subagents per applicable perspectives
Agent Team => create team, spawn one analyst per perspective, assign tasks
Dynamic Workflow => run one dynamic workflow: one analyst agent per perspective in parallel, returning every finding; no agent in it edits code
}
For Dynamic Workflow, these instructions are the opt-in: call the Workflow tool directly with an inline script. Do not load the workflow-authoring reference or assemble the script through shell commands first — runs that detour through either stall before launching. Choose `model` and `effort` per stage from what the stage does. Mechanical stages — running a command, gathering or quoting sources, mapping text into a fixed schema — can run on a smaller, faster model at lower effort. Analysis, writing, and judging another agent's work need the strongest model. A judging stage never runs on a weaker model than the stage it judges. When unsure, omit `model` so the stage inherits the session model.
Process findings:
1. Deduplicate overlapping issues.
2. Rank by impact (descending), then risk (ascending).
3. Sequence independent items first, dependent items after.
Read reference/output-format.md and present analysis summary accordingly.
Ask the user to choose: Document and proceed | Proceed without documenting | Cancel
If Cancel: stop, report summary of findings discovered.
### 4. Execute Changes
Apply changes sequentially — behavior preservation requires it.
For each refactoring in findings:
1. Apply single change.
2. Run tests immediately.
3. If tests pass: mark complete, continue.
4. If tests fail: `git checkout -- <changed files>`. Read reference/output-format.md for error recovery format.
### 5. Final Validation
Run complete test suite. Compare behavior with baseline.
Read reference/output-format.md and present completion summary accordingly.
Ask the user to choose: Commit changes | Run full test suite | Address skipped items | Done
© Rudolf S. · MIT · rsmdt/the-startup
Similar skills
All skills for Code review and refactoring →refactor by other authors comes first.