Skill auditor

Skill Auditor

This skill audits other skills for quality, completeness, and adherence to best practices. It validates skill structure, evaluates content quality, and recommends improvements or decomposition into sub-skills.

When to Use

This skill should be triggered when:

• Reviewing existing skills for quality issues
• Checking if a skill follows proper formatting conventions
• Evaluating whether a skill should be divided into sub-skills
• Performing bulk audits across all project skills
• Validating skills before packaging or distribution

Workflow

Step 1: Discover Skills

List all skills in the .claude/skills/ directory:

ls -la .claude/skills/

For each skill directory, verify it contains the required SKILL.md file.

Step 2: Run Automated Validation

Execute the audit script to check structural requirements:

python .claude/skills/skill-auditor/scripts/audit_skills.py .claude/skills/

The script validates:

• YAML frontmatter presence and required fields
• Description quality (length, specificity)
• Word count limits (<5000 words recommended)
• Unfinished placeholder detection
• Empty directory warnings
• Script executability

Step 3: Manual Quality Review

For each skill, evaluate against these criteria:

Frontmatter Quality:

• name: Uses hyphens, is descriptive
• description: 50+ characters, specific about triggers, no placeholders

Content Structure:

• Clear "When to Use" section with specific triggers
• Workflow with actionable steps
• Bundled resources properly documented

Decomposition Analysis:

• Evaluate if skill handles >3 distinct concerns
• Check if skill exceeds 5000 words
• Identify reusable components that could be shared

Step 4: Generate Audit Report

Produce a structured report for each skill:

## Skill: [name]

### Validation Results
- Frontmatter: PASS/FAIL
- Structure: PASS/FAIL
- Word Count: X words (PASS/WARNING/FAIL)
- Unfinished Placeholders: X found

### Quality Score: X/10

### Recommendations
1. [Specific improvement]
2. [Another improvement]

### Decomposition Analysis
- Should split: YES/NO
- Reason: [explanation]
- Suggested sub-skills: [list if applicable]

Step 5: Apply Fixes

For automated fixes, use the audit script with --fix flag:

python .claude/skills/skill-auditor/scripts/audit_skills.py .claude/skills/ --fix

For manual improvements, edit SKILL.md files directly following recommendations.

Audit Criteria Reference

See references/audit-criteria.md for detailed scoring rubrics and decomposition guidelines.

Bundled Resources

Scripts

• scripts/audit_skills.py - Automated validation and reporting script

References

• references/audit-criteria.md - Detailed audit criteria and scoring rubrics