Skill Cleanup

Skill Cleanup

Companion to skill-usage-stats. Reads the same HTML report and archives skills marked DELETE (or matching user-chosen criteria) without deleting any files.

How archiving works

For each chosen skill directory:

1. Move it under ~/.claude/skills-archive/<source>/<skill-name>/ (or ~/.codex/skills-archive/...)
2. Inside the archived directory, rename SKILL.md → SKILL.md.archived so the harness no longer treats it as an active skill (the harness only auto-discovers SKILL.md).
3. Write a .archived-meta.json next to it recording original path, archive date, and the reason from the stats report.

Reverse: restore <name> moves it back and renames SKILL.md.archived → SKILL.md.

How to run

# 1. Generate fresh stats first
python3 ~/.claude/skills/skill-usage-stats/analyze.py --no-open

# 2. Dry-run (default) — print what would be archived
python3 ~/.claude/skills/skill-cleanup/archive.py

# 3. Apply
python3 ~/.claude/skills/skill-cleanup/archive.py --apply

# Useful flags
#   --verdict DELETE       only archive DELETE-classified skills (default)
#   --verdict DELETE,REVIEW
#   --days 90              also archive count>0 but stale >N days
#   --source claude-global only archive from one source
#   --dry-run              never actually move (default)

# Restore
python3 ~/.claude/skills/skill-cleanup/archive.py restore <name>
python3 ~/.claude/skills/skill-cleanup/archive.py list-archive

Safety

• Default mode is dry-run.
• Never deletes; archive is fully reversible.
• Skips any skill not in the stats report (so you can't accidentally archive an unscanned skill).
• Refuses to operate on plugin cache paths (~/.claude/plugins/cache/...) — those are managed by the plugin marketplace and a rename there would just be re-installed.