skill-validator
Validate skills against best practices for YAML frontmatter, structure, content standards, file organization, and security. Use when creating new skills, updating existing skills, before packaging skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill".
When & Why to Use This Skill
The Skill Validator is a specialized developer tool designed to automate the quality assurance process for Claude skills. It rigorously checks skill packages against Anthropic's best practices, covering YAML frontmatter accuracy, structural integrity, content style, file organization, and security vulnerabilities. By providing actionable feedback and severity-based reporting, it ensures that agentic skills are robust, secure, and optimized for performance within the Claude ecosystem.
Use Cases
- Pre-publishing Validation: Automatically verify that a new skill meets all required YAML fields, naming conventions, and structural standards before packaging.
- Security Auditing: Scan skill source code and configurations for potential security risks such as 'eval' usage, undocumented constants, or unsafe execution patterns.
- Content Quality Control: Ensure documentation follows professional writing styles and terminology, identifying issues like second-person language or excessive file lengths.
- Continuous Integration: Integrate the validator into development workflows to catch 'lint' errors early when updating existing skills or refactoring file structures.
| name | skill-validator |
|---|---|
| description | Validate skills against best practices for YAML frontmatter, structure, content standards, file organization, and security. Use when creating new skills, updating existing skills, before packaging skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill". |
Skill Validator
Validate skills against Anthropic's best practices for structure, content, and security.
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-FM012 | Required fields, naming, description quality |
| Structure | SS001-SS006 | Line limits, progressive disclosure |
| Content | CW001-CW006 | Writing style, terminology |
| Files | FO001-FO007 | Naming conventions, forbidden files |
| References | RI001-RI003 | Broken links, orphan files |
| Security | SC001-SC005 | eval/exec, undocumented constants |
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 CW001to suppress
"Script security warning"
- Add inline comment:
# skill-validator: ignore SC001
See TROUBLESHOOTING.md for complete issue handling.
References
- EXAMPLES.md - Real validation outputs
- references/RULES_REFERENCE.md - Complete rules documentation