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-directory
With severity filter:
scripts/validate_skill.py /path/to/skill --min-severity warning
Validation 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 rules
Common Issues
"False positive on second-person"
- Context-appropriate "you" may be acceptable
- Use
--ignore CW001 to 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: skill-validator-53description: Validate skills against Anthropic best practices for frontmatter, structure, content, file organization, hooks, MCP, and security (62 rules in 8 categories). Use when creating new skills, updating existing skills, before publishing skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill". Use when this capability is needed.4---56# Skill Validator78Run automated checks against 62 rules covering frontmatter, structure, content, files, references, security, hooks, and MCP.910## Quick Start1112```bash13scripts/validate_skill.py /path/to/skill-directory14```1516With severity filter:1718```bash19scripts/validate_skill.py /path/to/skill --min-severity warning20```2122## Validation Categories2324| Category | Rules | Checks |25|----------|-------|--------|26| **Frontmatter** | FM001-FM018 | Required fields, naming, description, context/agent, maxTurns, memory, disable-model-invocation |27| **Structure** | SS001-SS006 | Line limits, progressive disclosure |28| **Content** | CW001-CW009 | Writing style, terminology, string substitution, dynamic context injection, ultrathink |29| **Files** | FO001-FO007 | Naming conventions, forbidden files |30| **References** | RI001-RI003 | Broken links, orphan files |31| **Security** | SC001-SC005 | eval/exec, undocumented constants |32| **Hooks** | HK001-HK003 | Hook structure, handler format, matcher format |33| **MCP** | MC001 | MCP server configuration format |3435## Severity Levels3637| Level | Action |38|-------|--------|39| CRITICAL | Must fix before publishing |40| ERROR | Should fix |41| WARNING | Consider fixing |42| SUGGESTION | Optional improvement |4344## Output Example4546```47=== Skill Validation Report: my-skill ===4849Summary: 0 critical, 1 error, 2 warnings, 1 suggestion5051[ERROR] SS002: SKILL.md exceeds 500 lines (523 lines)52 Location: SKILL.md53 Fix: Split content into WORKFLOW.md, EXAMPLES.md, TROUBLESHOOTING.md5455[WARNING] CW001: Second-person language detected56 Location: SKILL.md:4557 Found: "You should create..."58 Fix: Use imperative: "Create..."59```6061## Command Options6263```bash64--min-severity {critical,error,warning,suggestion} # Filter output65--format {text,json} # Output format66--ignore RULE1,RULE2 # Skip specific rules67```6869## Common Issues7071**"False positive on second-person"**72- Context-appropriate "you" may be acceptable73- Use `--ignore CW001` to suppress7475**"Script security warning"**76- Add inline comment: `# skill-validator: ignore SC001`7778**"Hook/MCP validation incomplete"**79- Install PyYAML for full nested structure validation: `pip install pyyaml`8081See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete issue handling.8283## References8485- [EXAMPLES.md](EXAMPLES.md) - Real validation outputs86- [references/RULES_REFERENCE.md](references/RULES_REFERENCE.md) - Complete rules documentation8788---89> Converted and distributed by [TomeVault](https://tomevault.io/claim/joaquimscosta) — claim your Tome and manage your conversions.90<!-- tomevault:4.0:skill_md:2026-04-12 -->
tomevault-io