Skill Validator

Overview

skill-validator ensures Claude Code skills meet established quality standards through systematic validation operations. Unlike review-multi (which scores 1-5), skill-validator provides pass/fail validation against minimum standards for production deployment.

Purpose: Quality gate for skill deployment - ensure minimum standards met

The 4 Validation Operations:

Validate Structure - YAML, files, naming must pass minimum standards
Validate Content - Essential sections and examples must be present
Validate Pattern - Architecture pattern correctly implemented
Validate Production Readiness - All critical criteria met for deployment

Difference from review-multi:

review-multi: Scores 1-5, identifies improvements, comprehensive assessment
skill-validator: Pass/fail, minimum standards, deployment gating

Use Together: review-multi for comprehensive assessment, skill-validator for go/no-go decisions

When to Use

Use skill-validator when:

Pre-Deployment Gating - Validate skill ready for production before releasing
Quality Standards Enforcement - Ensure all skills meet minimum bar
Continuous Integration - Automated validation in build/deploy pipelines
Certification - Certify skills meet ecosystem standards
Post-Update Validation - Ensure changes didn't break compliance
Ecosystem Consistency - Maintain quality across all skills
Binary Decision Needed - Ship or don't ship (not "what's the score")

Operations

Operation 1: Validate Structure

Purpose: Ensure skill structure meets minimum standards for deployment

Pass Criteria (All must pass):

✅ YAML frontmatter valid with required fields (name, description)
✅ name in kebab-case format
✅ description includes 3+ trigger keywords minimum
✅ SKILL.md exists
✅ File naming follows conventions
✅ No critical structure violations

Process:

Run automated validation: python3 review-multi/scripts/validate-structure.py <skill>
Check score: Must be ≥4 to pass
Verify no critical issues
Document pass/fail

Validation: PASS if structure score ≥4, FAIL if <4

Time: 5-10 minutes (automated)

Operation 2: Validate Content

Purpose: Ensure essential content sections and examples present

Pass Criteria (All must pass):

✅ Overview/Introduction section present
✅ When to Use section with 3+ scenarios minimum
✅ Main content present (workflow steps OR operations OR reference)
✅ At least 3 examples present (code/command)
✅ Some form of best practices or guidance

Process:

Check for Overview section (## Overview or ## Introduction)
Check for When to Use section with scenarios
Verify main content exists (steps, operations, or reference material)
Count examples (look for ``` code blocks, minimum 3)
Check for Best Practices, Common Mistakes, or guidance section

Validation: PASS if all 5 criteria met, FAIL if any missing

Time: 10-15 minutes (manual check)

Operation 3: Validate Pattern

Purpose: Ensure architecture pattern correctly implemented

Pass Criteria (Pattern-specific):

For Workflow Skills:

✅ Sequential steps present
✅ Steps have consistent structure
✅ Prerequisites or Post-Workflow section exists

For Task Skills:

✅ Operations section present
✅ Operations have consistent structure
✅ Operations are independent (no forced sequence)

For Reference Skills:

✅ Topic-based organization
✅ Quick Reference present

Process:

Identify pattern type (workflow/task/reference)
Check pattern-specific criteria
Verify pattern consistency throughout
Document compliance

Validation: PASS if pattern correctly implemented, FAIL if pattern violated

Time: 10-20 minutes (manual check)

Operation 4: Validate Production Readiness

Purpose: Comprehensive pass/fail check for deployment readiness

Pass Criteria (All must pass):

✅ Structure validation passes (Operation 1)
✅ Content validation passes (Operation 2)
✅ Pattern validation passes (Operation 3)
✅ No critical anti-patterns (from review-multi if available)
✅ SKILL.md completeness (not stub or incomplete)
✅ Examples are concrete (not all placeholders)

Process:

Run Operations 1-3
Check for critical anti-patterns:
- Monolithic SKILL.md (>2,000 lines, no references)
- All examples are placeholders
- Major sections missing
Assess overall completeness
Make deployment decision

Validation: PASS if all criteria met (ready to deploy), FAIL if any critical issue

Time: 30-45 minutes (combines all operations)

Output: DEPLOY or HOLD decision

Validation Report Format

# Skill Validation Report: [Skill Name]

**Validation Date**: [Date]
**Validator**: [Name]

## Validation Results

Operation 1: Structure Validation
Status: ✅ PASS | ❌ FAIL
- YAML: [Pass/Fail]
- Files: [Pass/Fail]
- Naming: [Pass/Fail]
- Structure Score: [X]/5

Operation 2: Content Validation
Status: ✅ PASS | ❌ FAIL
- Overview: [Present/Missing]
- When to Use: [X scenarios - Pass if ≥3]
- Main Content: [Present/Missing]
- Examples: [X examples - Pass if ≥3]
- Guidance: [Present/Missing]

Operation 3: Pattern Validation
Status: ✅ PASS | ❌ FAIL
- Pattern: [Workflow/Task/Reference]
- Implementation: [Correct/Incorrect]
- Consistency: [Yes/No]

Operation 4: Production Readiness
Status: ✅ READY TO DEPLOY | ❌ HOLD

Critical Issues: [List if any]

## Deployment Decision

✅ DEPLOY - All validations passed, ready for production

OR

❌ HOLD - Critical issues must be fixed:
1. [Issue 1 with fix]
2. [Issue 2 with fix]

Best Practices

1. Validate Before Deploy

Practice: Run skill-validator on all skills before production deployment

Rationale: Catches critical issues, prevents shipping broken skills

Application: Make validation part of deployment checklist

2. Use as Quality Gate

Practice: Skills must pass validation to be deployed

Rationale: Maintains ecosystem quality baseline

Application: No exceptions - PASS required for deployment

3. Automate Where Possible

Practice: Use review-multi automation for structure validation

Rationale: 95% automated, fast, consistent

Application: Run validate-structure.py as first check

4. Document Failures Clearly

Practice: When skill fails, specify exactly what to fix

Rationale: Actionable feedback enables quick fixes

Application: List specific issues with remediation steps

5. Re-Validate After Fixes

Practice: After fixing issues, run validation again to confirm

Rationale: Ensures fixes actually resolve issues

Application: Validate → Fix → Re-validate cycle

Quick Reference

The 4 Validations

Operation	Focus	Pass Criteria	Time	Automation
Structure	YAML, files, naming	Score ≥4	5-10m	95% (use review-multi)
Content	Sections, examples	5 criteria all met	10-15m	40%
Pattern	Architecture compliance	Pattern correct	10-20m	50%
Production Readiness	Overall deployment decision	All validations pass	30-45m	Combined

Minimum Standards

Structure:

Valid YAML with name + description
name in kebab-case
3+ trigger keywords
SKILL.md exists
Basic file structure

Content:

Overview present
3+ When to Use scenarios
Main content present
3+ examples
Some guidance/best practices

Pattern:

Correct pattern implementation
Consistent structure
Pattern-specific requirements met

Production:

All validations pass
No critical anti-patterns
Completeness (not stub)
Examples concrete

Deployment Decision Tree

Run validation operations 1-4
     ↓
All PASS?
├─ Yes → ✅ DEPLOY (production ready)
└─ No → Which failed?
    ├─ Structure → Fix YAML/files (critical)
    ├─ Content → Add missing sections (critical)
    ├─ Pattern → Fix implementation (critical)
    └─ After fixes → Re-validate → Deploy if pass

Integration with review-multi

Use Both:

skill-validator: Pass/fail, deployment gating
review-multi: 1-5 scoring, comprehensive assessment, improvements

Workflow:

Build skill → skill-validator (PASS?) → review-multi (score?) →
Deploy (if PASS) + Note improvements (from review-multi)

skill-validator provides quality gating for skill deployment, ensuring minimum standards met before production release.