Skill Auditor
Workflow
Step 1: Discover All Skills
Scan these locations for SKILL.md files:
| Level | Path |
|---|---|
| Global | ~/.claude/skills/*/SKILL.md |
| Project | .claude/skills/*/SKILL.md |
| Plugin | plugins/*/skills/*/SKILL.md |
For each skill found, collect:
- Name: from frontmatter
name:field (fall back to directory name) - Level: global / project / plugin (include plugin name for plugin skills)
- Lines: total line count of
SKILL.md - Has allowed-tools: yes/no
- Description length: character count of
description:field
Step 2: Present Summary Table
Sort by line count descending. Format:
| # | Level | Plugin | Skill Name | Lines | Status |Status indicators:
OVER— exceeds 500-line limitHEAVY— 300-499 lines (approaching limit)OK— under 300 lines
Include totals:
- Total skills per level
- Total lines across all skills
- Average lines per skill
- Skills exceeding limits
Step 3: Ask User for Selection
Use AskUserQuestion to ask which skills to review. Suggest:
- All skills marked OVER or HEAVY
- Top 5 largest skills by line count
- Option to review by plugin name
- Option to review all skills at a specific level
Step 4: Deep Review (per selected skill)
Read each selected skill fully. Evaluate against these criteria:
Conciseness (token efficiency)
- Lines that don't change LLM behavior (fluff, attribution, personas)
- Redundant explanations of concepts Claude already knows
- Verbose examples that could be compressed
- Sections that repeat CLAUDE.md rules
Clarity
- Ambiguous instructions that could be interpreted multiple ways
- Missing context that forces Claude to guess
- Inconsistent terminology within the skill
Scope Overlap
- Compare skill's purpose against other skills at same level
- Flag skills that cover substantially similar ground
- Identify candidates for merging or splitting
Structure
- Frontmatter completeness (name, description, allowed-tools)
- Description quality (too short = undiscoverable, too long = wasteful)
- Section organization (follows marketplace conventions?)
Step 5: Report Findings
For each reviewed skill, output:
## {skill-name} ({lines} lines)
**Verdict:** {TRIM | RESTRUCTURE | MERGE | OK}
**Issues:**
- [CONCISENESS] {specific finding with line reference}
- [CLARITY] {specific finding}
- [OVERLAP] overlaps with {other-skill}: {shared scope}
**Suggested savings:** ~{N} lines ({percentage}% reduction)
**Recommended actions:**
1. {specific action}
2. {specific action}Step 6: Summary
After all reviews, provide:
- Total potential line savings
- Skills recommended for merging (with rationale)
- Priority order for improvements (highest token savings first)