148 lines
3.8 KiB
Markdown
148 lines
3.8 KiB
Markdown
# Claude Code Skill Validator
|
||
|
||
A comprehensive validation tool for Claude Code skills that checks structure, format, and best practices compliance.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
cd scripts
|
||
npm install
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Validate a skill directory
|
||
|
||
```bash
|
||
node validate-skill.js /path/to/skill-directory
|
||
|
||
# Examples:
|
||
node validate-skill.js ~/.claude/skills/my-skill
|
||
node validate-skill.js .claude/skills/my-skill
|
||
node validate-skill.js . # validate current directory
|
||
```
|
||
|
||
### Help
|
||
|
||
```bash
|
||
node validate-skill.js --help
|
||
```
|
||
|
||
## What It Validates
|
||
|
||
### ✓ YAML Frontmatter
|
||
- Opening `---` on line 1
|
||
- Closing `---` before content
|
||
- Valid YAML syntax
|
||
- No tabs, proper indentation
|
||
|
||
### ✓ Required Fields
|
||
- `name`: Skill name
|
||
- `description`: What the skill does and when to use it
|
||
|
||
### ✓ Optional Fields
|
||
- `allowed-tools`: Tool restrictions (if present)
|
||
- `version`: Skill version
|
||
|
||
### ✓ Description Quality
|
||
- Specificity (not too vague)
|
||
- Usage triggers ("when to use")
|
||
- Length (20-150 tokens recommended)
|
||
|
||
### ✓ Token Budgets
|
||
- Metadata: ~100 tokens (warning at 150+)
|
||
- Body: <2k tokens recommended (error at 5k+)
|
||
- Provides estimates for all sections
|
||
|
||
### ✓ File Structure
|
||
- Only `SKILL.md` in root directory
|
||
- No stray `.md` files in root
|
||
- `/reference/` folder for detailed docs
|
||
- `/scripts/` folder detection
|
||
|
||
### ✓ Path Format
|
||
- All paths use forward slashes (cross-platform)
|
||
- No Windows-style backslashes
|
||
|
||
### ✓ Reference Links
|
||
- All `./reference/*.md` links are valid
|
||
- Referenced files actually exist
|
||
|
||
## Exit Codes
|
||
|
||
- `0`: Validation passed (may have warnings)
|
||
- `1`: Validation failed with errors
|
||
|
||
## Output
|
||
|
||
The validator provides:
|
||
|
||
- **✓ Success messages** (green): Validation passed
|
||
- **⚠ Warnings** (yellow): Best practice recommendations
|
||
- **✗ Errors** (red): Must be fixed before deployment
|
||
- **ℹ Info** (cyan): Informational messages
|
||
|
||
## Example Output
|
||
|
||
```
|
||
╔════════════════════════════════════════════╗
|
||
║ Claude Code Skill Validator v1.0.0 ║
|
||
╚════════════════════════════════════════════╝
|
||
|
||
Validating skill at: /path/to/skill
|
||
|
||
[1/8] Validating directory...
|
||
✓ Skill directory exists
|
||
|
||
[2/8] Checking for SKILL.md...
|
||
✓ SKILL.md exists
|
||
|
||
[3/8] Validating YAML frontmatter...
|
||
✓ Valid YAML frontmatter delimiters found
|
||
✓ YAML syntax is valid
|
||
|
||
...
|
||
|
||
═══════════════════════════════════════════
|
||
VALIDATION REPORT
|
||
═══════════════════════════════════════════
|
||
|
||
✓ All validations passed! Skill structure is excellent.
|
||
```
|
||
|
||
## Integration with Skill Development
|
||
|
||
This validator is designed to work with the skill-builder skill's development process:
|
||
|
||
1. **During development**: Run validation frequently to catch issues early
|
||
2. **Before testing**: Ensure structure is correct
|
||
3. **Before deployment**: Final validation check
|
||
4. **CI/CD integration**: Use exit codes for automated checks
|
||
|
||
## Common Issues and Fixes
|
||
|
||
### Error: "Markdown files found in root"
|
||
**Fix**: Move all `.md` files (except `SKILL.md`) to `/reference/` folder
|
||
|
||
### Warning: "Description may be too vague"
|
||
**Fix**: Add specific triggers like "Use when..." or "For [specific use case]"
|
||
|
||
### Warning: "Body is over 2k tokens"
|
||
**Fix**: Move detailed content to files in `/reference/` folder
|
||
|
||
### Error: "Referenced file does not exist"
|
||
**Fix**: Ensure all linked files exist at the specified path
|
||
|
||
## Based on Official Documentation
|
||
|
||
This validator implements all requirements from:
|
||
- https://anthropic.mintlify.app/en/docs/claude-code/skills
|
||
|
||
## Version
|
||
|
||
v1.0.0 - Initial release
|
||
|
||
## License
|
||
|
||
MIT
|