---
description: Comprehensive validation of Claude Code plugin.json with structure checks
argument-hint: [path-to-plugin-directory]
allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*), Read, Glob
---

# Validate Plugin

You are a plugin validation specialist. Your task is to comprehensively validate a Claude Code plugin for quality, structure, and standards compliance.

## Process

### 1. Locate Plugin Directory

Determine the plugin path:
- If user provided an argument ($1): Use that path
- If no argument: Use current directory
- Look for `plugin.json` at plugin root to confirm it's a plugin

### 2. Run Validation Script

Execute the validation script located at:
```
${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-full.sh [path]
```

The script will validate:
- **Structure**: Directory layout, required files
- **Metadata**: plugin.json schema compliance
- **Components**: Commands, agents, hooks validation
- **Quality**: Documentation, completeness
- **Security**: No secrets, safe permissions

### 3. Interpret Results

The script outputs:
- ✅ Success messages for valid components
- ❌ Errors for critical issues (must fix)
- ⚠️ Warnings for recommended improvements
- ℹ️ Info for optional suggestions

Quality Score Categories:
- 90-100: Excellent ⭐⭐⭐⭐⭐ (publication-ready)
- 75-89: Good ⭐⭐⭐⭐ (minor improvements)
- 60-74: Fair ⭐⭐⭐ (needs work)
- 40-59: Needs Improvement ⭐⭐ (significant issues)
- 0-39: Poor ⭐ (not ready)

### 4. Provide Detailed Feedback

For each issue found, provide:
1. **What's wrong**: Clear explanation
2. **Why it matters**: Impact on functionality/quality
3. **How to fix**: Specific remediation steps
4. **Examples**: Show correct format

### 5. Prioritize Issues

Categorize findings:
- **Critical**: Prevents installation or functionality
- **Important**: Affects quality or user experience
- **Recommended**: Improves discoverability or maintenance
- **Optional**: Nice-to-have enhancements

### 6. Generate Action Plan

Create a numbered list of fixes in priority order:
1. Fix critical errors first
2. Address important warnings
3. Implement recommended improvements
4. Consider optional enhancements

## Validation Checklist

### Structure Validation
- [ ] `plugin.json` exists at plugin root
- [ ] `plugin.json` in correct location
- [ ] Component directories present (if used)
- [ ] README.md exists and complete
- [ ] LICENSE file present

### Metadata Validation
- [ ] Required fields: name, version, description, author, license
- [ ] Name: lowercase-hyphen format
- [ ] Version: semantic versioning (X.Y.Z)
- [ ] Description: 50-200 characters
- [ ] Author: valid format (string or object)
- [ ] License: valid identifier

### Component Validation
- [ ] Command files (*.md) have valid frontmatter
- [ ] Agent files have required fields (name, description)
- [ ] Hooks JSON is valid (if present)
- [ ] MCP configuration valid (if present)
- [ ] All referenced files exist

### Quality Validation
- [ ] README has minimum sections
- [ ] No TODO or placeholder content
- [ ] Keywords present (3-7 recommended)
- [ ] CHANGELOG.md exists (recommended)

### Security Validation
- [ ] No .env files with real credentials
- [ ] No API keys or tokens in code
- [ ] No suspicious file permissions
- [ ] HTTPS for external URLs

## Example Output Structure

```
🔍 Validating Plugin: my-awesome-plugin

Structure:
✅ plugin.json exists at plugin root
✅ plugin.json schema valid
✅ Commands directory present (2 commands found)
⚠️  Agents directory missing (optional)
✅ README.md present and complete
❌ LICENSE file missing

Metadata:
✅ Name: my-awesome-plugin (valid format)
✅ Version: 1.0.0 (valid semver)
✅ Description: "A comprehensive plugin..." (132 chars)
❌ Author field missing

Components:
✅ commands/action.md - valid frontmatter
❌ commands/broken.md - missing description

Security:
✅ No exposed secrets
⚠️  File .env.example found (verify no real values)

Quality Score: 65/100 - Fair ⭐⭐⭐

Critical Issues (must fix):
1. Add LICENSE file (MIT recommended)
2. Add author field to plugin.json
3. Fix commands/broken.md frontmatter

Recommendations:
1. Add CHANGELOG.md for version tracking
2. Consider adding agents directory
3. Review .env.example for sensitive data

Status: NEEDS FIXES before publication
```

## Error Handling

Provide helpful guidance for common issues:

**Missing plugin.json**:
```
Error: No plugin.json found at plugin root

This is required for all Claude Code plugins.

To fix:
1. Create plugin.json at plugin root directory
2. Add plugin.json with required fields
3. See: .claude/docs/plugins/plugins-reference.md
```

**Invalid JSON**:
```
Error: Invalid JSON syntax in plugin.json
Line 5: Expected comma or closing brace

To fix:
1. Validate JSON: cat plugin.json | python3 -m json.tool
2. Fix syntax errors
3. Ensure proper formatting
```

**Missing Required Field**:
```
Error: Missing required field: 'author'

The author field identifies the plugin creator.

To fix - Add to plugin.json:
"author": {
  "name": "Your Name",
  "email": "you@example.com"
}

Or use string format:
"author": "Your Name"
```

## References

- Plugin schema: `.claude/docs/plugins/plugins-reference.md`
- OpenPlugins standards: `open-plugins/CONTRIBUTING.md`
- Best practices: `CLAUDE.md` in project