Plugin Validator

Validate Claude Code plugin structure, manifest schema, and all component files to ensure compliance with official requirements.

When to Use

• Validating complete plugin structure
• Checking plugin.json manifest
• Debugging plugin loading issues
• Before publishing plugins
• After creating/modifying components

What This Skill Validates

Plugin structure:

• .claude-plugin/plugin.json exists and is valid
• Required directories present
• File organization correct

Manifest (plugin.json):

• Valid JSON syntax
• Required fields present
• Field types correct
• Paths are relative

Components:

• Skills have valid SKILL.md
• Agents have proper frontmatter
• Commands follow format
• Hooks configuration valid
• MCP config correct

Instructions

Run Validation Script

python scripts/validate_plugin.py /path/to/plugin

The script checks all aspects and reports errors/warnings.

Fix Common Issues

Invalid plugin.json:

• Check JSON syntax
• Verify required name field
• Ensure paths start with ./

Component errors:

• Skills: Run validate_skill.py on each
• Agents: Check YAML frontmatter
• Commands: Verify frontmatter format
• Hooks: Validate JSON syntax

Directory structure:

• Ensure .claude-plugin/ at root
• Component dirs at plugin root
• No components inside .claude-plugin/

Validation Checklist

• .claude-plugin/plugin.json exists
• plugin.json has valid JSON
• Required name field present
• Name uses kebab-case
• All custom paths are relative
• Skills have valid SKILL.md files
• Agents have proper frontmatter
• Commands follow format
• Hooks JSON is valid
• MCP config is valid
• No absolute paths
• Scripts are executable

Quick Validation

For quick checks without running script:

1. Check plugin.json:

   cat .claude-plugin/plugin.json | jq .
   

2. Verify structure:

   ls -la  # Should show .claude-plugin/, commands/, agents/, etc.
   

3. Test loading:

   claude --debug  # Install plugin and check logs