skill-validator

Instructions

Use this skill to validate any Agent Skill directory against the specification before publishing. The validator checks:

• SKILL.md presence - Required manifest file exists
• Frontmatter format - Valid YAML frontmatter with required fields
• Name validation - 1-64 chars, lowercase, hyphens only, starts with letter
• Name-directory match - Name field matches the directory name
• Description validation - 1-1024 characters, non-empty
• Structure validation - Valid folder organization

When to Use

• Before submitting a skill for publication
• After making changes to SKILL.md
• To diagnose why a skill was rejected
• As part of CI/CD pipelines

How to Use

Validate a skill directory:

Validate the skill at /path/to/my-skill

Get JSON output for CI integration:

python3 validate_skill.py /path/to/my-skill --json

Output

✓ Skill Validation Report
  Skill: pdf-tools
  Status: COMPLIANT (100/100)

  Checks:
    ✓ SKILL.md exists
    ✓ Valid frontmatter
    ✓ Name format valid (pdf-tools)
    ✓ Name matches directory
    ✓ Description valid (45 chars)
    ✓ Structure valid

  No issues found.

Or if issues are found:

✗ Skill Validation Report
  Skill: My-Skill
  Status: NON-COMPLIANT (40/100)

  Checks:
    ✓ SKILL.md exists
    ✓ Valid frontmatter
    ✗ Name format invalid
    ✗ Name doesn't match directory
    ✓ Description valid
    ✓ Structure valid

  Issues:
    - Name must be lowercase with hyphens only (got "My-Skill")
    - Name 'My-Skill' doesn't match directory 'my-skill'

Examples

Basic validation:

User: Validate the skill at ./document-skills/pdf
Agent: Running validation on ./document-skills/pdf...
       ✓ Skill is compliant (100/100)

Fix validation errors:

User: Why is my skill failing validation?
Agent: Let me check... Running validator...
       The name field uses underscores. Change "pdf_tools" to "pdf-tools".

Limitations

• Does not validate skill functionality (only structure/format)
• Does not run safety scans (use skill-safety-scanner for that)
• Requires local filesystem access to the skill directory

Dependencies

• Python 3.9+
• PyYAML (optional, falls back to basic parsing)