Skill Validation Skill

Validates skill directories using a comprehensive set of 168+ validation rules extracted from:

• •AgentSkills OpenSpec (skills-ref library) - 44 rules
• •Nixtla Quality Standards (strict mode) - 52 rules
• •Meta-Skill Validation (8+1 Pillars, checklists) - 47 rules
• •Component Validators (multi-scale scoring, grading) - 25 rules

Quick Navigation

Overview

This skill provides comprehensive validation for Claude Code skills according to multiple quality standards:

1. •Basic Validation - Structure, frontmatter, SKILL.md existence
2. •Quality Validation - Description quality, token budget, path formats
3. •Strict Mode - Nixtla required sections, voice checks
4. •OpenSpec Mode - AgentSkills strict field whitelist
5. •Pillars Mode - 8+1 Pillars coverage for lang-/convert- skills

Prerequisites

• •Python 3.12+ with pyyaml installed
• •The skill to validate must be a directory containing SKILL.md
• •For Pillars validation, skill name must start with lang- or convert-

Instructions

1. Run Basic Validation

uv run python scripts/validate_skill_comprehensive.py path/to/skill/

Output: Grade (A-F), issue counts, detailed results by category.

2. Run Verbose Validation (Show All Checks)

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --verbose

3. Run Strict Mode (Nixtla Quality Standards)

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --strict

Additional checks:

• •Required sections: Overview, Prerequisites, Instructions, Output, Error Handling, Examples, Resources
• •Description must include "Use when..." phrase
• •Description must NOT use first/second person
• •Instructions must have numbered step-by-step list

4. Run OpenSpec Mode (AgentSkills Strict Whitelist)

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --openspec

Additional checks:

• •Only 6 fields allowed: name, description, license, allowed-tools, metadata, compatibility
• •Name MUST match directory name
• •Extra fields cause MAJOR errors (not warnings)

5. Run Pillars Validation (Language Skills)

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --pillars

Validates 8+1 Pillars coverage:

1. •Module - import/export, namespacing
2. •Error - error handling, Result types
3. •Concurrency - async, threads, channels
4. •Metaprogramming - macros, decorators
5. •Zero/Default - null handling, Option types
6. •Serialization - JSON, encoding/decoding
7. •Build - package management
8. •Testing - test frameworks, assertions
9. •Dev Workflow/REPL (for REPL-centric languages)

6. Combine All Modes

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --strict --openspec --pillars --verbose

7. JSON Output (For CI/CD)

uv run python scripts/validate_skill_comprehensive.py path/to/skill/ --json

Output

Grade System (A-F)

Exit Codes

Severity Levels

Validation Checklist

Copy this checklist and track your progress:

• • Run basic validation: uv run python scripts/validate_skill_comprehensive.py path/to/skill/
• • Fix all CRITICAL issues (Grade F blockers)
• • Fix all MAJOR issues (Grade D issues)
• • Run strict mode: add --strict flag
• • Address required sections (Overview, Prerequisites, etc.)
• • For lang-/convert- skills: run with --pillars flag
• • Verify 8+1 Pillars coverage (50%+ recommended)
• • Run with --verbose to review all checks
• • Achieve Grade B or higher before deployment
• • Document any intentionally skipped checks

Error Handling

Common Errors and Solutions

"SKILL.md not found"

• •Ensure the path points to a skill directory (not a file)
• •Check file is named SKILL.md (uppercase preferred)

"Malformed YAML frontmatter"

• •Ensure frontmatter starts and ends with ---
• •Validate YAML syntax (check for missing quotes, colons)

"Skill name must be lowercase"

• •Use kebab-case: my-skill-name not MySkillName

"Directory name must match skill name"

• •Rename directory or update name field to match

"Required section missing"

• •Add missing sections (only in --strict mode)
• •Sections: Overview, Prerequisites, Instructions, Output, Error Handling, Examples, Resources

"SKILL.md has X lines (max 500)"

• •Move detailed content to references/ subdirectory
• •Use progressive disclosure pattern

Examples

Example 1: Validate a Single Skill

$ uv run python scripts/validate_skill_comprehensive.py ./skills/my-skill/

======================================================================
Skill Validation: ./skills/my-skill/
======================================================================

Grade: B (85.2/100)

Summary:
  CRITICAL: 0
  MAJOR:    0
  MINOR:    3

Details:
  [Description Quality]
    [MINOR] Description should include 'Use when ...' phrase

  [Token Budget]
    [MINOR] SKILL.md has 520 lines (recommended: under 500)

----------------------------------------------------------------------
✓ Skill validation passed (Grade B)

Example 2: Validate with Strict Mode

$ uv run python scripts/validate_skill_comprehensive.py ./skills/lang-rust-dev/ --strict --pillars

======================================================================
Skill Validation: ./skills/lang-rust-dev/
======================================================================

Grade: A (94.5/100)

Pillars Coverage:
  ✓ Module: 1.0/1.0 - Full coverage with dedicated section
  ✓ Error: 1.0/1.0 - Full coverage (12 keyword occurrences)
  ~ Concurrency: 0.5/1.0 - Partial coverage (4 keyword occurrences)
  ✓ Metaprogramming: 1.0/1.0 - Full coverage with dedicated section
  ✓ Zero/Default: 1.0/1.0 - Full coverage (8 keyword occurrences)
  ✓ Serialization: 1.0/1.0 - Full coverage with dedicated section
  ✓ Build: 1.0/1.0 - Full coverage with dedicated section
  ✓ Testing: 1.0/1.0 - Full coverage (15 keyword occurrences)

----------------------------------------------------------------------
✓ Skill validation passed (Grade A)

Example 3: JSON Output for CI/CD

$ uv run python scripts/validate_skill_comprehensive.py ./skills/my-skill/ --json

{
  "skill_path": "./skills/my-skill/",
  "exit_code": 0,
  "overall_score": 92.5,
  "grade": "A",
  "counts": {
    "critical": 0,
    "major": 0,
    "minor": 1,
    "info": 2,
    "passed": 25
  },
  "pillar_scores": [],
  "category_scores": {},
  "results": [...]
}

Resources

Official Documentation

• •AgentSkills OpenSpec - Official skill specification
• •Claude Code Skills - Anthropic skill documentation
• •skills-ref Library - Reference validator library

Reference Documents (in this skill)

• •Validation Rules - Complete 168+ rules reference
• •Frontmatter Schema - Field requirements
• •Pillars Coverage - 8+1 Pillars validation guide
• •Scoring System - Grading and scoring details

Related Skills

• •plugin-validation-skill - Plugin-level validation
• •marketplace-validation-skill - Marketplace validation

See Also

• •/validate-skill command - Invoke this validation
• •skill-validation-agent - Agent for automated skill audits