Agent skill
code-cleanup
Dead code detection and removal using knip (recommended) or standard tooling. Use when removing unused imports, variables, or dead files.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/code-cleanup
SKILL.md
SKILL: Code Cleanup
Purpose: Dead code detection and removal using knip (recommended) or ESLint/TypeScript fallback Target: Coder Agent, cleanup commands
⚠️ EXECUTION DIRECTIVE
IMPORTANT: Execute ALL steps IMMEDIATELY and AUTOMATICALLY.
Core Philosophy: Auto-apply Low/Medium risk | High-risk: User confirmation | Safe flags: --dry-run, --apply | Verification after each batch
Quick Start
When to Use This Skill
- Remove unused import statements
- Detect and delete dead files (zero references)
- Clean up codebase after refactoring
Usage
MODE="${1:-files}" # imports|files|all
SCOPE="${2:-repo}" # repo|path=...
.cleanup-ignore Support
Create .cleanup-ignore file in project root:
# Core infrastructure
**/auth/**
**/database/**
**/*.config.*
# Entry points
**/index.ts
**/main.ts
# Generated files
**/generated/**
**/*.gen.ts
Loading order: Read .cleanup-ignore → Apply patterns → Exclude protected files
Step 1: Detect Dead Code
Detection Tools
Recommended: knip
npx knip # Full analysis
npx knip --reporter compact # Concise output
npx knip --fix # Auto-fix safe issues
Fallback: Standard tooling
grep -r "import.*from" src/ --include="*.ts" # Unused imports
find src/ -name "*.ts" -exec grep -l "{}" \; # Dead files
Dead File Detection Procedure
EXCLUDE="--glob '!*.test.ts' --glob '!*.spec.ts' --glob '!index.ts'"
rg --files $EXCLUDE src/ | while read file; do
refs=$(rg -c "from.*['\"]$file" src/ || echo 0)
[ "$refs" -eq 0 ] && echo "$file: 0 references"
done
Step 2: Risk Classification (4-Level)
| Risk | File Types | Action |
|---|---|---|
| SAFE | Tests (*.test.*), mocks, fixtures |
auto-remove |
| CAUTION | Utils, helpers, internal modules | auto-remove + prompt |
| WARNING | Components, services, hooks | tests pass first |
| DANGER | Auth, database, config, API routes | require --force |
classify_risk() {
case "$1" in
*.test.* | *.spec.* | */__mocks__/*) echo "SAFE" ;;
*/utils/* | */helpers/* | */lib/*) echo "CAUTION" ;;
*/components/* | */services/* | */hooks/*) echo "WARNING" ;;
*/auth/* | */database/* | *.config.* | */api/*) echo "DANGER" ;;
*) echo "CAUTION" ;;
esac
}
Step 3: Cleanup with Confirmation
detect_dead_files() {
rg --files --glob '!*.test.ts' src/ | while read file; do
refs=$(rg -c "from.*['\"]$file" src/ || echo 0)
[ "$refs" -eq 0 ] && echo "$file|$(classify_risk "$file")"
done
}
# Auto-apply SAFE/CAUTION/WARNING, confirm DANGER
detect_dead_files | while IFS='|' read -r file risk; do
if [ "$risk" = "DANGER" ]; then
echo "DANGER: $file [A) Delete / B) Skip]"
read -p "Choose: " choice
[ "$choice" = "A" ] && rm "$file"
else
echo "Auto-deleting: $file" && rm "$file"
fi
done
Step 4: Verification
npm test || { echo "❌ Tests failed"; git checkout -- .; exit 1; }
npm run type-check || { echo "❌ Type check failed"; git checkout -- .; exit 1; }
npm run lint || { echo "❌ Lint failed"; git checkout -- .; exit 1; }
echo "✅ All checks passed"
Rollback on failure: git checkout -- .
Step 5: Execution Logging
mkdir -p .cleanup
LOG_FILE=".cleanup/$(date +%Y-%m-%d_%H%M%S).log"
if [ "$DELETED_COUNT" -gt 0 ]; then
echo "# Cleanup Log - $(date +%Y-%m-%d)" > "$LOG_FILE"
echo "## Deleted: $DELETED_COUNT files" >> "$LOG_FILE"
echo "✓ Log saved: $LOG_FILE"
fi
stdout: ✅ Cleanup Complete - Deleted: 5 files, Tests: PASS
Parallel Detection (Optional)
Task A: npx knip --reporter json
Task B: eslint . --report-unused-disable-directives --format json
Task C: tsc --noUnusedLocals --noEmit 2>&1
# Merge: Deduplicate → Apply .cleanup-ignore → Classify by risk
Safe: All detection commands are read-only.
Pre-flight Safety
[ -n "$(git status --porcelain)" ] && { echo "⚠️ Working directory not clean"; exit 2; }
Troubleshooting
False Positives: Dynamic imports, runtime requires | Test Failures: git checkout -- .
Best Practices
- Run tests after each batch: Max 10 deletions per batch | Conservative exclusion: Exclude index., main., .config. | Risk-based approach: Auto-apply Low/Medium, confirm High | Clean working directory: Block if modified/staged files exist
Further Reading
Internal: @.claude/skills/code-cleanup/REFERENCE.md | @.claude/skills/vibe-coding/SKILL.md
External: ESLint Unused Vars Rule | knip | ⚠️ SAFETY: Auto-rollback on verification failure
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?