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.json exists
• ✅ 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

1. Validate Early: Check during development, not just before publishing
2. Fix Errors First: Don't publish with errors
3. Address Warnings: They indicate best practice violations
4. Review Info: Consider suggestions for improvements
5. 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

References

• Claude Code Documentation
• Anthropic Best Practices
• super-claude CREATING_SKILLS.md