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