Skip to main content
skill CX Codex

refactor · justxor — Claude Code skill: safe refactoring in small steps

A Claude Code skill that runs refactoring as a sequence of small, behavior-preserving steps. Use it when you ask the agent to split a module or remove duplication.

MIT ★ 353 updated 2026-10-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add justxor/claude-code-pro-course --skill refactor -a claude-code
Open on GitHub

What refactor does

The refactor skill makes the agent follow a fixed routine. First it checks whether the affected code has passing tests. If there are none, the skill requires characterization tests for current behavior, committed before any changes.

Then the agent writes a plan: renames, extracting functions, moving code. Every step leaves the project in a working state. Tests and type checks run after each step, and a red run means rolling that step back and trying another way.

The skill forbids mixing refactoring with new features or bug fixes. Bugs found during the work go into a report instead of the code. At the end the agent summarizes what changed, counts lines and functions before and after, and lists discovered bugs. Without green tests first, the skill will not proceed.

What it helps with

  • split a large module without breaking behavior
  • remove code duplication in small steps
  • rename functions and variables with test verification
  • lock in current behavior with characterization tests before refactoring
  • get a report with found bugs and before/after metrics

Example prompts for the agent

  • Refactor src/parser.py to remove duplication
  • Split services/auth.ts into several files without changing behavior
  • Simplify utils/helpers.js and lock the behavior with tests

How to install refactor

1Skills CLI (Vercel)

npx skills add justxor/claude-code-pro-course --skill refactor -a claude-code

2Manually: 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?

Run npx skills add justxor/claude-code-pro-course --skill refactor -a claude-code. The skill lands in ~/.claude/skills/refactor/SKILL.md.

What does the refactor skill do?

It refactors in small steps without changing behavior: tests first, then a plan, then step-by-step work with tests and type checks after each step. Found bugs are written to a report, not fixed.

What happens if the affected code has no tests?

The skill will not start refactoring. The agent first writes characterization tests that capture current behavior and commits them.

Source text

SKILL.md · MIT
---
name: refactor
description: Безопасный рефакторинг маленькими шагами без изменения поведения. Используй, когда просят отрефакторить, упростить, разделить модуль, убрать дублирование или почистить код.
argument-hint: <файл или модуль> [цель]
---

# Refactor: $ARGUMENTS

Правило №1: **поведение не меняется.**

1. Убедись, что тесты для затрагиваемого кода есть и зелёные. Если тестов нет — сначала напиши характеризационные тесты на текущее поведение и закоммить их.
2. Опиши план: список маленьких шагов (переименование, выделение функции, перенос и т.д.). Каждый шаг оставляет проект рабочим.
3. Выполняй шаги по одному. После каждого:
   - запусти тесты и проверку типов;
   - если красное — откати шаг и попробуй иначе.
4. Не смешивай рефакторинг с новыми фичами и исправлениями багов. Найденные баги — запиши в отчёт.
5. Итог: что изменилось, метрики (строк/функций до и после), найденные баги, что стоит сделать дальше.

© justxor · MIT · justxor/claude-code-pro-course

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 refactor-method-complexity-reduce official github refactor-method-complexity-reduce refactors a chosen method by moving complex logic into helpers. Use it when nested conditions or branching make a method hard to follow. CX Codex +1 9,992installs w-refactor blockmatic-icebox The w-refactor Claude Code skill restructures selected code while preserving its behavior. It starts by recording a baseline with tests, type checks, or a manual scenario. CX Codex +1 647installs refactor-legacy-code aj-geddes refactor-legacy-code guides systematic legacy code refactoring without breaking features. Built for paying down technical debt and replacing deprecated patterns. CX Codex +1 611installs deep-module-refactor zebbern deep-module-refactor inspects your codebase for shallow modules, drafts deeper alternative interfaces with sub-agents, and files a refactor RFC directly to GitHub Issues. CX Codex +1 ★ 4,719repo stars 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 lsp-refactor blackwell-systems The lsp-refactor Claude Code skill checks a refactor’s impact, simulates edits, applies them, then verifies the build and runs related tests. It pauses for confirmation above 20 references. CX Codex +1 ★ 182repo stars

From the same set15

The whole set →
pr-description pr-description generates clear pull request titles and descriptions by inspecting branch commits and diffs against main. CX Codex +1 ★ 353repo stars architect The architect subagent examines a project before implementation, compares design options, and lays out a change plan. Use it to scope a feature or a major refactor. CX Codex ★ 353repo stars code-reviewer code-reviewer reads your diff, flags security holes, missing tests and edge cases, then returns a severity-sorted report with a file and line for each fix. CX Codex ★ 353repo stars write-tests write-tests generates unit tests for a chosen file or function while matching existing project patterns. It runs new checks and flags discovered bugs instead of bending assertions. CX Codex +1 ★ 353repo stars commit This skill reviews your working changes and creates a git commit in Conventional Commits format. Use it when you want an agent to make a commit that follows the repository’s message style. CX Codex +1 ★ 353repo stars release-notes Generates release notes and CHANGELOG entries between Git tags or from the latest tag to HEAD using Conventional Commits. CX Codex +1 ★ 353repo stars onboard The onboard skill gives a new developer a guided introduction to a codebase, from its layout to its main workflows. Use it when someone needs to get oriented and find a first task. CX Codex +1 ★ 353repo stars code-review The code-review skill checks changes in the current branch against main and produces a report with notes on correctness, security, tests, and readability. CX Codex +1 ★ 353repo stars

Project sponsors

Companies that keep this analytics open