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"

"Script security warning"

"Hook/MCP validation incomplete"

See TROUBLESHOOTING.md for complete issue handling.

References

Source Transparency