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)