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
1---2name: skill-validator-43description: 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".4---5
6# Skill Validator
7
8Run automated checks against 62 rules covering frontmatter, structure, content, files, references, security, hooks, and MCP.
9
10## Quick Start
11
12```bash
13scripts/validate_skill.py /path/to/skill-directory
14```
15
16With severity filter:
17
18```bash
19scripts/validate_skill.py /path/to/skill --min-severity warning
20```
21
22## Validation Categories
23
24| 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 |
34
35## Severity Levels
36
37| Level | Action |
38|-------|--------|
39| CRITICAL | Must fix before publishing |
40| ERROR | Should fix |
41| WARNING | Consider fixing |
42| SUGGESTION | Optional improvement |
43
44## Output Example
45
46```
47=== Skill Validation Report: my-skill ===
48
49Summary: 0 critical, 1 error, 2 warnings, 1 suggestion
50
51[ERROR] SS002: SKILL.md exceeds 500 lines (523 lines)
52 Location: SKILL.md
53 Fix: Split content into WORKFLOW.md, EXAMPLES.md, TROUBLESHOOTING.md
54
55[WARNING] CW001: Second-person language detected
56 Location: SKILL.md:45
57 Found: "You should create..."
58 Fix: Use imperative: "Create..."
59```
60
61## Command Options
62
63```bash
64--min-severity {critical,error,warning,suggestion} # Filter output
65--format {text,json} # Output format
66--ignore RULE1,RULE2 # Skip specific rules
67```
68
69## Common Issues
70
71**"False positive on second-person"**
72- Context-appropriate "you" may be acceptable
73- Use `--ignore CW001` to suppress
74
75**"Script security warning"**
76- Add inline comment: `# skill-validator: ignore SC001`
77
78**"Hook/MCP validation incomplete"**
79- Install PyYAML for full nested structure validation: `pip install pyyaml`
80
81See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete issue handling.
82
83## References
84
85- [EXAMPLES.md](EXAMPLES.md) - Real validation outputs
86- [references/RULES_REFERENCE.md](references/RULES_REFERENCE.md) - Complete rules documentation
majiayu000