--- description: Validate plugin structure, manifest, and component files for common issues --- # Validate Plugin Comprehensive validation of plugin structure, configuration, and components. ## Prerequisites - Must be run from a plugin root directory (containing `.claude-plugin/plugin.json`) ## Instructions ### What This Command Does Performs a thorough validation of the plugin: 1. **Structure validation**: Check directories and files exist 2. **Manifest validation**: Verify plugin.json is valid and complete 3. **Component validation**: Check commands, agents, skills, hooks 4. **Path validation**: Ensure all paths are relative and resolve correctly 5. **Naming validation**: Verify kebab-case conventions 6. **Common issues**: Flag typical mistakes ### Validation Steps #### 1. Check Core Structure Verify these exist: ``` □ .claude-plugin/plugin.json □ At least one component directory (commands/, agents/, skills/, or hooks/) ``` #### 2. Validate plugin.json Read and check: - **Valid JSON**: Can parse without errors - **Required fields present**: `name`, `version`, `description` - **Name format**: kebab-case (lowercase with hyphens) - **Version format**: Valid SemVer (e.g., "1.0.0") - **Paths are relative**: Start with `./` not `/` - **Author format**: If present, valid object or string Example valid structure: ```json { "name": "plugin-name", "version": "1.0.0", "description": "What the plugin does", "author": { "name": "Your Name" }, "license": "MIT", "keywords": ["keyword1"], "commands": "./commands/", "agents": "./agents/", "hooks": "./hooks/hooks.json" } ``` #### 3. Validate Component Paths For each path in plugin.json: - **commands**: Check directory exists, contains .md files - **agents**: Check directory exists, contains .md files - **skills**: Check directory exists, contains skill folders with SKILL.md - **hooks**: Check file exists and is valid JSON #### 4. Validate Commands For each file in `commands/`: - **File extension**: Must be .md - **Frontmatter present**: Has `---` delimiters - **Description field**: Frontmatter includes `description` - **Naming**: kebab-case filename - **Content**: Not empty after frontmatter #### 5. Validate Skills For each directory in `skills/`: - **SKILL.md exists**: In uppercase - **Frontmatter present**: Has `---` delimiters - **Required fields**: `name` and `description` present - **Name matches directory**: Exact match, kebab-case - **Description is specific**: Includes when/why to use #### 6. Validate Agents For each file in `agents/`: - **File extension**: Must be .md - **Frontmatter present**: Has `---` delimiters - **Description field**: Present in frontmatter - **Naming**: kebab-case filename - **Content**: Not empty after frontmatter #### 7. Validate Hooks If `hooks.json` exists: - **Valid JSON**: Can parse without errors - **Proper structure**: Has `hooks` object - **Event names**: Valid events (PreToolUse, PostToolUse, etc.) - **Hook commands**: Scripts use `${CLAUDE_PLUGIN_ROOT}` - **Scripts exist**: Referenced scripts are present - **Scripts executable**: Have execute permissions ### Validation Output Format Report findings in this structure: ``` 🔍 Validating plugin: ✅ Structure ✓ .claude-plugin/plugin.json exists ✓ Component directories present ✅ Manifest (plugin.json) ✓ Valid JSON ✓ Required fields: name, version, description ✓ Name format: kebab-case ✓ Version format: SemVer ✓ Paths are relative ✅ Commands (3 files) ✓ commands/init.md ✓ commands/validate.md ✓ commands/test-local.md ✅ Skills (1 skill) ✓ skills/plugin-authoring/SKILL.md - name matches directory: ✓ - description present: ✓ ✅ Agents (1 agent) ✓ agents/plugin-reviewer.md ✅ Hooks ✓ hooks/hooks.json is valid ✓ Scripts exist and are executable ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Validation passed: 0 errors, 0 warnings ``` ### Error Reporting If issues are found, report clearly: ``` ❌ Errors Found 1. Manifest: plugin.json missing required field "version" Fix: Add "version": "1.0.0" to .claude-plugin/plugin.json 2. Command: commands/myCommand.md uses camelCase Fix: Rename to commands/my-command.md (kebab-case) 3. Skill: skills/MySkill/SKILL.md name doesn't match directory Fix: Change frontmatter 'name' to "my-skill" (matches directory) ⚠️ Warnings 1. No README.md found Suggestion: Create README.md with usage documentation 2. No keywords in plugin.json Suggestion: Add keywords array for discoverability ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ❌ Validation failed: 3 errors, 2 warnings ``` ## Validation Categories ### Critical (Must Fix) - Missing plugin.json - Invalid JSON in config files - Missing required fields (name, version, description) - Absolute paths in configuration - Component name mismatches (skill name ≠ directory) - Non-executable hook scripts ### Warnings (Should Fix) - Missing README.md - No keywords in plugin.json - Empty component directories - Commands missing argument-hint - Skills without progressive disclosure structure ### Suggestions (Nice to Have) - Add CHANGELOG.md - Include examples directory - Add more descriptive descriptions - Use consistent naming patterns ## Common Issues Detected ### Issue: Paths Not Relative ```json ❌ "commands": "/Users/you/plugin/commands/" ✅ "commands": "./commands/" ``` ### Issue: Name Mismatch ``` Directory: skills/code-review/ Frontmatter: name: codeReview ❌ Names don't match Fix: Change frontmatter to name: code-review ``` ### Issue: Missing Frontmatter ```markdown # My Command Instructions... ``` ❌ No frontmatter with description ```markdown --- description: What this command does --- # My Command Instructions... ``` ✅ Has required frontmatter ### Issue: Hook Script Not Executable ```bash $ ls -l scripts/validate.sh -rw-r--r-- validate.sh ❌ Not executable $ chmod +x scripts/validate.sh ✅ Now executable ``` ## Validation Checklist Complete checklist used for validation: ``` Structure: □ .claude-plugin/plugin.json exists □ At least one component directory present □ README.md exists Manifest: □ Valid JSON syntax □ name field: present, kebab-case □ version field: present, valid SemVer □ description field: present, non-empty □ Paths are relative (start with ./) □ Referenced paths exist Commands: □ .md extension □ Frontmatter with description □ kebab-case naming □ Non-empty content Skills: □ Directory structure (skill-name/SKILL.md) □ SKILL.md in uppercase □ Frontmatter with name and description □ Name matches directory (exact, kebab-case) Agents: □ .md extension □ Frontmatter with description □ kebab-case naming □ Non-empty content Hooks: □ hooks.json valid JSON □ Proper structure (hooks object) □ Valid event names □ Scripts use ${CLAUDE_PLUGIN_ROOT} □ Scripts exist □ Scripts are executable (chmod +x) ``` ## After Validation ### If Validation Passes ``` ✅ Plugin is valid and ready for testing! Next steps: 1. Test locally: /plugin-development:test-local 2. Create dev marketplace and install 3. Test all commands and features 4. Register in team marketplace when ready ``` ### If Validation Fails ``` ❌ Please fix the errors above before testing. Need help? - Review error messages for specific fixes - Check best practices: /plugin-development:help - Common issues documented in examples ``` ## Example Usage **Input**: `/plugin-development:validate` **Output**: ``` 🔍 Validating plugin: my-awesome-plugin ✅ All checks passed ✓ Structure correct ✓ Manifest valid ✓ 5 commands validated ✓ 2 skills validated ✓ 1 agent validated ✓ Hooks configured correctly ✅ Plugin ready for testing! ``` ## Best Practices 1. **Validate often**: Run before testing or commits 2. **Fix errors first**: Address critical issues before warnings 3. **Read messages carefully**: Each error includes fix instructions 4. **Use debug mode**: Run `claude --debug` for deep inspection 5. **Incremental fixes**: Fix and re-validate one issue at a time ## Notes - This command only reads files (no modifications) - Validation is comprehensive but not exhaustive - Some issues may only appear during runtime testing - Always test in a dev marketplace after validation passes