# refactoring-code

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 124 installs · ★ 3 repo stars
- Author: b-mendoza
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/b-mendoza/agent-skills/tree/HEAD/skills/refactoring-code/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/refactoring-code

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill refactoring-code -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/refactoring-code/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/refactoring-code/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill refactoring-code -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/refactoring-code/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill refactoring-code -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/refactoring-code/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install b-mendoza/agent-skills skills/refactoring-code
```

2. **Manually: put the files in place**
- File: `.github/skills/refactoring-code/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill refactoring-code -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/b-mendoza/agent-skills --path skills/refactoring-code
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/refactoring-code/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add b-mendoza/agent-skills --skill refactoring-code -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/b-mendoza/agent-skills/tree/HEAD/skills/refactoring-code/SKILL.md

## When to use it
- 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
- 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

## Similar
- [refactoring](https://affpapa.org/en/nevibecode/skills/refactoring.md) — skill · 670 installs
- [refactoring-analysis](https://affpapa.org/en/nevibecode/skills/refactoring-analysis.md) — skill · 434 installs
- [code-refactoring-tech-debt](https://affpapa.org/en/nevibecode/skills/code-refactoring-tech-debt.md) — skill · 2 installs
- [refactoring_specialist](https://affpapa.org/en/nevibecode/agents/agenticorglab-refactoring-specialist.md) — subagent · ★ 776 repo stars
- [do-in-parallel](https://affpapa.org/en/nevibecode/skills/do-in-parallel.md) — skill · 1300 installs
- [refactoring-specialist](https://affpapa.org/en/nevibecode/skills/refactoring-specialist.md) — skill · 757 installs

From the same set: [b-mendoza/agent-skills](https://affpapa.org/en/nevibecode/by/b-mendoza/agent-skills.md) — 12 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
