Initial commit
This commit is contained in:
Zhongwei Li
376
commands/validate/plugin.md
Normal file
376
commands/validate/plugin.md
Normal file
@@ -0,0 +1,376 @@
|
||||
---
|
||||
name: validate:plugin
|
||||
description: Validate Claude Code plugin against official guidelines
|
||||
delegates-to: autonomous-agent:orchestrator
|
||||
---
|
||||
|
||||
# Validate Claude Plugin
|
||||
|
||||
Comprehensive validation for Claude Code plugins against official development guidelines to prevent installation failures and ensure marketplace compatibility.
|
||||
|
||||
## Command: `/validate:plugin`
|
||||
|
||||
Validates the current plugin against Claude Code official guidelines, checking for common installation failures, compatibility issues, and marketplace requirements.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Plugin Manifest Validation**: Validates .claude-plugin/plugin.json against Claude Code schema requirements
|
||||
2. **Directory Structure Check**: Ensures proper plugin directory layout and required files
|
||||
3. **File Format Compliance**: Validates Markdown files with YAML frontmatter
|
||||
4. **Command Execution Validation**: Checks agent delegation and command-to-agent mappings
|
||||
5. **Installation Readiness**: Checks for common installation blockers
|
||||
6. **Cross-Platform Compatibility**: Validates plugin works on Windows, Linux, and Mac
|
||||
|
||||
### Command Execution Validation Details
|
||||
|
||||
The validator now checks for command execution issues that cause runtime failures:
|
||||
|
||||
**Agent Delegation Validation**:
|
||||
- Verifies all command frontmatter includes proper `delegates-to` field
|
||||
- Validates referenced agents exist in the `agents/` directory
|
||||
- Checks agent identifiers use correct prefix format (`autonomous-agent:name`)
|
||||
- Ensures command documentation matches delegation targets
|
||||
|
||||
**Common Command Execution Failures Detected**:
|
||||
- Missing `delegates-to` field in command YAML frontmatter
|
||||
- Agent names without `autonomous-agent:` prefix
|
||||
- References to non-existent agent files
|
||||
- Mismatched delegation between documentation and frontmatter
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
### Critical Issues (Installation Blockers)
|
||||
- Missing or invalid plugin.json manifest
|
||||
- Invalid JSON syntax in manifest
|
||||
- Missing required fields (name, version, description, author)
|
||||
- Invalid version format (must be x.y.z semantic versioning)
|
||||
- Non-UTF-8 file encoding
|
||||
- Missing .claude-plugin directory
|
||||
|
||||
### Command Execution Issues (Runtime Failures)
|
||||
- Invalid agent delegation references in commands
|
||||
- Missing or incorrect agent identifiers
|
||||
- Commands that reference non-existent agents
|
||||
- Broken command-to-agent mappings
|
||||
- Missing `delegates-to` field in command frontmatter
|
||||
|
||||
### Warnings (Non-Critical)
|
||||
- Long file paths (Windows limit 260 characters)
|
||||
- Missing optional YAML frontmatter fields
|
||||
- Inconsistent line endings
|
||||
- Very long or short descriptions
|
||||
- Agent names without proper prefixes in documentation
|
||||
|
||||
### Quality Score
|
||||
- **100**: Perfect - No issues found
|
||||
- **90-99**: Ready - Minor warnings only
|
||||
- **70-89**: Usable - Some fixes recommended
|
||||
- **< 70**: Needs fixes before release
|
||||
|
||||
## Usage
|
||||
|
||||
### Quick Validation
|
||||
```bash
|
||||
/validate:plugin
|
||||
```
|
||||
|
||||
### Strict Validation (treat warnings as errors)
|
||||
```bash
|
||||
/validate:plugin --strict
|
||||
```
|
||||
|
||||
### Validate Specific Plugin Directory
|
||||
```bash
|
||||
/validate:plugin --dir /path/to/plugin
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
### Successful Validation (Perfect)
|
||||
```
|
||||
============================================================
|
||||
VALIDATE CLAUDE PLUGIN RESULTS
|
||||
============================================================
|
||||
|
||||
[+] Plugin Validation PASSED - Ready for Release!
|
||||
|
||||
Validation Summary:
|
||||
+- Plugin Manifest: [OK] Valid JSON schema
|
||||
+- Directory Structure: [OK] Compliant layout
|
||||
+- File Formats: [OK] Valid Markdown/YAML
|
||||
+- Installation Readiness: [OK] No blockers
|
||||
+- Cross-Platform Compatibility: [OK] Ready for all platforms
|
||||
|
||||
Quality Score: 100/100 (Perfect)
|
||||
Detailed report: .claude/data/reports/validate-claude-plugin-2025-10-23.md
|
||||
Completed in 1.2 minutes
|
||||
|
||||
[+] Assessment stored in pattern database for dashboard monitoring
|
||||
[+] Plugin is fully compliant with Claude Code guidelines
|
||||
Ready for immediate distribution and installation
|
||||
```
|
||||
|
||||
### Issues Found
|
||||
```
|
||||
============================================================
|
||||
VALIDATE CLAUDE PLUGIN RESULTS
|
||||
============================================================
|
||||
|
||||
[WARN]️ Plugin Validation Issues Found
|
||||
|
||||
📊 Validation Summary:
|
||||
+- Plugin Manifest: ❌ 2 critical issues
|
||||
+- Directory Structure: ✅ Compliant layout
|
||||
+- File Formats: [WARN]️ 3 warnings
|
||||
+- Installation Readiness: ❌ 2 blockers
|
||||
+- Cross-Platform Compatibility: ✅ Ready for all platforms
|
||||
|
||||
🚨 Critical Issues (Installation Blockers):
|
||||
* Missing required field: version
|
||||
* Invalid JSON syntax: trailing comma in plugin.json
|
||||
* File encoding error: agents/orchestrator.md (not UTF-8)
|
||||
|
||||
[WARN]️ Command Execution Issues (Runtime Failures):
|
||||
* Invalid agent delegation: commands/quality-check.md references 'orchestrator' (should be 'autonomous-agent:orchestrator')
|
||||
* Missing delegates-to field: commands/auto-analyze.md lacks agent delegation specification
|
||||
* Non-existent agent: commands/example.md references 'missing-agent' (file not found)
|
||||
|
||||
[WARN]️ Warnings:
|
||||
* YAML frontmatter missing in 2 agent files
|
||||
* Long file paths (Windows limit): 3 files
|
||||
* Description too short (< 10 chars)
|
||||
|
||||
🔧 Auto-Fix Available:
|
||||
* JSON syntax errors: Can be automatically corrected
|
||||
* Missing required fields: Can be added with defaults
|
||||
* File encoding: Can be converted to UTF-8
|
||||
* Agent delegation errors: Can auto-correct prefixes and add missing fields
|
||||
|
||||
🛠️ Command Execution Fixes Applied:
|
||||
* Fixed commands/quality-check.md: Added `delegates-to: autonomous-agent:orchestrator`
|
||||
* Auto-corrected agent identifier: `orchestrator` -> `autonomous-agent:orchestrator`
|
||||
* Updated command documentation: Explicit agent references with proper prefixes
|
||||
|
||||
🎯 Quality Score: 65/100 (Needs Fixes)
|
||||
|
||||
💡 Recommendations:
|
||||
1. [HIGH] Fix JSON syntax in plugin.json
|
||||
2. [HIGH] Add missing version field (use semantic versioning)
|
||||
3. [HIGH] Convert files to UTF-8 encoding
|
||||
4. [MED] Add missing YAML frontmatter to agents
|
||||
5. [LOW] Reduce file path lengths
|
||||
|
||||
📄 Detailed report: .claude/data/reports/validate-claude-plugin-2025-10-23.md
|
||||
⏱ Completed in 1.5 minutes
|
||||
|
||||
❌ Plugin needs fixes before release
|
||||
Run recommended fixes and re-validate
|
||||
```
|
||||
|
||||
## Files Created
|
||||
|
||||
The validation command creates detailed reports in:
|
||||
|
||||
1. **Console Output**: Concise summary with key findings
|
||||
2. **Detailed Report**: `.claude/data/reports/validate-claude-plugin-YYYY-MM-DD.md`
|
||||
3. **JSON Report**: Machine-readable validation results
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### Pre-Release Checklist
|
||||
```bash
|
||||
# Required validation before any release
|
||||
/validate:plugin --strict
|
||||
|
||||
# Only proceed if validation passes
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ Ready for release"
|
||||
else
|
||||
echo "❌ Fix issues before release"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Continuous Integration
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Validate Claude Plugin
|
||||
run: |
|
||||
/validate:plugin --strict
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Plugin validation failed - blocking release"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# During development
|
||||
make validate-plugin # Custom command that runs validation
|
||||
|
||||
# Before committing changes
|
||||
git add .
|
||||
git commit -m "Update plugin (validated: ✅)"
|
||||
```
|
||||
|
||||
## Common Installation Failure Prevention
|
||||
|
||||
The validator specifically targets the most common causes of plugin installation failures:
|
||||
|
||||
### 1. JSON Syntax Errors
|
||||
```json
|
||||
// ❌ INVALID (trailing comma)
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
}
|
||||
|
||||
// ✅ VALID
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Missing Required Fields
|
||||
```json
|
||||
// ❌ MISSING VERSION
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "A great plugin"
|
||||
}
|
||||
|
||||
// ✅ COMPLETE
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "A great plugin",
|
||||
"author": "Developer Name"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. File Encoding Issues
|
||||
```bash
|
||||
# Check file encoding
|
||||
file .claude-plugin/plugin.json
|
||||
|
||||
# Convert to UTF-8 if needed
|
||||
iconv -f ISO-8859-1 -t UTF-8 input.txt > output.txt
|
||||
```
|
||||
|
||||
### 4. Directory Structure
|
||||
```
|
||||
my-plugin/
|
||||
+-- .claude-plugin/
|
||||
| +-- plugin.json # REQUIRED
|
||||
+-- agents/ # OPTIONAL
|
||||
+-- skills/ # OPTIONAL
|
||||
+-- commands/ # OPTIONAL
|
||||
+-- lib/ # OPTIONAL
|
||||
```
|
||||
|
||||
## Marketplace Compatibility
|
||||
|
||||
The validation ensures compatibility with Claude Code plugin marketplaces:
|
||||
|
||||
### Installation Methods Supported
|
||||
- ✅ GitHub repository URLs
|
||||
- ✅ Git repository URLs
|
||||
- ✅ Local directory paths
|
||||
- ✅ Team distribution sources
|
||||
- ✅ Marketplace listing files
|
||||
|
||||
### Requirements Met
|
||||
- ✅ JSON manifest schema compliance
|
||||
- ✅ Semantic versioning format
|
||||
- ✅ UTF-8 encoding throughout
|
||||
- ✅ Cross-platform file paths
|
||||
- ✅ Proper directory structure
|
||||
- ✅ Valid file formats
|
||||
|
||||
## Error Recovery
|
||||
|
||||
### Auto-Fix Capabilities
|
||||
The validator can automatically correct many common issues:
|
||||
|
||||
1. **JSON Syntax**: Remove trailing commas, fix quotes
|
||||
2. **Missing Fields**: Add defaults (version: "1.0.0", author: "Unknown")
|
||||
3. **File Encoding**: Convert to UTF-8 automatically
|
||||
4. **Line Endings**: Normalize line endings for platform
|
||||
5. **Agent Delegation**: Auto-correct agent identifier prefixes (`orchestrator` -> `autonomous-agent:orchestrator`)
|
||||
6. **Command Frontmatter**: Add missing `delegates-to` fields based on command content analysis
|
||||
7. **Agent Mapping**: Verify and fix command-to-agent mappings by cross-referencing agents directory
|
||||
|
||||
### Manual Fixes Required
|
||||
1. **Structural Issues**: Directory reorganization
|
||||
2. **Content Issues**: Improve documentation quality
|
||||
3. **Naming Conflicts**: Resolve duplicate names
|
||||
4. **Version Conflicts**: Semantic versioning corrections
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Validation Failures
|
||||
|
||||
**Error**: "Missing plugin manifest"
|
||||
- **Cause**: No `.claude-plugin/plugin.json` file
|
||||
- **Fix**: Create manifest with required fields
|
||||
|
||||
**Error**: "Invalid JSON syntax"
|
||||
- **Cause**: Syntax errors in plugin.json
|
||||
- **Fix**: Use JSON linter, check for trailing commas
|
||||
|
||||
**Error**: "Missing required fields"
|
||||
- **Cause**: Required JSON fields absent
|
||||
- **Fix**: Add name, version, description, author fields
|
||||
|
||||
**Error**: "File encoding error"
|
||||
- **Cause**: Non-UTF-8 encoded files
|
||||
- **Fix**: Convert all files to UTF-8 encoding
|
||||
|
||||
**Error**: "Agent type not found" (Runtime Command Failure)
|
||||
- **Cause**: Command references incorrect agent identifier
|
||||
- **Example**: `/quality-check` tries to delegate to `orchestrator` instead of `autonomous-agent:orchestrator`
|
||||
- **Fix**: Update command frontmatter with correct `delegates-to: autonomous-agent:agent-name`
|
||||
|
||||
**Error**: "Missing delegates-to field"
|
||||
- **Cause**: Command YAML frontmatter lacks delegation specification
|
||||
- **Fix**: Add `delegates-to: autonomous-agent:agent-name` to command frontmatter
|
||||
|
||||
**Error**: "Command execution failed"
|
||||
- **Cause**: Referenced agent file doesn't exist in `agents/` directory
|
||||
- **Fix**: Create missing agent file or update delegation to existing agent
|
||||
|
||||
### Getting Help
|
||||
|
||||
```bash
|
||||
# Detailed validation with debugging
|
||||
/validate:plugin --debug
|
||||
|
||||
# Check specific file
|
||||
/validate:plugin --file .claude-plugin/plugin.json
|
||||
|
||||
# Show validation rules
|
||||
/validate:plugin --show-rules
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
1. **Create Plugin Structure**: Follow standard layout
|
||||
2. **Write Manifest**: Complete all required fields
|
||||
3. **Add Content**: Agents, skills, commands
|
||||
4. **Validate**: Run `/validate:plugin`
|
||||
5. **Fix Issues**: Address any problems found
|
||||
6. **Re-validate**: Ensure all issues resolved
|
||||
7. **Release**: Publish with confidence
|
||||
|
||||
### Quality Assurance
|
||||
- Run validation before every commit
|
||||
- Use `--strict` mode for pre-release checks
|
||||
- Monitor validation scores over time
|
||||
- Keep documentation up to date
|
||||
- Test on multiple platforms
|
||||
|
||||
---
|
||||
|
||||
This validation command ensures your Claude Code plugin meets official guidelines and will install successfully across all supported platforms and marketplace types.
|
||||
Reference in New Issue
Block a user