clean-code

A repository-aware agent skill for refactoring legacy code without casually changing its behavior.

Its enforced sequence is:

1. inspect the repository and record the baseline;
2. add retained characterization tests that pass on unchanged production code;
3. when the target is an API, resolve whether to preserve v1 in place or leave v1 untouched and add v2;
4. refactor in small verified batches;
5. report exact evidence and any remaining risk.

The skill deliberately prioritizes precise naming and locality. It does not equate clean code with more files, smaller methods, interfaces, patterns, or abstraction layers.

Install

Codex project scope

Copy the folder to:

<repository>/.agents/skills/clean-code/

Codex user scope

Copy the folder to:

$HOME/.agents/skills/clean-code/

Other Agent Skills-compatible clients

Place the complete clean-code directory in the client's configured skills directory. Keep SKILL.md at the root of the skill folder.

Invoke

Explicit invocation in Codex:

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

The description also supports implicit routing for requests about legacy cleanup, maintainability, naming, technical debt, and behavior-preserving refactoring.

Package contents

clean-code/
├── SKILL.md
├── README.md
├── REFERENCES.md
├── LICENSE
├── agents/
│   └── openai.yaml
├── references/
│   ├── api-versioning.md
│   ├── characterization-tests.md
│   ├── refactoring-heuristics.md
│   └── verification-and-reporting.md
├── evals/
│   ├── evals.json
│   └── trigger-queries.json
└── scripts/
    └── validate_skill.py

SKILL.md contains the mandatory workflow. Supporting references are loaded only when their step is reached, keeping the primary instructions focused.

Validate

From the skill directory:

python3 scripts/validate_skill.py

The validator checks frontmatter, naming, required files, local links, evaluation fixtures, and OpenAI metadata without third-party packages.

Core guarantees

• Production behavior is characterized before production edits.
• Characterization tests are retained as legacy regression tests.
• API versioning is an explicit decision gate after tests and before implementation.
• Side-by-side v2 work leaves v1 production files untouched.
• Refactoring and behavior changes remain separate.
• Names, cohesion, and local comprehension take priority over arbitrary size metrics.
• Verification results distinguish passing checks, pre-existing failures, new failures, and commands not run.

Non-goals

This skill is not primarily for:

• greenfield implementation;
• debugging a behavior defect;
• broad dependency upgrades;
• formatting-only changes;
• architecture diagrams or educational explanations;
• intentional breaking API migrations without a behavior-preserving refactor scope.

See REFERENCES.md for the source material that informed the workflow.