clean-code
Refactor legacy code for readability without changing behavior. Use when cleaning up or reducing technical debt.
Open source Open in the app JSON README (API)
About
Refactor legacy code for readability without changing behavior. Use when cleaning up or reducing technical debt.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- cskwork
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Last push
- 2026-08-21T14:39:34Z
- Repository state
- ativo
- Language
- HTML
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
cskwork/clean-code
README
<p align="center"><img src="logo.png" width="120" alt="logo" /></p>
# 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:
```text
<repository>/.agents/skills/clean-code/
```
### Codex user scope
Copy the folder to:
```text
$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:
```text
$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
```text
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:
```bash
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](REFERENCES.md) for the source material that informed the workflow.