Skill cleanup

Skill Cleanup

Audit tool. Never delete anything without explicit user confirmation per item.

---

Quick start — interactive TUI tool

The fastest path. Run the bundled script for a multi-select TUI that scans all platforms and removes in one flow:

# First-time setup (once per machine)
cd <skills-dir>/skill-cleanup && npm install

# Run the interactive cleanup tool
node scripts/cleanup.mjs

# Preview only — no files removed
node scripts/cleanup.mjs --dry-run

The tool:

1. Scans all installed agent platforms (Claude Code, Kiro, Codex, Windsurf, Gemini, Pi, and more)
2. Pre-selects stale entries (renamed originals, artifacts, orphaned installs)
3. Shows a multi-select checklist — toggle any skill, select all with a
4. Asks for final confirmation before removing anything
5. Removes platform copies first, central store last

Use the manual flow below if you prefer guided step-by-step or need to inspect specific entries.

---

Phase 1 — Detect OS and home directory

Run the appropriate probe:

macOS / Linux:

echo "OS: $(uname -s)"
echo "HOME: $HOME"

Windows (PowerShell):

echo "OS: Windows"
echo "HOME: $env:USERPROFILE"

Use the detected home directory for all paths below. On Windows substitute \ for / throughout.

---

Phase 2 — Scan installed locations

Run each command that applies (skip if directory does not exist):

# Central store — source of truth
ls ~/.agents/skills/

# Symlink platforms (point into central store)
ls ~/.claude/skills/          # Claude Code
ls ~/.kiro/skills/            # Kiro CLI
ls ~/.pi/agent/skills/        # Pi
ls ~/.kilocode/skills/        # Kilo Code
ls ~/.qwen/skills/            # Qwen Code

# Copy platforms (independent copies — not symlinks)
ls ~/.codex/skills/           # Codex
ls ~/.codeium/windsurf/skills/ # Windsurf
ls ~/.gemini/config/skills/   # Gemini CLI

See PLATFORMS.md for exact paths per OS and notes on each platform's install type.

Build two inventories:

• Central store list — what ~/.agents/skills/ contains
• Platform lists — what each platform dir contains

---

Phase 3 — Flag stale entries

Compare inventories. Flag an entry as stale when ANY signal is true:

Signal	Stale type
Name matches a known renamed skill AND the replacement is also in central store	Renamed original
Two entries where one is clearly the predecessor (e.g. foo and foo-v2, bar and bar-old)	Duplicate
Entry present in a platform dir but absent from central store	Orphaned platform entry
Entry in central store but absent from ALL platform dirs	Orphaned install (no platform linked)
.zip suffix, -workspace suffix, or -backup suffix	Install artifact
Symlink in a symlink-platform dir whose target path does not resolve	Broken symlink

Also check ~/.claude/settings.json (or equivalent) for plugins entries whose repo or skill name no longer matches what is installed.

---

Phase 4 — Interactive selection

If no stale entries found: state "All installed skills look clean." and stop.

If stale entries found, call AskUserQuestion with multiSelect: true:

• One option per unique skill name (not per platform entry)
• label: skill-name [Platform1, Platform2, ...] listing every platform it appears in
• description: the stale reason — e.g. orphaned — not in central store or install artifact
• AskUserQuestion supports max 4 options per call — if more than 4 stale skills, chain a second call for the remainder
• Do NOT fall back to a text table — the checkbox selector is the required UI for this phase

The user's checked selections become the confirmed removal list for Phase 5.

---

Phase 5 — Remove confirmed entries

Use OS-correct commands. For each confirmed item:

macOS / Linux:

# Symlink entry (Claude Code, Kiro, Pi, Kilo Code, Qwen Code)
rm ~/.claude/skills/<name>

# Full directory (central store or copy platform)
rm -rf ~/.agents/skills/<name>
rm -rf ~/.codex/skills/<name>

Windows (PowerShell):

# Symlink / junction
Remove-Item -Force "$env:USERPROFILE\.claude\skills\<name>"

# Full directory
Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\<name>"
Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\skills\<name>"

Removal order: platform entries first, central store last.

After removal, re-run Phase 2 scans and confirm the entries are gone.

---

Gotchas

• Never remove the only installed version of a skill — if no replacement exists, keep it.
• Symlink platforms (~/.claude/, ~/.kiro/, ~/.pi/agent/, ~/.kilocode/, ~/.qwen/): entries are symlinks, rm without -rf is sufficient on macOS/Linux; Remove-Item -Force on Windows.
• Copy platforms (~/.codex/, ~/.codeium/windsurf/, ~/.gemini/config/): entries are full directory copies — remove from each platform dir independently, then from central store.
• Pi path is ~/.pi/agent/skills/, not ~/.pi/skills/ — the extra agent/ level is intentional.
• Gemini CLI may install under multiple subdirs (antigravity-backup/, antigravity-ide/, config/) — check all three.
• settings.json plugin entries: surface for human review only; do not auto-remove them.