skill-validator

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](TROUBLESHOOTING.md) for complete issue handling.

References

• [EXAMPLES.md](EXAMPLES.md) - Real validation outputs
• [references/RULES_REFERENCE.md](references/RULES_REFERENCE.md) - Complete rules documentation