Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup
Open on GitHub

What 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

  • /refactor simplify this method without changing what it does.
  • /refactor find duplicated code in src/ and suggest an order for fixing it.
  • /refactor replace magic numbers in this file with named constants.

How to install refactor

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup

This installs the whole start plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill refactor -a claude-code

3Manually: put the files in place

~/.claude/skills/refactor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/refactor/

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.

refactor official github The refactor skill reshapes existing code without changing its external behavior. Use it for gradual cleanup of large functions, duplication, weak types, and code smells. CX Codex +1 22,321installs refactor parcadei refactor is a Claude Code skill that guides code changes through analysis, planning, implementation, review, and test validation. It activates for refactoring requests that should preserve existing behavior. CX Codex +1 625installs refactor smallnest refactor restructures code safely based on Martin Fowler's catalog without altering external behavior. Fixes code smells through small, verifiable steps. CX Codex +1 538installs refactor boshu2 refactor — a Claude Code skill for restructuring code without changing observable behavior. Runs on requests to clean up, extract functions, remove dead code, or simplify logic. CX Codex +1 123installs refactor pproenca A skill with 43 refactoring rules drawn from Martin Fowler's catalog and Clean Code. Useful when you want the agent to restructure code by a fixed set of rules instead of guessing. CX Codex +1 661installs oma-refactor First Fluke oma-refactor — a skill for Claude Code and Codex restructures existing code while preserving observable behavior. Executes targeted technical debt cleanup through small test-gated transformations. CX Codex +1 ★ 1,472repo stars refactor-expert alirezarezvani The refactor-expert subagent reviews code structure and plans incremental refactoring. Use it to find duplication, architectural issues, and gaps in test coverage. CX Codex ★ 788repo stars refactor-code davila7 refactor-code — a slash command that walks Claude through 17 refactoring steps, from analysis and tests to performance checks and review prep. CX Codex +1 4,890installs safe-refactor JuliusBrussee safe-refactor restructures code while preserving existing behavior, enforcing verification boundaries before structural edits. CX Codex +1 130,700installs refactor-project FradSer refactor-project — a skill for Claude Code, Codex, Cursor and other agents that runs automated refactoring across every file in the project at once. Cuts duplication, normalises patterns, and strips legacy code in a single pass. CX Codex +1 122installs refactor-engineer First Fluke refactor-engineer — a subagent that rewrites code while keeping it working. Identifies hot spots, wraps them with safety tests, and applies one atomic transformation at a time. CX Codex ★ 1,472repo stars

From the same set50

The whole set →
brainstorm brainstorm guides interactive feature planning before touching code. Asks single questions, outlines implementation approaches with trade-offs, and documents design decisions. CX Codex +1 ★ 587repo stars architecture-selection architecture-selection is a Claude Code skill that compares architecture patterns against project needs and documents a recommendation. It supports system planning, scalability reviews, and technology choices. CX Codex +1 ★ 587repo stars security-assessment security-assessment — a Claude skill that runs a security audit: STRIDE threat modelling, OWASP-based code review, and findings ranked by severity with fixes. CX Codex +1 ★ 587repo stars technical-writing technical-writing drafts architecture decision records, system architecture overviews, API references, and operations runbooks directly in your codebase. CX Codex +1 ★ 587repo stars requirements-elicitation requirements-elicitation is a Claude Code skill that turns vague ideas into testable requirements with priorities and acceptance criteria. CX Codex +1 ★ 587repo stars pattern-detection pattern-detection finds naming conventions, architectural layers, and test styles across files. Keeps generated code aligned with repository habits. CX Codex +1 ★ 587repo stars monitor-production The monitor-production subagent plans production metrics, logs, traces, alerts, and dashboards. Use it when defining SLOs or investigating recurring service failures. CX Codex ★ 587repo stars review-compatibility review-compatibility — a subagent for Claude Code that examines code for breaking changes to APIs, databases, and configs. CX Codex ★ 587repo stars

Project sponsors

Companies that keep this analytics open