Skip to main content
skill CX Codex

refactoring-code — Claude Code skill: what it does, how to install

refactoring-code is a Claude Code skill that stages simplification refactors: approve the plan before edits, then check that behaviour stays the same.

no license 124 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code
Open on GitHub

What refactoring-code does

This skill runs a simplification refactor in stages, with behaviour as the thing you must not break. No edit lands before the plan is approved, and each run handles one target file. Raw code and diffs stay inside subagents, so only short reports travel between phases.

Four subagents do the work: behavior-mapper records the baseline and the risky spots, chunk-analyst takes one analysis dimension per chunk, refactor-implementer applies the approved plan, refactor-reviewer returns two verdicts — behaviour preserved, and did the code get simpler. The reuse ladder and deletion test sit in references/simplification-heuristics.md, hard stops in references/protected-surfaces.md, reports in .handoffs/refactoring-code/. Only TARGET_PATH is required, and MAX_LINES defaults to 250.

AUTO_APPROVE=true keeps the gates. The plan card passes on its own only when it carries no size waiver, no validation command outside safe, and no protected-surface carve-out; anything else ends the run as NEEDS_CLARIFICATION. Touching a protected surface stops the run, and re-approving a wider fix scope under AUTO_APPROVE always returns BLOCKED.

What it helps with

  • split a large file without changing behaviour
  • strip duplication before adding new code
  • rename or move a module and keep tests green
  • find out which files a refactor must not touch
  • follow a refactor through short reports instead of raw diffs

Example prompts for the agent

  • Simplify src/billing/invoice.ts, keep behaviour identical, tests: npm test -- invoice
  • Split src/api/router.ts, cap at 300 lines, leave protected surfaces alone
  • Look at src/queue/worker.ts and tell me what could be simplified, plan only

How to install refactoring-code

1Skills CLI (Vercel)

npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code

2Manually: put the files in place

~/.claude/skills/refactoring-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/refactoring-code/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about refactoring-code

How do I install refactoring-code in Claude Code?

Run npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code. The skill ends up at ~/.claude/skills/refactoring-code/SKILL.md.

What does refactoring-code do?

It drives a simplification refactor through phases: baseline, plan, approved edits, then a check that behaviour did not change. Code and diffs never leave the subagents.

What happens if an edit reaches a protected surface?

The run stops. Crossing references/protected-surfaces.md counts as a hard stop until the user reframes the task outside this skill.

Similar skills

All skills for Code review and refactoring →

From the same set12

The whole set →
review-pull-request review-pull-request audits a single GitHub pull request across isolated stages, drafts a local Markdown report, and posts comments only when confirmed. CX Codex +1 161installs committing-scoped-changes committing-scoped-changes splits an explicit list of files or folders into separate git commits and leaves the rest of the working tree alone. CX Codex +1 153installs responding-to-pr-review-comments The responding-to-pr-review-comments skill gathers pull request comments, assesses the feedback, and drafts replies. With confirmation, it can post approved text to supported GitHub comment threads. CX Codex +1 144installs clarifying-assumptions clarifying-assumptions — a skill that runs the conversational layer for plan verification. Asks critical questions upfront or before individual tasks, delegates artifact analysis to subagents. CX Codex +1 129installs diagnosing-root-causes The diagnosing-root-causes skill traces bugs, regressions, and CI/CD failures from supplied evidence, then produces a reviewed root-cause report. Use it when a problem report needs investigation rather than guesswork. CX Codex +1 122installs rewriting-code-strictly rewriting-code-strictly is a Claude Code skill that rewrites Python, TypeScript/JavaScript, or Go with stricter typing and boundary checks. It runs on requests to harden code or align it with static analysis tools. CX Codex +1 122installs improving-test-suites improving-test-suites is a Claude Code skill that reviews test suites and focuses them on important behavior. It activates for requests to trim, rewrite, review, or strengthen tests. CX Codex +1 119installs planning-codebase-restructuring planning-codebase-restructuring is a Claude Code skill that maps a codebase and prepares a restructuring plan without changing files. It produces an evidence-backed report for a later implementation pass. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open