English | 中文

code-hygiene-skills

A collection of agent skills for cleaning up codebase drift — stale comments and tests, duplicate code, and inconsistent imports.

Every skill in this repo enforces a two-phase workflow: produce a prioritized inventory first, then batch-execute by priority. The key insight across all of them is that analysis and execution are separate steps with different failure modes — do not merge them.

Install

npx skills add niuma996/code-hygiene-skills

Or install to a specific agent:

npx skills add niuma996/code-hygiene-skills -a claude-code

Available Skills

cleanup-stale-code

A two-phase workflow (inventory → execute) for cleaning stale comments and tests. Forces category discipline so the agent doesn't invent new cleanup categories mid-task, and decouples analysis from editing so a typo in the inventory doesn't become a file delete.

Use when:

• "stale comments", "comment cleanup", "remove migration notes"
• "test cleanup", "delete test cases", "evaluate tests", "remove dead tests"
• The codebase has accumulated phased implementation markers (Phase 0:, TODO, etc.), obvious-code comments, visual dividers, or failing tests, deprecated-API regression tests, and mock-path style debt over many iterations

What it covers:

• Section A — Cleaning Comments: 5 default categories (expired, deprecated, inaccurate, low-value, migration-era); anchor-grep search; phased execution by priority P0–P3; dead-code check after cleanup
• Section B — Cleaning Tests: 4 default categories (expired, deprecated, low-value, useless); test-suite baseline before/after; mock-path style debt fix; deprecated-API regression test deletion; source-side dead-code follow-up proposal

Skip when:

• Adding new doc comments or improving comment style
• Adding new test coverage
• Auditing a single file manually
• Change is ≤3 lines (do it inline)

find-duplication

A two-phase workflow (detect → decide → execute) for finding duplicate and near-duplicate code ("clones") and producing a merge plan. Default mode is LLM-driven (anchor-grep + structured reading); tool-driven mode is opt-in for token-level precision on large codebases.

Use when:

• "find duplication", "deduplicate code", "DRY violations", "repeated code", "clone code"
• The codebase has accumulated copy-pasted helpers, copy-pasted try/catch wrappers, or structurally similar functions across modules
• Code review surfaces "this is the same as <other-file>" comments

What it covers:

• Two detection modes: LLM (default, anchor-grep) and Tool (opt-in, jscpd/copydetect/pmd-cpd/lizard)
• Clone-family inventory: groups copies into families; each row carries drift classification (none / minor / structural)
• Four merge strategies: extract helper / parameterize / delete dead copy / keep all
• Priority P0–P3: P0 = identical ≥ 10 lines, zero drift; P3 = similar intent, different implementation (keep)
• Second-order cleanup hook: after merging, run cleanup-stale-code on the new shared module's comments and tests

Skip when:

• Refactoring a single function
• Third-party / vendor / generated code
• Type-only duplication (usually a structural-typing feature, not a bug)
• Change is ≤3 lines (do it inline)

consolidate-imports

A report-only workflow for auditing import statements and surfacing style inconsistencies. Does NOT auto-rewrite, because the target style is project-specific (path aliases, grouping, extensions, ordering).

Use when:

• "consolidate imports", "normalize imports", "check import style", "fix import paths"
• "unify alias usage" — some files use @/foo, others use ../../foo
• "audit imports" — a sweep before a refactor or before a formatter migration
• The project has accumulated mixed import styles across iterations

What it covers:

• Five target-style axes: path aliases, grouping, extensions, style, re-exports — read from tsconfig.paths / eslint-plugin-import / .editorconfig first, ask the user for the rest
• Eight anchor patterns: relative-when-aliased / mixed-extension / wildcard / default+named / unused / duplicate / side-effect-mixing / inconsistent-ordering
• Per-finding inventory: each row carries current/target/category/priority/diff
• Priority P0–P3: P0 = duplicate or unused (safe wins); P1 = mechanical alias/extension fix; P3 = ordering preference (skip)
• Report deliverable: file-by-file markdown with ready-to-apply unified diffs for P0/P1; user applies

Skip when:

• Adding new import statements (this is for auditing existing ones)
• Changing import behavior (default vs. named exports) — that's a refactor, not a style fix
• Re-export aggregator files where diverse import patterns are intentional
• Generated / vendor / third-party code
• Change is ≤3 lines (do it inline)

Repository Structure

.
├── AGENTS.md                 # guidance for AI agents contributing to this repo
├── README.md                 # this file
├── LICENSE
├── skills.sh.json            # skills.sh metadata + grouping
└── skills/
    ├── cleanup-stale-code/   # Section A (comments) + Section B (tests)
    │   └── SKILL.md
    ├── find-duplication/     # Detect → Decide → Execute
    │   └── SKILL.md
    └── consolidate-imports/  # Report-only; user applies
        └── SKILL.md

This layout follows the Agent Skills format and is installable via npx skills. See AGENTS.md for the repo-level contribution guide.

How the Skills Relate

                 ┌──────────────────────┐
                 │   cleanup-stale-code │  comments + tests (subtract drift)
                 └──────────────────────┘
                            ▲
   ┌────────────────────────┴────────────────────────┐
   │                                                  │
┌─────────────────┐                       ┌──────────────────────┐
│ find-duplication│                       │ consolidate-imports  │
│   (clone code)  │                       │  (audit + report)    │
└─────────────────┘                       └──────────────────────┘
   extract shared helper                       user applies diffs
   after dedup → re-run                        → may reveal dup
   cleanup-stale-code on                       modules → run
   the new shared module                        find-duplication

A typical sequence:

1. Run cleanup-stale-code first — comments and tests are the lowest-risk wins and often reveal follow-up opportunities.
2. Run consolidate-imports next — the report surfaces import-style debt that should be fixed before refactors, so subsequent reads are clean.
3. Run find-duplication last — once the surface is clean, the duplication inventory is smaller and the merge targets are more obvious.
4. Loop back to cleanup-stale-code if any of the above exposed new stale comments or dead tests.

License

MIT — see LICENSE.