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:

bash

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:

bash

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

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:

bash

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:

Present a table with skill name, location, version, and description excerpt
Show the similarity score between descriptions
Explain why they were flagged (same name or similar description)
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):

bash

rm {symlink_path}

Directory removal:

bash

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.

skill-inventory-auditor

NPX Install

Tags

SKILL.md Content

Skill Inventory Auditor

Repo Sync Before Edits (mandatory)

Workflow

Phase 1: Scan

Phase 2: Report Duplicates

Phase 3: Remove Duplicates

Expected Output

Edge Cases

Acceptance Criteria

Step Completion Reports

Phase-specific checks

Important Notes