tools-only Skill Auditor
Comprehensive assessment of your skill ecosystem with actionable recommendations.
Workflow
Phase 1: Inventory
Gather all skills from:
- Global skills:
~/.claude/skills/*/SKILL.md - Project skills:
./skills/*/SKILL.mdor./.claude/skills/*/SKILL.md
For each skill, extract:
- Name and description from frontmatter
- Line count of SKILL.md
- Presence of reference files, scripts, assets
- Any non-standard frontmatter fields
Phase 2: Individual Assessment
Evaluate each skill against these criteria:
Frontmatter Quality
| Criterion | Check |
|---|---|
| Description completeness | Does it explain both WHAT and WHEN? |
| Trigger coverage | Are all reasonable trigger phrases included? |
| Description length | Sufficient detail without being excessive (50-300 words ideal) |
| Non-standard fields | Any fields beyond name/description? (often unnecessary) |
Content Quality
| Criterion | Check |
|---|---|
| Line count | Under 500 lines? (Over suggests need for reference split) |
| Progressive disclosure | Does it use reference files for detailed content? |
| Actionability | Are instructions concrete and procedural? |
| Output contracts | Does it specify expected output format? |
| Examples | Does it include good/bad examples where helpful? |
Structure Quality
| Criterion | Check |
|---|---|
| Reference organization | Are references in references/ directory? |
| Script availability | Are reusable operations scripted? |
| Internal links | Are reference files linked from SKILL.md? |
| Naming consistency | Do file names follow conventions? |
Phase 3: Ecosystem Assessment
Evaluate the skill collection as a whole:
Coverage Analysis
- Domain clusters: What areas do skills cover? Any gaps?
- Overlap detection: Do multiple skills cover similar territory?
- Workflow completeness: Can common tasks be handled end-to-end?
Consistency Analysis
- Style uniformity: Do skills use consistent formatting?
- Trigger pattern consistency: Are similar skills triggered similarly?
- Output format consistency: Do related skills produce compatible outputs?
Organization Analysis
- Global vs project split: Are skills appropriately scoped?
- Naming conventions: Are names consistent and discoverable?
- Documentation quality: Is the overall system documented?
Phase 4: Generate Report
Output Format
# Skill Ecosystem Audit
**Generated**: [timestamp]
**Skills audited**: [count] global, [count] project-level
## Executive Summary
[2-3 sentences: overall health, biggest opportunities, critical issues if any]
**Health Score**: [X/100]
## Quick Stats
| Metric | Value | Assessment |
|--------|-------|------------|
| Total skills | [n] | — |
| Avg SKILL.md lines | [n] | [Good/High/Concerning] |
| Skills over 500 lines | [n] | [Needs attention if >0] |
| Skills with references | [n]% | [Good if >30%] |
| Skills with scripts | [n]% | — |
| Duplicate coverage areas | [n] | [Needs review if >0] |
## Top Recommendations
### Priority 1: [Most impactful improvement]
[Specific action with affected skills]
### Priority 2: [Second improvement]
[Specific action with affected skills]
### Priority 3: [Third improvement]
[Specific action with affected skills]
## Individual Skill Assessments
### [skill-name] — [Grade: A/B/C/D]
**Strengths:**
- [What works well]
**Issues:**
- [Specific problem] → [Specific fix]
**Quick wins:**
- [ ] [Actionable improvement]
[Repeat for each skill, ordered by grade (worst first for attention)]
## Domain Coverage Map
| Domain | Skills | Coverage |
|--------|--------|----------|
| [e.g., Design] | [list] | [Complete/Partial/Gap] |
| [e.g., Code Quality] | [list] | [Complete/Partial/Gap] |
## Overlap Analysis
[If overlaps exist, describe which skills overlap and recommend consolidation]
## Ecosystem Recommendations
### Organization
- [Recommendations for how skills are organized]
### Consistency
- [Recommendations for standardizing across skills]
### Missing Skills
- [Suggestions for skills that would complement the ecosystem]
Grading Rubric
Individual Skills
| Grade | Criteria |
|---|---|
| A | Clear triggers, concise content (<300 lines), uses references appropriately, has output contract, well-organized |
| B | Good triggers, reasonable length, mostly organized, minor improvements possible |
| C | Triggers could be better, content somewhat long, organization issues, needs work |
| D | Weak triggers, bloated content (>500 lines), poor organization, significant rewrite needed |
Ecosystem Health Score
Calculate from:
- Average individual grade (40%)
- Coverage breadth without overlap (20%)
- Consistency across skills (20%)
- Progressive disclosure usage (10%)
- Script/automation presence (10%)
Common Issues & Fixes
"Description doesn't include trigger phrases"
Fix: Add explicit "Use when..." phrases that match how users actually invoke the skill.
"SKILL.md over 500 lines"
Fix: Move detailed content to references/ files. Keep only workflow and essential quick-reference in SKILL.md.
"No output contract"
Fix: Add a section specifying what format the skill's output should take.
"Duplicate coverage with [other-skill]"
Fix: Either consolidate into one skill, or clearly differentiate triggers so they don't compete.
"Missing reference links"
Fix: If references exist, link them from SKILL.md with guidance on when to load each.
"Non-standard frontmatter fields"
Fix: Remove fields beyond name and description unless specifically needed for skill behavior (rare).
Proactive Recommendations
Based on common skill ecosystem patterns, also check for:
- Missing meta-skill: Is there a skill for creating/improving skills? (skill-creator)
- Missing checkpoint skill: Is there a way to pause and assess? (checkpoint)
- Missing handoff skill: Can sessions be continued? (bootstrap)
- Missing review skills: Are there skills for quality gates? (code review, design critique)
Running the Audit
Quick audit (overview only)
# Count skills and sizes
find ~/.claude/skills -name "SKILL.md" -exec wc -l {} \; | sort -n
find ./skills -name "SKILL.md" -exec wc -l {} \; 2>/dev/null | sort -n
Full audit
- Inventory all skills
- Read each SKILL.md frontmatter and assess
- Check for reference/script directories
- Compile findings into report format above
When to Audit
- After adding several new skills: Check for overlap and consistency
- Periodically (quarterly): Ensure ecosystem stays healthy
- Before sharing skills: Verify quality before distribution
- When skills feel ineffective: Diagnose what's not working