Skill Validator

Skill Validator

Overview

Skills are Bosun's knowledge packages. Invalid skills break the plugin. This skill guides systematic validation of Bosun skills before they ship.

Core principle: Validate early, validate often. A malformed skill wastes everyone's time.

The Validation Process

Phase 1: Frontmatter Validation

Check the YAML frontmatter at the top of SKILL.md:

1. Required Fields

   • name - Must be present, must be {purpose} format
   • description - Must be present, must include trigger phrases

2. Forbidden Fields

   • tags - Removed per skill-creator spec
   • Any field other than name and description

3. Description Quality

   • Includes "Use when..." trigger phrases
   • 50-100 words (comprehensive but concise)
   • No angle brackets (< or >)

Phase 2: Structure Validation

Check the SKILL.md body structure:

1. Required Sections

   • Overview with core principle
   • "When to Use" or similar trigger section
   • Red Flags section
   • Checklist section
   • Quick Commands or Quick Patterns

2. Length Check

   • SKILL.md should be < 500 lines
   • If approaching limit, content should be in references/

3. Code Examples

   • Use ✅/❌ or checkmark/X pattern for good/bad
   • Examples should be practical and runnable

Phase 3: Reference Validation

Check the references/ directory:

1. Cited References Exist

   • Every file mentioned in SKILL.md References section exists
   • Check: references/{filename}.md

2. No Orphaned References

   • Every file in references/ is cited in SKILL.md
   • Orphaned files waste space and cause confusion

3. Naming Convention

   • Files should be {topic}.md or {topic}-patterns.md
   • Avoid {skill}-research.md pattern

Red Flags - STOP and Fix

Frontmatter Red Flags

# ❌ Has tags field (removed from spec)
tags: [security, owasp]

# ❌ Missing description
name: security

# ❌ Wrong naming pattern
name: security-skill  # Should be security

# ❌ No trigger phrases in description
description: "Security stuff"  # Should include "Use when..."

Structure Red Flags

- SKILL.md over 500 lines (move content to references/)
- Missing Red Flags section (every skill needs warnings)
- Missing Checklist (users need actionable checks)
- No code examples (skills should show, not just tell)
- Deeply nested headers (keep it flat: h1 → h2 → h3 max)

Reference Red Flags

- "See references/foo.md" but foo.md doesn't exist
- references/ has files never mentioned in SKILL.md
- Research files with no clear topic ({skill}-research.md)

Common Rationalizations - Don't Accept These

Validation Checklist

Before approving a skill:

Frontmatter:

• Only name and description fields
• Name follows {purpose} pattern
• Description includes trigger phrases ("Use when...")
• Description is 50-100 words

Structure:

• SKILL.md is < 500 lines
• Has Overview with core principle
• Has Red Flags section
• Has Checklist section
• Has Quick Commands/Patterns section
• Code examples use ✅/❌ pattern

References:

• All cited references exist in references/
• No orphaned files in references/
• Reference naming follows convention

Quick Validation Commands

# Check frontmatter for forbidden fields
head -10 skills/*/SKILL.md | grep -E "^tags:"

# Count lines in each skill
wc -l skills/*/SKILL.md | sort -n

# Find skills over 400 lines (approaching limit)
wc -l skills/*/SKILL.md | awk '$1 > 400 {print}'

# List all reference files
ls skills/*/references/*.md

# Find cited references in a skill
grep -o 'references/[^`]*\.md' skills/security/SKILL.md

Validation Output Format

When validating, report findings like this:

Validating security...
  ✓ Frontmatter valid
  ✓ Structure valid (178 lines)
  ✓ References valid (4 cited, 4 exist)

Validating architect...
  ✓ Frontmatter valid
  ✓ Structure valid (199 lines)
  ✗ Missing reference: api-design.md
  ✗ Missing reference: architecture-patterns.md

Summary: 18/20 skills valid, 2 with issues

References

• Skill-creator specification for base validation rules
• CLAUDE.md for Bosun-specific conventions

Converted and distributed by TomeVault — claim your Tome and manage your conversions.