gh-resolve-io-prism/skills/skill-builder/scripts

Claude Code Skill Validator

A comprehensive validation tool for Claude Code skills that checks structure, format, and best practices compliance.

Installation

cd scripts
npm install

Usage

Validate a skill directory

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

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