Skill Validator

{
  "$schema": "https://agentskills.io/schemas/manifest.v1.json",
  "manifestVersion": "1.0",
  "generatedAt": "2026-01-03T02:24:46.094996Z",
  "generator": "skill-manifest-generator/1.0.0",
  "skill": {
    "name": "skill-validator",
    "version": "1.0.0"
  },
  "integrity": {
    "algorithm": "sha256",
    "hash": "2c48316df8cb9231cc24b1387e24ef96b1ff5d383af74caea719185841c2bf6f"
  },
  "files": [
    {
      "path": "SKILL.md",
      "size": 2586,
      "sha256": "c662b1e1bc6846aeefe7cf06ad3be26518f2168bd4db68dfd38b9cb95bceabfe",
      "type": "manifest"
    },
    {
      "path": "scripts/validate_skill.py",
      "size": 14502,
      "sha256": "ebf57274d07bf593eab81cbf7b3455e406827960d0eec4e91831838411e39009",
      "type": "script"
    }
  ],
  "externalReferences": [],
  "structure": {
    "maxDepth": 1,
    "totalFiles": 2,
    "totalBytes": 17088,
    "folders": [
      "scripts"
    ]
  },
  "license": {
    "spdxId": "MIT"
  }
}


#!/usr/bin/env python3
"""
Skill Validator

Validates Agent Skills against the specification.
This script mirrors the validation logic from src/lib/spec-compliance/index.ts
to ensure consistent behavior between the skill and the catalog.

Usage:
    python validate_skill.py /path/to/skill
    python validate_skill.py /path/to/skill --json
    python validate_skill.py /path/to/skill --strict
"""

import argparse
import json
import os
import re
import sys
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Optional

# Try to import yaml, fall back to basic parsing if not available
try:
    import yaml
    HAS_YAML = True
except ImportError:
    HAS_YAML = False


@dataclass
class ValidationResult:
    """Result of skill validation - mirrors ComplianceResult from TypeScript"""
    is_compliant: bool
    score: int  # 0-100
    has_skill_md: bool
    has_valid_name: bool
    has_valid_description: bool
    name_matches_dir: bool
    has_valid_structure: bool
    skill_name: Optional[str]
    description: Optional[str]
    issues: list = field(default_factory=list)
    warnings: list = field(default_factory=list)

    # Additional fields for enhanced validation
    version: Optional[str] = None
    license: Optional[str] = None
    author: Optional[str] = None
    tags: list = field(default_factory=list)


def validate_name(name: str) -> tuple[bool, Optional[str]]:
    """
    Validate a skill name according to spec.

    Rules (from src/lib/spec-compliance/index.ts):
    - 1-64 characters
    - lowercase alphanumeric and hyphens only
    - cannot start with hyphen
    - cannot end with hyphen
    - no consecutive hyphens

    Extended rules (from specs/20-skill-manifest-system.md):
    - must start with a letter
    """
    if not name or len(name) == 0:
        return False, "Name is required"

    if len(name) > 64:
        return False, "Name exceeds 64 characters"

    # Must be lowercase alphanumeric and hyphens only
    if not re.match(r'^[a-z0-9-]+$', name):
        return False, "Name must be lowercase alphanumeric and hyphens only"

    # Must start with a letter (extended rule from Spec 20)
    if not re.match(r'^[a-z]', name):
        return False, "Name must start with a letter"

    if name.startswith("-"):
        return False, "Name cannot start with a hyphen"

    if name.endswith("-"):
        return False, "Name cannot end with a hyphen"

    if "--" in name:
        return False, "Name cannot contain consecutive hyphens"

    return True, None


def validate_description(desc: str) -> tuple[bool, Optional[str]]:
    """
    Validate description according to spec.

    Rules:
    - 1-1024 characters
    - non-empty
    """
    if not desc or len(desc.strip()) == 0:
        return False, "Description is required"

    if len(desc) > 1024:
        return False, "Description exceeds 1024 characters"

    return True, None


def validate_version(version: str) -> tuple[bool, Optional[str]]:
    """Validate version follows semver format (war