---
name: audit-local-skills
description: Audits the user's local skill collection (personal + plugin + project) for redundancy, broken descriptions, missing `paths` filters, skill bloat, and outdated components. Reports issues color-coded (red = must fix, yellow = recommendation, green = OK). Periodic use (monthly) or right after adding new plugins.
when_to_use: |
  Manual / scheduled. Invocable directly:
  "/maxvision-orchestration:audit-local-skills",
  "audite minhas skills",
  "show skills not used in 90+ days".
disable-model-invocation: true
allowed-tools: Read Grep Glob Bash(ls *) Bash(find *) Bash(jq *) Bash(cat *) Bash(date *) Bash(wc *)
---

# Audit local skills

No arguments expected. Runs read-only inventory and analysis.

## Workflow

### 1. Inventory

```bash
PERSONAL=~/.claude/skills/
PLUGIN_CACHE=~/.claude/plugins/cache/
PROJECT_LOCAL=./.claude/skills/

ls -1 "$PERSONAL" 2>/dev/null > /tmp/maxv-personal.txt
find "$PLUGIN_CACHE" -mindepth 4 -maxdepth 4 -type d -path '*/skills/*' 2>/dev/null > /tmp/maxv-plugin.txt
ls -1 "$PROJECT_LOCAL" 2>/dev/null > /tmp/maxv-project.txt
```

Count each scope and report.

### 2. Description quality check

For each `SKILL.md` found, parse YAML frontmatter and check:

- `description` < 80 chars → ⚠ "discovery risk: too short"
- `description` + `when_to_use` combined > 1.500 chars → ⚠ "approaching 1.536-char per-skill cap"
- Missing `description` field → 🔴 "skill cannot be auto-discovered"
- Missing `paths` field on a domain-specific skill (heuristic: name contains "react", "supabase", "n8n", "test" but no `paths` filter) → ⚠ "consider adding paths to reduce budget pressure"

### 3. Redundancy / overlap

Look for skills with similar names or descriptions across scopes:

- Duplicates: same skill name in 2+ scopes (precedence: enterprise > personal > project, plugins use namespace).
- Description similarity: tokenize descriptions, flag pairs with Jaccard similarity > 0.7.

### 4. Origin tracking (.maxv-source.json)

For skills under `~/.claude/skills/` that have `.maxv-source.json`:

- Report the source repo, commit_sha, last_check date.
- Flag entries where `last_check` is > 90 days old as "stale-tracking".

### 5. Description budget estimate

```bash
TOTAL_CHARS=$(find ~/.claude/skills ~/.claude/plugins/cache -name SKILL.md -exec awk '/^---$/{c++} c==1 && /^description:/{print substr($0, 13)}' {} \; | wc -c)
BUDGET=${SLASH_COMMAND_TOOL_CHAR_BUDGET:-8000}
```

Report `<used>/<budget> chars (<percent>%)`. Flag red if > 90%, yellow if > 75%.

### 6. Plugin enabled vs used

Read `~/.claude/settings.json` → `enabledPlugins`. For each `<plugin>@<marketplace>: true`, check if any skill from that plugin appears in:

- `~/.claude/projects/*/sessions/` (last 30 days of session transcripts) → if not found, flag as "enabled but unused".

(Note: this is best-effort. Session transcripts may be compressed.)

### 7. Tier 4 audit

Scan installed skills for any that match tier_4 catalog entries (`alirezarezvani/claude-skills`). If full plugin is installed (vs cherry-pick), warn about budget impact.

## Output format

```markdown
# Audit Report — 2026-04-28

## Inventory
- Personal skills:    12
- Plugin skills:      94
- Project skills:     3
- Total SKILL.md:     109

## 🔴 Must fix (3)
1. `~/.claude/skills/old-deploy-skill/SKILL.md`: missing `description` field
2. `voltagent-domains:wordpress-master`: description 2.100 chars (exceeds 1.536 cap, will be truncated)
3. Description budget: 9.200 / 8.000 chars (115%) — set `SLASH_COMMAND_TOOL_CHAR_BUDGET=24000`

## ⚠ Recommendations (8)
1. `n8n-skills:n8n-workflow-patterns`: consider `paths: ["**/n8n-workflows/**"]` to reduce budget pressure
2. `~/.claude/skills/legacy-helper/`: tracked source last checked 142 days ago — run `update-component`
3. ...

## ✓ Healthy (98)
(skills below threshold for warnings — list available with --verbose)

## Plugin usage
- Enabled plugins: 50
- Unused (last 30d): 7 (`legal`, `brand-voice`, `enterprise-search`, `cowork-plugin-management`, ...)
- Suggestion: review `~/.claude/settings.json` → `enabledPlugins` to disable unused

## Tier 4 status
- `alirezarezvani/claude-skills`: not installed ✓
```

## Guardrails

- **Read-only.** This skill never modifies any file.
- **Never auto-disable plugins.** Always report and let the user decide.
- **Tokenization for similarity is a heuristic** — false positives expected. User must validate before acting on overlap warnings.
- **`enabledPlugins` analysis requires session history.** If `~/.claude/projects/*/sessions/` is gitignored or empty, skip that section gracefully.