luongnv89/skill-inventory-auditor

Skill Inventory Auditor

Find and remove duplicate skills across installed skill directories.

Repo Sync Before Edits (mandatory)

Before removing skills from git-tracked directories, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

Phase 1: Scan

Run the duplicate scanner with scope both (default) unless the user specifies otherwise:

python3 {SKILL_DIR}/scripts/scan_inventory.py --scope both --project-dir {cwd}

Scopes: global (~/.claude/skills/, ~/.agents/skills/), project (.claude/skills/), or both.

Parse the JSON output. If the script fails, report the error and stop.

Phase 2: Report Duplicates

If no duplicates are found, say so and stop.

For each duplicate group:

1. Present a table with skill name, location, version, and description excerpt
2. Show the similarity score between descriptions
3. Explain why they were flagged (same name or similar description)
4. Recommend which to keep based on:
   • Higher version number
   • More descriptive name
   • Richer feature set (more scripts/files)
   • Location preference (project-local skills may override global)

Ask the user which skills to keep/remove for each group. Wait for confirmation.

Phase 3: Remove Duplicates

Present a summary of planned removals, then ask for confirmation.

Symlink removal (preserves the source):

rm {symlink_path}

Directory removal:

rm -rf {directory_path}

Safety rules:

• Always confirm before executing removals
• Print exactly what will be deleted
• Never remove skills from the project source repository (e.g., skills/ in a git repo)
• When removing a symlink, only the link is deleted — the source remains intact

After removals, rerun the scanner to verify no duplicates remain.

Expected Output

After the audit completes, the skill presents:

Skill Inventory Audit — 2 duplicate group(s) found

Group 1: "release-manager"
| Location                          | Version | Description excerpt              |
|-----------------------------------|---------|----------------------------------|
| ~/.claude/skills/release-manager  | 2.3.1   | Automate the full release...     |
| .claude/skills/release-manager    | 2.1.0   | Complete release automation...   |
Recommendation: keep ~/.claude/skills/release-manager (higher version)
Similarity: exact name match

Removed: .claude/skills/release-manager
Rescan: 0 duplicates remaining.

Edge Cases

• Symlink pointing to the same source as another entry: Do not flag as a duplicate. The scanner excludes cross-linked entries that resolve to the same path; treat them as a single shared installation.
• Skill with no skill.md file: If a directory in a skills folder lacks a skill.md, skip it during scanning and report it separately as an unrecognized entry. Do not attempt to remove it automatically.
• Scanner script not found: If scripts/scan_inventory.py is missing (e.g., the skill was installed without its scripts), report the missing dependency and stop. Do not attempt to scan manually.

Acceptance Criteria

• [ ] All configured skill directories (global and project) are scanned
• [ ] Each duplicate group is presented with a table showing location, version, and description excerpt
• [ ] A keep/remove recommendation is provided for each group based on version and feature richness
• [ ] No skills are removed without explicit user confirmation
• [ ] Source repositories are never touched — only installed copies in ~/.claude/skills/, ~/.agents/skills/, or .claude/skills/ are eligible for removal
• [ ] A rescan is run after removals to confirm zero duplicates remain

Step Completion Reports

After completing each major step, output a status report in this format:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Adapt the check names to match what the step actually validates. Use √ for pass, × for fail, and — to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

Phase-specific checks

Phase 1 — Scan

◆ Scan (step 1 of 3 — inventory collection)
··································································
  Global skills scanned:    √ pass (~/.claude/skills/, ~/.agents/skills/)
  Project skills scanned:   √ pass (.claude/skills/)
  Duplicates identified:    √ pass (N duplicate groups found)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Phase 2 — Report

◆ Report (step 2 of 3 — findings presentation)
··································································
  Findings presented:       √ pass (table shown per duplicate group)
  Severity classified:      √ pass (exact name match | similar description)
  Removal plan ready:       √ pass (keep/remove recommendations made)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Phase 3 — Cleanup

◆ Cleanup (step 3 of 3 — duplicate removal)
··································································
  Duplicates removed:       √ pass (N skills removed)
  No side effects:          √ pass (source repos untouched)
  Inventory verified:       √ pass (rescan: 0 duplicates remaining)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Important Notes

• This skill only removes installed copies (in ~/.claude/skills/, ~/.agents/skills/, or .claude/skills/). It never touches source repositories.
• Symlinks between ~/.claude/skills/ and ~/.agents/skills/ pointing to the same target are shared installations, NOT duplicates. The scanner excludes these automatically.