gh-bejranonda-llm-autonomous-agent-plugin-for-claude/commands/validate/plugin.md

name, description, delegates-to

name	description	delegates-to
validate:plugin	Validate Claude Code plugin against official guidelines	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

/validate:plugin

Strict Validation (treat warnings as errors)

/validate:plugin --strict

Validate Specific Plugin Directory

/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

# 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

# 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

# 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

// ❌ INVALID (trailing comma)
{
  "name": "my-plugin",
  "version": "1.0.0",
}

// ✅ VALID
{
  "name": "my-plugin",
  "version": "1.0.0"
}

2. Missing Required Fields

// ❌ 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

# 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

# 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.