Audit Skill Completeness

Actions:

1. Verify SKILL.md exists
2. Check for scripts/, references/, assets/ directories
3. Read SKILL.md frontmatter and body
4. List all files in each directory

Validation:

• If SKILL.md missing, report error and exit
• If path is not a directory, report error and exit

Step 2: Evaluate Quality Categories

Run through each of the 8 categories using the detailed checklist in references/skill-completeness-checklist.md.

Quality Categories:

Evaluation Process:

For each category:

1. Read the category definition from references/skill-completeness-checklist.md
2. Review checklist items for that category
3. Search SKILL.md and supporting files for evidence
4. Score 0-3 based on rubric (below)
5. Document findings with file:line references

Step 3: Score and Report

Calculate overall score and write report to .claude/audits/completeness-report-{skill-slug}.md.

Report Structure:

# Skill Completeness Report: {skill-name}

**Evaluated:** {timestamp}
**Skill Path:** {absolute-path}

## Overall Score: {percentage}% ({score}/24)

| Category | Score | Label | Findings |
|----------|-------|-------|----------|
| 1. Preparation | 2 | Adequate | Environment checks present, missing metadata extraction |
| 2. Progression | 3 | Exemplary | Clear workflow, deterministic scripts, decision tree |
| ... | ... | ... | ... |

## Category Details

### 1. Preparation (2/3 - Adequate)

**What was evaluated:**
- Environment verification before starting
- Input inspection before acting
- Metadata extraction scripts

**Evidence found:**
- ✅ Environment check at SKILL.md:45-50
- ✅ Input validation at SKILL.md:65
- ❌ No metadata extraction script in scripts/

**Recommendation:**
Add a script to extract structured metadata from inputs so the AI operates on verified data instead of assumptions.

### 2. Progression (3/3 - Exemplary)

...

## Recommendations for Improvement

1. **High Priority:** Add metadata extraction script (Preparation)
2. **Medium Priority:** Include anti-pattern examples (Anti-Patterns)
3. **Low Priority:** Add visual validation examples (Verification)

## Reference

This audit follows patterns from Anthropic's official skills repository:
- https://github.com/anthropics/skills

Checklist: [Skill Completeness Checklist](./references/skill-completeness-checklist.md)

Output Location:

Report written to .claude/audits/completeness-report-{skill-slug}.md

If .claude/audits/ does not exist, create it.

Scoring Rubric

Each category is scored 0-3 based on presence and quality of evidence:

Overall Score Calculation:

Sum of category scores / 24 * 100 = percentage

Scoring Guidelines:

• Preparation (0-3):

  • 0: No environment checks, no input validation, no metadata extraction
  • 1: Environment checks OR input validation present
  • 2: Environment checks AND input validation present
  • 3: Environment checks, input validation, AND metadata extraction scripts

• Progression (0-3):

  • 0: No clear workflow, AI must generate all code
  • 1: Workflow defined but no scripts or examples
  • 2: Workflow defined with scripts OR examples
  • 3: Workflow defined with scripts AND examples AND decision trees

• Verification (0-3):

  • 0: No verification steps mentioned
  • 1: Manual verification suggested but not enforced
  • 2: Verification steps defined with acceptance criteria
  • 3: Automated verification scripts with error-correction loops

• Scripts (0-3):

  • 0: No scripts provided
  • 1: 1-2 scripts, limited functionality
  • 2: 3-5 scripts covering core operations
  • 3: 6+ scripts, --help support, comprehensive coverage

• Examples (0-3):

  • 0: No examples provided
  • 1: Abstract examples or pseudocode only
  • 2: Working examples with imports and realistic data
  • 3: Working examples covering common AND edge cases

• Anti-Patterns (0-3):

  • 0: No anti-patterns documented
  • 1: Anti-patterns mentioned but not shown
  • 2: Anti-patterns shown with corrections
  • 3: Anti-patterns shown with corrections AND reasoning

• References (0-3):

  • 0: No reference material
  • 1: External links only (not bundled)
  • 2: 1-2 reference files in references/
  • 3: 3+ reference files, organized by topic, linked from workflow

• Assets (0-3):

  • 0: No assets provided
  • 1: 1-2 asset files
  • 2: 3-5 asset files, organized
  • 3: 6+ asset files or comprehensive asset library

Output Format

Report filename: completeness-report-{skill-slug}.md

Where {skill-slug} is the skill directory name (e.g., audit-skill-completeness → completeness-report-audit-skill-completeness.md)

Report sections:

1. Header - skill name, path, timestamp
2. Overall Score - percentage and raw score
3. Summary Table - all categories with scores
4. Category Details - for each category:
   • Score and label
   • What was evaluated (checklist items)
   • Evidence found (file:line references)
   • Recommendations for improvement
5. Recommendations Summary - prioritized list
6. Reference - link to checklist and Anthropic repository

Quality Categories Reference

All 8 categories are detailed in references/skill-completeness-checklist.md with:

• Checklist items for each category
• Examples from Anthropic's official skills
• Patterns observed across creative, document, and developer skills
• Rationale for why each pattern matters

Additional Resources

• references/skill-completeness-checklist.md - detailed quality categories, checklist items, and examples from Anthropic's official skills repository