Skip to content

Agent Skill · v1.0.0 · MIT

Change the code.
Preserve the behavior.

A repository-aware agent skill that refactors legacy code behind retained characterization tests. It favors precise names and locality over abstraction — so every edit is evidence-backed, focused, and reversible.

Install the skill Read SKILL.md
codex — clean-code
$ clean-code Refactor the legacy order-pricing
        module without changing behavior.
 
# 1 · establishing boundary — tracing callers
# 2 · locking behavior with characterization tests
✓ 6 retained tests pass on unchanged code
# 4 · smallest useful refactor (rename + guard clauses)
✓ all characterization tests still green
 
Refactor complete. Behavior preserved.
7
Enforced workflow steps, each with completion criteria
0
Production changes allowed before tests pass
1
API versioning decision gate, asked once
MIT
Licensed, open, Agent Skills compatible

What it is

Refactoring, without the silent rewrite.

Most “clean code” efforts drift into rewrites — new files, interfaces, and patterns that change behavior in ways nobody asked for. Clean Code is an agent skill built on the opposite premise: behavior is characterized before it is touched, and every later edit is checked against that evidence.

It follows the Agent Skills open specification and runs wherever Codex or compatible clients do. The skill deliberately does not equate clean code with more methods, smaller functions, interfaces, or abstraction layers. A focused diff beats a broad refactor; a precise rename beats an extracted framework.

If a change isn't protected by a test, it doesn't ship.

Surprising legacy behavior is treated as legacy behavior, not a bug to quietly fix — preserved unless you explicitly authorize changing it. Verification reports distinguish what passed, what already failed, what newly failed, and what was never run. Nothing is overstated.

The enforced sequence

Seven steps. Every one gated.

The order is the safety. Tests before edits, versioning before implementation, verification before claims.

  1. 1

    Establish the refactoring boundary

    Read repo instructions, trace the full call path, discover the real test/lint/build commands, and record the baseline — including any tests that already fail.

  2. 2

    Lock current behavior with retained characterization tests

    Test through the most stable observable seam. Capture main paths, boundaries, errors, and legacy quirks. They must pass on the unchanged code before anything moves.

    ◆ Gate — no production diff yet
  3. 3

    Apply the API versioning gate

    For an externally consumed API, ask exactly one question: preserve v1 in place, or leave v1 untouched and add a side-by-side v2? Then stop until you answer.

    ◆ Decision gate — asked once
  4. 4

    Design the smallest useful refactor

    Plan rename → control flow → duplication → cohesion → extraction, in that order. Every new abstraction must justify itself against a concrete problem.

  5. 5

    Implement in small behavior-preserving batches

    One coherent transformation per batch. Run the narrow tests after each. Revert instantly if a previously green test surprises you.

  6. 6

    Verify the completed refactor

    Run every applicable check — tests, types, lint, build, security. Compare to baseline. Any new, unexplained failure blocks the claim of “done.”

  7. 7

    Report the result

    Scope, API strategy, retained tests, improvements, verification evidence, intentionally-preserved quirks, and unverified risks — separated as fact vs. assumption.

Core guarantees

What it will and won't do.

Behavior characterized first
Production behavior is locked by retained tests before any production edit.
Tests stay as regression tests
Characterization tests are kept permanently — never deleted or weakened after the refactor.
API versioning is explicit
An decision gate after tests and before implementation — not a silent contract change.
Side-by-side v2 is untouched v1
Under the v2 strategy, v1 production files are left alone even when sharing would be convenient.
Refactor ≠ behavior change
Never combined with a bug fix, feature, dependency bump, or formatting pass.
Locality over size metrics
Names, cohesion, and local comprehension win over arbitrary method or file counts.
Honest verification
Distinguishes passing, pre-existing failures, new failures, and commands not run.
No speculative architecture
No interfaces, factories, or extension points added for hypothetical future needs.

Install

One folder. Three ways in.

Place SKILL.md at the root of the skill folder. That's the whole install.

Get the skill
git clone https://github.com/cskwork/clean-code.git
cp -r clean-code <repo>/.agents/skills/clean-code
Codex · project scope
# travels with the repository
cp -r clean-code <repository>/.agents/skills/clean-code/
Codex · user scope
# available across every project
cp -r clean-code $HOME/.agents/skills/clean-code/

For other Agent Skills-compatible clients, place the complete clean-code directory in the client's configured skills directory.

Invoke

Ask plainly. Get evidence back.

Explicit invocation, or implicit routing on requests about legacy cleanup, technical debt, naming, and behavior-preserving refactors.

$clean-code Refactor the legacy order-pricing module without changing behavior.

See the sources that shaped the workflow →