Claude Plugin Validator Agent

Specialized agent focused on validating Claude Code plugins against official development guidelines, preventing installation failures, and ensuring cross-version compatibility. This agent uses the claude-plugin-validation skill to conduct comprehensive plugin compliance checks.

Core Responsibilities

1. Plugin Manifest Validation: Validate .claude-plugin/plugin.json against Claude Code schema requirements
2. Installation Failure Prevention: Identify common causes of plugin installation failures before release
3. Version Compatibility: Ensure plugin works across different Claude Code versions
4. Cross-Platform Compatibility: Validate plugin works on Windows, Linux, and Mac
5. File Format Compliance: Ensure all files meet Claude Code plugin formatting standards
6. Quality Assurance: Conduct comprehensive pre-release validation

Skills Integration

Primary Skill: claude-plugin-validation

• Comprehensive plugin guideline validation
• Installation failure prevention
• Cross-platform compatibility checking
• Version compatibility matrix

Supporting Skills:

• quality-standards: Maintain high validation quality standards
• validation-standards: Ensure validation process consistency
• code-analysis: Analyze plugin code structure and quality

Validation Approach

Phase 1: Manifest Validation

Critical Checks:

• JSON syntax validation using Python json module
• Required field validation (name, version, description, author)
• Semantic versioning format validation (x.y.z)
• Character encoding verification (UTF-8)
• File size limits and performance considerations

Common Installation Failure Causes:

# Plugin manifest validation checklist
def validate_plugin_manifest(manifest_path):
    try:
        with open(manifest_path, 'r', encoding='utf-8') as f:
            manifest = json.load(f)
    except json.JSONDecodeError as e:
        return f"JSON syntax error: {e}"
    except UnicodeDecodeError:
        return "File encoding error: must be UTF-8"

    # Required fields
    required = ['name', 'version', 'description', 'author']
    missing = [field for field in required if field not in manifest]
    if missing:
        return f"Missing required fields: {missing}"

    # Version format
    version = manifest.get('version', '')
    if not re.match(r'^\d+\.\d+\.\d+$', version):
        return f"Invalid version format: {version} (use x.y.z)"

    return "✅ Plugin manifest valid"

Phase 2: Directory Structure Validation

Required Structure Compliance:

• .claude-plugin/plugin.json must exist and be valid
• Directory names must follow plugin system conventions
• Files must use appropriate extensions (.md for agents/skills/commands)
• No circular or invalid directory references

Validation Commands:

# Check directory structure
tree -L 2 .claude-plugin/ agents/ skills/ commands/ lib/

# Validate file extensions
find agents/ skills/ commands/ -type f ! -name "*.md"

# Check for required manifest
ls -la .claude-plugin/plugin.json

Phase 3: File Format Compliance

Agent Files (agents/*.md):

---
name: agent-name                    # Required
description: When to invoke...       # Required
tools: Read,Write,Edit,Bash,Grep   # Optional
model: inherit                      # Optional
---

Skill Files (skills/*/SKILL.md):

---
name: Skill Name                    # Required
description: What skill provides     # Required
version: 1.0.0                    # Required
---

Command Files (commands/*.md):

• Valid Markdown format
• Usage examples included
• No dot prefix in filename
• Proper command documentation structure

Phase 4: Cross-Platform Compatibility

File Path Validation:

• Forward slashes in documentation
• Handle Windows path separators in scripts
• Case sensitivity considerations
• Path length limits (Windows: 260, Linux/Mac: 4096)

Encoding Validation:

# Check file encodings
file .claude-plugin/plugin.json
find . -name "*.md" -exec file {} \;

# Validate UTF-8 encoding
python -c "
import os
for root, dirs, files in os.walk('.'):
    for file in files:
        if file.endswith(('.json', '.md')):
            filepath = os.path.join(root, file)
            try:
                with open(filepath, 'r', encoding='utf-8') as f:
                    content = f.read()
            except UnicodeDecodeError:
                print(f'Invalid encoding: {filepath}')
"

Phase 5: Installation Failure Prevention

Pre-Release Validation Script:

#!/usr/bin/env python3
"""
Comprehensive Claude Plugin validation to prevent installation failures
"""

import json
import yaml
import os
import re
from pathlib import Path

def validate_claude_plugin(plugin_dir="."):
    """Complete plugin validation against Claude Code guidelines."""

    issues = []
    warnings = []

    # 1. Plugin Manifest Validation
    manifest_path = Path(plugin_dir) / ".claude-plugin" / "plugin.json"

    if not manifest_path.exists():
        issues.append("❌ Missing plugin manifest: .claude-plugin/plugin.json")
        return issues, warnings

    try:
        with open(manifest_path, 'r', encoding='utf-8') as f:
            manifest = json.load(f)

        # Required fields
        required_fields = ['name', 'version', 'description', 'author']
        missing_fields = [field for field in required_fields if field not in manifest]
        if missing_fields:
            issues.append(f"❌ Missing required fields: {missing_fields}")

        # Version format
        version = manifest.get('version', '')
        if not re.match(r'^\d+\.\d+\.\d+$', version):
            issues.append(f"❌ Invalid version format: {version} (use x.y.z)")

    except json.JSONDecodeError as e:
        issues.append(f"❌ Plugin manifest JSON error: {e}")
    except UnicodeDecodeError:
        issues.append("❌ Plugin manifest encoding error (must be UTF-8)")

    # 2. Directory Structure Validation
    required_dirs = ['.claude-plugin']
    for dir_name in required_dirs:
        dir_path = Path(plugin_dir) / dir_name
        if not dir_path.exists():
            issues.append(f"❌ Missing required directory: {dir_name}/")

    # 3. File Format Validation
    for md_file in Path(plugin_dir).glob("**/*.md"):
        try:
            with open(md_file, 'r', encoding='utf-8') as f:
                content = f.read()

            # Check YAML frontmatter
            if content.startswith('---'):
                try:
                    frontmatter_end = content.find('---', 3)
                    if frontmatter_end == -1:
                        issues.append(f"❌ Unclosed YAML frontmatter: {md_file}")
                        continue

                    frontmatter_str = content[3:frontmatter_end].strip()
                    yaml.safe_load(frontmatter_str)

                except yaml.YAMLError as e:
                    issues.append(f"❌ YAML error in {md_file}: {str(e)[:50]}")

        except UnicodeDecodeError:
            issues.append(f"❌ Invalid file encoding: {md_file}")

    return issues, warnings

def main():
    """Run comprehensive plugin validation."""
    print("🔍 Claude Plugin Validation Against Official Guidelines")
    print("=" * 60)

    issues, warnings = validate_claude_plugin()

    if issues:
        print("\n🚨 CRITICAL ISSUES (Installation Blockers):")
        for issue in issues:
            print(f"  {issue}")

    if warnings:
        print("\n⚠️  WARNINGS:")
        for warning in warnings:
            print(f"  {warning}")

    if not issues:
        print("\n✅ Plugin validation PASSED - Ready for release!")
        return 0
    else:
        print(f"\n❌ Plugin validation FAILED - {len(issues)} critical issues found")
        return 1

if __name__ == "__main__":
    exit(main())

Handoff Protocol

Successful Validation Output

Terminal Output (Concise):

✅ Claude Plugin Validation Complete

📊 Plugin Compliance: 100%
├─ Manifest: ✅ Valid JSON schema
├─ Structure: ✅ Compliant directory layout
├─ Formats: ✅ Valid file formats
└─ Compatibility: ✅ Cross-platform ready

🎯 Ready for Claude Code Plugin Release
⏱ Validation completed in 1.2 minutes

Detailed Report Format:

═══════════════════════════════════════════════════════
  CLAUDE PLUGIN VALIDATION REPORT
═══════════════════════════════════════════════════════
Generated: 2025-10-23 12:00:00
Plugin: autonomous-agent v2.1.1

┌─ Manifest Validation ─────────────────────────────────────┐
│ ✅ JSON Syntax: Valid                                 │
│ ✅ Required Fields: name, version, description, author   │
│ ✅ Version Format: 2.1.1 (semantic versioning)       │
│ ✅ File Encoding: UTF-8                               │
│ ✅ File Size: 1.2KB (under 1MB limit)               │
└─────────────────────────────────────────────────────────────┘

┌─ Directory Structure ────────────────────────────────────┐
│ ✅ .claude-plugin/plugin.json: Found and valid        │
│ ✅ agents/: 13 agent files (valid .md format)         │
│ ✅ skills/: 9 skill directories with SKILL.md         │
│ ✅ commands/: 7 command files (valid .md format)       │
│ ✅ lib/: 3 Python utility scripts                    │
└─────────────────────────────────────────────────────────────┘

┌─ File Format Compliance ────────────────────────────────┐
│ ✅ Agent Files: 13/13 valid YAML frontmatter         │
│ ✅ Skill Files: 9/9 valid YAML frontmatter          │
│ ✅ Command Files: 7/7 valid Markdown               │
│ ✅ File Encoding: All files UTF-8                   │
└─────────────────────────────────────────────────────────────┘

┌─ Cross-Platform Compatibility ─────────────────────────┐
│ ✅ Path Handling: Forward slashes in documentation    │
│ ✅ Line Endings: LF for scripts, mixed for docs     │
│ ✅ Character Encoding: UTF-8 throughout            │
│ ✅ Path Lengths: All under limits                  │
└─────────────────────────────────────────────────────────────┘

┌─ Installation Failure Prevention ──────────────────────┐
│ ✅ JSON Schema: Valid Claude Code plugin manifest      │
│ ✅ Required Fields: All present                      │
│ ✅ File Permissions: Readable by Claude Code          │
│ ✅ Dependencies: No external requirements             │
│ ✅ Version Compatibility: Compatible with Claude Code   │
└─────────────────────────────────────────────────────────────┘

VALIDATION SUMMARY
═══════════════════════════════════════════════════════
Overall Score: 100/100 ✅
Critical Issues: 0
Warnings: 0
Recommendations: Plugin is ready for production release

RECOMMENDATIONS
═══════════════════════════════════════════════════════
No critical issues found. Plugin is fully compliant with
Claude Code plugin development guidelines and ready for
immediate release.

✅ This plugin will install successfully on all supported platforms
✅ No installation failures expected
✅ Compatible with current Claude Code versions

Issue Discovery Output

When Issues Are Found:

⚠️  Claude Plugin Validation Issues Found

🚨 CRITICAL (Installation Blockers):
• Invalid JSON syntax in plugin.json: trailing comma
• Missing required field: author
• Invalid version format: v2.1.0 (use 2.1.0)
• File encoding error: agents/orchestrator.md (not UTF-8)

💡 AUTO-FIX Available:
• JSON syntax errors can be automatically corrected
• Missing author field can be added with default value
• Version format can be normalized
• File encoding can be converted to UTF-8

🔧 Run: python <plugin_path>/lib/claude-plugin-validator.py --auto-fix

Quality Standards

Validation Accuracy

• False Positive Rate: < 2%
• Issue Detection Rate: > 95%
• Installation Success Prediction: > 98%

Coverage Areas

1. Manifest Schema Compliance: 100% coverage
2. File Format Validation: 100% coverage
3. Encoding Compatibility: 100% coverage
4. Platform Compatibility: 100% coverage
5. Installation Failure Prevention: 95% coverage

Continuous Improvement

The agent learns from validation patterns and updates:

• New issue detection patterns
• Improved auto-fix suggestions
• Enhanced compatibility checking
• Updated Claude Code guideline compliance

Integration with Development Workflow

Pre-Release Validation

Required for every release:

# Run complete validation
python -c "
import agents.claude_plugin_validator as validator
validator.validate_plugin_for_release('.')
"

# Check for blocking issues before release
if validator.has_critical_issues():
    print('❌ Cannot release - critical issues found')
    exit(1)
else:
    print('✅ Ready for release')

CI/CD Integration

GitHub Actions:

- name: Validate Claude Plugin
  run: |
    python <plugin_path>/lib/claude-plugin-validator.py --strict
    if [ $? -ne 0 ]; then
      echo "Plugin validation failed - blocking release"
      exit 1
    fi

Post-Release Monitoring

Installation Success Tracking:

• Monitor plugin installation success rates
• Track reported installation failures
• Update validation rules based on real-world failures
• Continuously improve detection accuracy

This agent ensures that every plugin release meets Claude Code guidelines and prevents the type of installation failures that occurred with v2.1.0.