# Codebase Refactoring

Three-part workflow to improve overall codebase health with jscpd, find and fix...

- Repository: https://github.com/kucherenko/jscpd (6480 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kucherenko/jscpd --skill codebase-refactoring -g -a claude-code -y`
Codex: `npx skills add kucherenko/jscpd --skill codebase-refactoring -g -a codex -y`
Cursor: `npx skills add kucherenko/jscpd --skill codebase-refactoring -g -a cursor -y`
Gemini CLI: `npx skills add kucherenko/jscpd --skill codebase-refactoring -g -a gemini-cli -y`

## Description

Three-part workflow to improve overall codebase health with jscpd, find and fix duplicated code, find and remove or refactor dead code, then find and simplify the largest/most complex files. Starts from --dashboard/--health to prioritize and ends by re-measuring the score.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# codebase-refactoring

A guided pass over a codebase's three biggest maintenance costs, duplicated
code, dead code, and complexity, using jscpd to find each and a strategy to
fix it. Use this skill when asked to "clean up", "improve", "refactor" or
"pay down tech debt in" a codebase, rather than to fix one specific bug.

## Start here: measure, then prioritize

```bash
npx jscpd --health --reporters ai <path>
```

```
health 74 B (duplication 75, dead-code 72, complexity 76; 93 code lines)
```

The health score is a weighted mix of three sub-scores, each a share of the
code lines, high is good, 100 is clean. The lowest of the three names where
the codebase actually hurts most; if it isn't the order below, do that
dimension first instead. `n/a` on a dimension (e.g. `dead code n/a`) means
jscpd could not measure it, dead-code detection needs JavaScript,
TypeScript or Python to be a real share of the code, skip that step rather
than treating it as clean.

For the full picture behind that score, largest duplicated formats, most
complex files, largest dead-code findings, all in one screen, run `npx
jscpd --dashboard` instead. Its `console` output (the default) is the only
reporter with that per-file detail; `--reporters ai` on `--dashboard` prints
the same one-line summary shown above, not the breakdown, so don't reach for
it expecting more than the score. Use `--reporters json` on `--dashboard` if
you need the detail in a parseable form.

The three passes below are otherwise independent and safe to run in any
order; **duplication → dead code → complexity** is the default because
fixing duplication first means step 2 isn't wasting effort tracing call
sites that a later extract-function pass will move anyway, and clearing
dead code before step 3 means the files ranked for simplification are ones
actually worth simplifying, not ones about to be deleted.

## Step 1, Duplicated code

```bash
npx jscpd --reporters ai --summary <path>
```

The rest: https://github.com/kucherenko/jscpd/blob/HEAD/skills/codebase-refactoring/SKILL.md