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
npx skills add justxor/claude-code-pro-course --skill refactor -a claude-codeWhat 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.pyto remove duplication - Split
services/auth.tsinto several files without changing behavior - Simplify
utils/helpers.jsand lock the behavior with tests
How to install refactor
1Skills CLI (Vercel)
npx skills add justxor/claude-code-pro-course --skill refactor -a claude-code2Manually: 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 justxor/claude-code-pro-course --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 justxor/claude-code-pro-course --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 justxor/claude-code-pro-course starter-kit/.claude/skills/refactor2Manually: put the files in place
.github/skills/refactor/SKILL.md1Skills CLI (Vercel)
npx skills add justxor/claude-code-pro-course --skill refactor -a gemini-cli2Platform CLI
gemini skills install https://github.com/justxor/claude-code-pro-course --path starter-kit/.claude/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?
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.