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:

1. •Validate Structure - YAML, files, naming must pass minimum standards
2. •Validate Content - Essential sections and examples must be present
3. •Validate Pattern - Architecture pattern correctly implemented
4. •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:

1. •Pre-Deployment Gating - Validate skill ready for production before releasing
2. •Quality Standards Enforcement - Ensure all skills meet minimum bar
3. •Continuous Integration - Automated validation in build/deploy pipelines
4. •Certification - Certify skills meet ecosystem standards
5. •Post-Update Validation - Ensure changes didn't break compliance
6. •Ecosystem Consistency - Maintain quality across all skills
7. •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:

1. •Run automated validation: python3 review-multi/scripts/validate-structure.py <skill>
2. •Check score: Must be ≥4 to pass
3. •Verify no critical issues
4. •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:

1. •Check for Overview section (## Overview or ## Introduction)
2. •Check for When to Use section with scenarios
3. •Verify main content exists (steps, operations, or reference material)
4. •Count examples (look for ``` code blocks, minimum 3)
5. •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:

1. •Identify pattern type (workflow/task/reference)
2. •Check pattern-specific criteria
3. •Verify pattern consistency throughout
4. •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:

1. •Run Operations 1-3
2. •Check for critical anti-patterns:
   • •Monolithic SKILL.md (>2,000 lines, no references)
   • •All examples are placeholders
   • •Major sections missing
3. •Assess overall completeness
4. •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

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:

1. •skill-validator: Pass/fail, deployment gating
2. •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.