A portable Agent Skill for aggressively cleaning, simplifying, and restructuring existing codebases for experienced human engineers.
It is designed to remove:
- AI-generated code slop
- unnecessary abstractions
- excessive indirection
- duplicated logic
- dead code
- artificial fragmentation
- vague architecture
- pointless wrappers
- excessive defensive code
- type-system overengineering
- comment and logging spam
while preserving intended application behavior.
This skill does not try to make code "look human."
It makes code understandable by humans.
The standard is simple:
Another experienced engineer should be able to open the repository, understand the architecture, trace the important behavior, and safely modify the code without needing an AI assistant to explain every subsystem.
The skill instructs an AI coding agent to:
- Inspect the repository broadly.
- Reconstruct the actual architecture.
- Trace important execution paths.
- Identify unnecessary complexity.
- Identify common AI-generated coding patterns.
- Find duplication and dead code.
- Improve module boundaries.
- Simplify unnecessary abstractions.
- Improve naming where it materially improves comprehension.
- Refactor incrementally.
- Preserve intended behavior.
- Run the project's existing validation tools.
- Perform a final maintainability audit.
It does not blindly rewrite a repository.
It does not redesign a product simply because the existing implementation is unfamiliar.
It does not introduce abstractions just to make code appear architecturally sophisticated.
It does not worship DRY.
It does not optimize for minimum line count.
It does not replace one kind of AI slop with another.
This repository follows the portable Agent Skills format.
skills/
└── senior-codebase-cleanup/
└── SKILL.md
The SKILL.md file contains the skill metadata and instructions.
Compatible agents can discover or load the skill according to their own supported skill installation mechanism.
The skill is intentionally written without vendor-specific instructions.
It is intended for Agent Skills-compatible coding agents such as:
- Claude Code
- OpenAI Codex
- Gemini CLI
- Cursor
- GitHub Copilot
- other agents supporting the
SKILL.mdAgent Skills format
Individual agents may use different directories or installation commands for discovering skills.
Once installed into a compatible coding agent, invoke it when a repository needs serious cleanup or structural refactoring.
Example requests:
Clean up this entire codebase using the senior-codebase-cleanup skill.
Remove the AI-generated slop and unnecessary abstractions.
Go through the repository and restructure it so experienced engineers can maintain it.
Do a senior-level maintainability pass over the entire project.
The agent should inspect the repository before making substantial changes.
The skill prefers:
simple over clever
explicit over magical
cohesive over fragmented
direct over unnecessarily abstract
understandable over impressive
boring over complicated
Good software does not need to look sophisticated.
It needs to make sense.
This skill is designed for existing software repositories where maintainability matters.
It is particularly useful after:
- heavy AI-assisted development
- rapid prototyping
- multiple developers working independently
- rushed feature development
- large-scale generated code
- long-lived projects that accumulated abstractions
MIT