How do I install the Codebase Cleanup skill?

Run npx skillmds@latest add darkmatter/codebase-cleanup in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Codebase Cleanup safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Codebase Cleanup?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Codebase Cleanup free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Codebase Cleanup?

darkmatter (@darkmatter) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Codebase Cleanup by darkmatter — Agent Skill

Name: Codebase Cleanup
Author: darkmatter

Codebase Cleanup

Multi-pass refactor / code-quality cleanup designed to be dispatched as 8 specialist subagents (one per cleanup concern), each running a research → critical-assessment → high-confidence-implementation cycle. Triggers on "clean up the codebase", "tech-debt pass", "refactor for quality", "find dead code", "remove AI slop", or any explicit request for a comprehensive quality sweep. Do NOT trigger for narrow targeted fixes ("remove this one function") or for net-new feature work.

darkmatter 439d87c 11 files · 41.3 KB Updated Sep 17, 2026

File contents

Codebase cleanup — 8-pass refactor

Eight independent specialist passes over a codebase, each scoped to one quality concern. Designed to be run as 8 separate subagent sessions (or sequentially in one) so each pass gets a clean context window and can't be tempted to bleed into another's territory.

Every pass follows the same three-phase protocol — see reference/protocol.md. The recommended pass ordering and why is in reference/pass-ordering.md.

When to use

"Clean up the codebase" / "do a tech-debt pass"
"Refactor for quality before we ship"
"Find and remove dead code / AI slop / weak types"
Onboarding a codebase and wanting to know what's actually load-bearing
Pre-1.0 / pre-release quality sweep
Periodic (quarterly) hygiene runs

When NOT to use

Narrow targeted asks ("remove this one function", "fix this one type")
Net-new feature work
Tight deadline / minimum-viable-fix scenarios — this is a deliberate, careful sweep
Codebases under active heavy refactor by humans (the passes will fight in-flight work)

The 8 passes

Run in this order (rationale in reference/pass-ordering.md). Each links to the full subagent prompt:

AI slop & stale comments → reference/passes/01-ai-slop.md Remove generated noise, in-motion-work comments, larp, unhelpful boilerplate.
Legacy / deprecated / fallback code → reference/passes/02-legacy-removal.md Remove dead branches, deprecated APIs, fallback paths that no longer fall back to anything live.
Unused code → reference/passes/03-unused-code.md knip-class analysis: exports/files/deps that nothing imports.
Circular dependencies → reference/passes/04-circular-deps.md madge-class analysis: untangle import cycles.
Weak types → reference/passes/05-weak-types.md Replace any / unknown / Object / dynamic / interface{} with real types backed by research.
Type consolidation → reference/passes/06-type-consolidation.md Find duplicated / near-duplicated type definitions and unify.
Defensive programming → reference/passes/07-defensive-programming.md Remove try/catch and null-guards that don't handle a real input boundary.
DRY / dedup → reference/passes/08-dry.md Consolidate duplicated logic only where it reduces complexity (not the other way).

Tools

Each pass spec lists the tooling it expects (knip, ts-unused-exports, madge, jscpd, language-specific linters, etc.). The skill ships no scripts — orchestration happens in the calling agent runtime, which already has bash/edit/grep/etc.

Reference

reference/protocol.md — the 3-phase research/assess/implement protocol every pass follows
reference/pass-ordering.md — why this order, and which passes can run in parallel
reference/passes/*.md — one self-contained subagent prompt per pass

---name: codebase-cleanupdescription: Multi-pass refactor / code-quality cleanup designed to be dispatched as 8 specialist subagents (one per cleanup concern), each running a research → critical-assessment → high-confidence-implementation cycle. Triggers on "clean up the codebase", "tech-debt pass", "refactor for quality", "find dead code", "remove AI slop", or any explicit request for a comprehensive quality sweep. Do NOT trigger for narrow targeted fixes ("remove this one function") or for net-new feature work.---# Codebase cleanup — 8-pass refactorEight independent specialist passes over a codebase, each scoped to one quality concern. Designed to be run as 8 separate subagent sessions (or sequentially in one) so each pass gets a clean context window and can't be tempted to bleed into another's territory.Every pass follows the same three-phase protocol — see `reference/protocol.md`. The recommended pass ordering and why is in `reference/pass-ordering.md`.## When to use- "Clean up the codebase" / "do a tech-debt pass"- "Refactor for quality before we ship"- "Find and remove dead code / AI slop / weak types"- Onboarding a codebase and wanting to know what's actually load-bearing- Pre-1.0 / pre-release quality sweep- Periodic (quarterly) hygiene runs## When NOT to use- Narrow targeted asks ("remove this one function", "fix this one type")- Net-new feature work- Tight deadline / minimum-viable-fix scenarios — this is a deliberate, careful sweep- Codebases under active heavy refactor by humans (the passes will fight in-flight work)## The 8 passesRun in this order (rationale in `reference/pass-ordering.md`). Each links to the full subagent prompt:1. **AI slop & stale comments** → `reference/passes/01-ai-slop.md` Remove generated noise, in-motion-work comments, larp, unhelpful boilerplate.2. **Legacy / deprecated / fallback code** → `reference/passes/02-legacy-removal.md` Remove dead branches, deprecated APIs, fallback paths that no longer fall back to anything live.3. **Unused code** → `reference/passes/03-unused-code.md` `knip`-class analysis: exports/files/deps that nothing imports.4. **Circular dependencies** → `reference/passes/04-circular-deps.md` `madge`-class analysis: untangle import cycles.5. **Weak types** → `reference/passes/05-weak-types.md` Replace `any` / `unknown` / `Object` / `dynamic` / `interface{}` with real types backed by research.6. **Type consolidation** → `reference/passes/06-type-consolidation.md` Find duplicated / near-duplicated type definitions and unify.7. **Defensive programming** → `reference/passes/07-defensive-programming.md` Remove try/catch and null-guards that don't handle a real input boundary.8. **DRY / dedup** → `reference/passes/08-dry.md` Consolidate duplicated logic _only_ where it reduces complexity (not the other way).## ToolsEach pass spec lists the tooling it expects (knip, ts-unused-exports, madge, jscpd, language-specific linters, etc.). The skill ships no scripts — orchestration happens in the calling agent runtime, which already has bash/edit/grep/etc.## Reference- `reference/protocol.md` — the 3-phase research/assess/implement protocol every pass follows- `reference/pass-ordering.md` — why this order, and which passes can run in parallel- `reference/passes/*.md` — one self-contained subagent prompt per pass

Frequently asked questions