7.6 KiB
7.6 KiB
name, version, description
| name | version | description |
|---|---|---|
| skill-validator | 1.0.0 | Validate Claude Code skills, commands, agents, hooks, and plugins against specifications. Checks structure, format, best practices, and common issues before committing or distributing. Use when: validating skills, checking plugins, linting components, ensuring quality. Activates for: "validate skill", "check skill", "validate plugin", "lint skill", "verify skill" |
Skill Validator
Validate Claude Code components against specifications and best practices.
When to Use
- Before committing skills/plugins
- Before distributing to marketplace
- During skill development (catch issues early)
- Reviewing community contributions
- Ensuring quality standards
Validation Checks
Skills (SKILL.md)
Structure Checks
- ✅ YAML frontmatter present and valid
- ✅ Required fields: name, version, description
- ✅ Name is kebab-case
- ✅ Version follows semantic versioning
- ✅ Description is clear and includes triggers
Content Checks
- ✅ Has "When to Use" section
- ✅ Has workflow or instructions
- ✅ Includes examples
- ✅ Under 500 lines (or has progressive disclosure)
- ✅ No TODOs or placeholders
- ✅ No generic labels (helper, util, tool)
Best Practices
- ✅ Specific triggers (not too generic)
- ✅ Real examples (not placeholders)
- ✅ Clear, actionable instructions
- ✅ Integration points documented
- ✅ Troubleshooting section present
Commands
Structure Checks
- ✅ YAML frontmatter with description
- ✅ Clear command name
- ✅ Usage examples provided
- ✅ Parameters documented
Content Checks
- ✅ Purpose is clear
- ✅ Instructions are actionable
- ✅ Examples show real usage
- ✅ Parameter descriptions complete
Agents
Structure Checks
- ✅ YAML frontmatter present
- ✅ Model specified (haiku/sonnet/opus)
- ✅ Purpose is clear
- ✅ Workflow defined
Content Checks
- ✅ Single responsibility
- ✅ Operational principles defined
- ✅ Quality standards specified
- ✅ Success criteria clear
- ✅ Appropriate model for task complexity
Hooks
Structure Checks
- ✅ Valid JSON format
- ✅ Event type is valid
- ✅ Command is specified
- ✅ Description provided
Safety Checks
- ✅ No arbitrary code execution
- ✅ File paths are validated
- ✅ Commands are safe
- ✅ Filters are specific (not too broad)
Plugins
Structure Checks
- ✅
.claude-plugin/plugin.jsonexists - ✅ Valid JSON format
- ✅ Required fields present
- ✅ Referenced components exist
- ✅ Directory structure correct
Manifest Checks
- ✅ Name is kebab-case
- ✅ Version follows semver
- ✅ Description is clear
- ✅ Keywords are relevant
- ✅ Author info present (if distributing)
Core Workflow
1. Identify Component Type
Determine what to validate:
- Skill (SKILL.md)
- Command (.md in commands/)
- Agent (.md in agents/)
- Hook (hooks.json)
- Plugin (entire plugin directory)
2. Run Validation Checks
Execute appropriate checks based on component type.
3. Report Issues
Categorize by severity:
- Error: Must fix (prevents functionality)
- Warning: Should fix (best practice violation)
- Info: Consider fixing (minor improvement)
4. Provide Fixes
For each issue, provide:
- Description of problem
- Why it's an issue
- How to fix it
- Code example if applicable
Validation Examples
Skill Validation
Input: skills/my-skill.md
Checks:
✅ YAML frontmatter valid
✅ Name: my-skill (kebab-case)
✅ Version: 1.0.0 (semver)
✅ Description present
⚠️ No triggers defined
⚠️ Missing "When to Use" section
✅ Has examples
✅ 342 lines (under 500)
❌ Contains TODO on line 45
❌ Uses generic label "helper" in title
Report:
Errors (2):
1. Line 45: TODO found - remove before publishing
2. Line 12: Generic label "helper" - be more specific
Warnings (2):
1. No triggers defined - skill won't auto-activate
2. Missing "When to Use" section - users won't know when to apply
Info (0):
None
Score: 6/10 - Fix errors before publishing
Plugin Validation
Input: my-plugin/
Checks:
✅ plugin.json exists
✅ Valid JSON
✅ Name: my-plugin
✅ Version: 1.0.0
⚠️ No description
❌ Referenced skill "skill-1" not found in skills/
✅ Directory structure correct
⚠️ No README.md
⚠️ No LICENSE file
Report:
Errors (1):
1. plugin.json references "skill-1" but skills/skill-1.md doesn't exist
Warnings (3):
1. plugin.json missing description field
2. README.md not found - add documentation
3. LICENSE file missing - add if distributing publicly
Info (0):
None
Score: 5/10 - Fix errors, address warnings
Validation Rules
Severity Levels
Error (Must Fix):
- Invalid YAML/JSON syntax
- Missing required fields
- Referenced files don't exist
- TODOs in production code
- Security issues in hooks
- Invalid semantic version
Warning (Should Fix):
- Missing recommended fields
- No triggers (skill won't auto-activate)
- Missing documentation sections
- Generic/vague naming
- No examples
- No license (public distribution)
Info (Consider):
- Could improve clarity
- Additional documentation helpful
- Consider progressive disclosure (long skills)
Common Issues
Generic Naming
❌ my-helper
❌ utils-tool
❌ component-stuff
✅ shadcn-component-generator
✅ drizzle-schema-generator
✅ tanstack-query-hook
Missing Triggers
❌ Missing entirely
✅ triggers:
keywords: [specific, technical, terms]
patterns: ["regex.*patterns"]
TODOs in Production
❌ ## Feature X
TODO: Implement this later
✅ ## Feature X
Complete implementation
Vague Descriptions
❌ "Helps with things"
❌ "Utility for stuff"
✅ "Generate type-safe API clients from OpenAPI schemas"
✅ "Validate React components for WCAG AAA accessibility"
Validation Output Format
Component: [name]
Type: [skill|command|agent|hook|plugin]
Location: [file path]
Structure: [✅|⚠️|❌]
Content: [✅|⚠️|❌]
Best Practices: [✅|⚠️|❌]
Errors (must fix): [count]
1. [description]
2. [description]
Warnings (should fix): [count]
1. [description]
2. [description]
Info (consider): [count]
1. [description]
Overall Score: [0-10]
Status: [Ready|Needs work|Not ready]
Recommendations:
- [specific action 1]
- [specific action 2]
Validation Best Practices
- Validate Early: Check during development, not just before publishing
- Fix Errors First: Don't publish with errors
- Address Warnings: They indicate best practice violations
- Review Info: Consider suggestions for improvements
- Re-validate: After fixes, validate again
Integration
With Hooks
Auto-validate before commits:
{
"name": "validate-before-commit",
"event": "user-prompt-submit",
"when": "before",
"command": "claude-validate --skills",
"filter": {
"promptPattern": "commit"
}
}
With Commands
Create validation command:
---
description: Validate all skills in current plugin
---
# Validate Skills
Run skill-validator on all SKILL.md files in current plugin.
## Usage
\`\`\`
/validate-skills
\`\`\`
With CI/CD
Add to GitHub Actions:
- name: Validate Skills
run: claude-validate --all --strict