Skill Validator
Run automated checks against 62 rules covering frontmatter, structure, content, files, references, security, hooks, and MCP.
Quick Start
scripts/validate_skill.py /path/to/skill-directoryWith severity filter:
scripts/validate_skill.py /path/to/skill --min-severity warningValidation Categories
| Category | Rules | Checks |
|---|---|---|
| Frontmatter | FM001-FM018 | Required fields, naming, description, context/agent, maxTurns, memory, disable-model-invocation |
| Structure | SS001-SS006 | Line limits, progressive disclosure |
| Content | CW001-CW009 | Writing style, terminology, string substitution, dynamic context injection, ultrathink |
| Files | FO001-FO007 | Naming conventions, forbidden files |
| References | RI001-RI003 | Broken links, orphan files |
| Security | SC001-SC005 | eval/exec, undocumented constants |
| Hooks | HK001-HK003 | Hook structure, handler format, matcher format |
| MCP | MC001 | MCP server configuration format |
Severity Levels
| Level | Action |
|---|---|
| CRITICAL | Must fix before publishing |
| ERROR | Should fix |
| WARNING | Consider fixing |
| SUGGESTION | Optional improvement |
Output Example
=== Skill Validation Report: my-skill ===
Summary: 0 critical, 1 error, 2 warnings, 1 suggestion
[ERROR] SS002: SKILL.md exceeds 500 lines (523 lines)
Location: SKILL.md
Fix: Split content into WORKFLOW.md, EXAMPLES.md, TROUBLESHOOTING.md
[WARNING] CW001: Second-person language detected
Location: SKILL.md:45
Found: "You should create..."
Fix: Use imperative: "Create..."Command Options
--min-severity {critical,error,warning,suggestion} # Filter output
--format {text,json} # Output format
--ignore RULE1,RULE2 # Skip specific rulesCommon Issues
"False positive on second-person"
- Context-appropriate "you" may be acceptable
- Use
--ignore CW001to suppress
"Script security warning"
- Add inline comment:
# skill-validator: ignore SC001
"Hook/MCP validation incomplete"
- Install PyYAML for full nested structure validation:
pip install pyyaml
See TROUBLESHOOTING.md for complete issue handling.
References
- EXAMPLES.md - Real validation outputs
- references/RULES_REFERENCE.md - Complete rules documentation