Agent skill

Clean code,by the catalog.

Not by vibes. Teach your coding agent to refactor any codebase in safe, behavior-preserving steps.

guard-clauses.js

Before

function getPay(e) {
  if (e.isDead) {
    return dead();
  } else {
    if (e.isRetired) {
      return retired();
    } else {
      return normal(e);
    }
  }
}

After

function getPay(e) {
  if (e.isDead)    return dead();
  if (e.isRetired) return retired();
  return normal(e);
}

// flat happy path,
// same behavior.

The method

One loop, run on every cleanup

Refactoring is not rewriting. It is a sequence of tiny, behavior-preserving moves, each verified before the next. The skill never lets the agent skip the last two steps.

Detect

Name the specific smell, not just "this is ugly." Smells point to the fix.

Choose

Map that smell to a concrete technique from the catalog.

Step small

Make one tiny change that does not alter what the program does.

Re-run tests

After every step. A long red period means the step was too big.

Verify cleaner

If the result is not more readable than before, revert it.

What "clean" actually means

01
Obvious to a readerIntention-revealing names, no magic numbers, small methods. If it needs explaining, it is not clean.
02
Free of duplicationOne change should mean editing exactly one place.
03
MinimalThe fewest moving parts that solve the problem. Code is a liability, not an asset.
04
Tested and passingReliability is part of clean. "95% green" means dirty.
05
Cheap to changeThe payoff of the four above, and the only reason any of this matters.

Refactoring never changes what the program does. The moment behavior shifts, it is a feature or a bugfix: a separate commit, a separate review.

// the one rule the skill will not break

A diagnosis, then a fix

The catalog pairs every code smell with the techniques that treat it, so the agent works from evidence instead of taste. A sample of the mapping:

code smells, in 5 families

60+

refactoring techniques

technique families

steps in the loop

smell: Long Method

treated by

Extract Method

Group a fragment, name it for what it does, and the method reads like a short paragraph again.

smell: Switch Statements

treated by

Replace Conditional with Polymorphism

Move each branch onto a subclass. Adding a case becomes adding a class, not editing a switch.

smell: Duplicate Code

treated by

Extract Method, Pull Up, Form Template Method

Give each piece of knowledge a single home so one change never ripples across files.

The same behavior, easier to change

Extract Method

print-report.js

Before

function printReport(invoice) {
  printHeader();
  let total = 0;
  for (const line of invoice.lines)
    total += line.amount;
  log("name:", invoice.customer);
  log("total:", total);
}

After

function printReport(invoice) {
  printHeader();
  printDetails(invoice, totalOf(invoice));
}

function totalOf(invoice) {
  return invoice.lines
    .reduce((s, l) => s + l.amount, 0);
}

Replace Magic Number

pricing.js

Before

// what is 0.0825?
function total(subtotal) {
  return subtotal * 1.0825;
}

After

const SALES_TAX_RATE = 0.0825;

function total(subtotal) {
  return subtotal
    * (1 + SALES_TAX_RATE);
}

Install in one command

The skill is a folder of Markdown. Drop it into your agent's skills directory; no build step, no dependencies. The agent loads it when you ask to refactor or clean up code.

# global, all projects
git clone https://github.com/cskwork/clean-code-skill ~/.claude/skills/clean-code

# this project only
git clone https://github.com/cskwork/clean-code-skill .claude/skills/clean-code

Then run /clean-code, or just say "refactor this" and let the agent pick it up.