Comprehensive validation system for Claude Code plugins to ensure compliance with official plugin development guidelines and prevent installation failures
Validates Claude Code plugins against official guidelines to prevent installation failures and ensure compatibility.
/plugin marketplace add bejranonda/LLM-Autonomous-Agent-Plugin-for-Claude/plugin install bejranonda-autonomous-agent@bejranonda/LLM-Autonomous-Agent-Plugin-for-ClaudeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides comprehensive validation for Claude Code plugins to ensure they meet official development guidelines, prevent installation failures, and maintain compatibility across different versions. It focuses on critical validation areas that commonly cause plugin breakage.
Use this skill when:
Critical Requirements:
name, version, description, authorx.y.z format (no pre-release identifiers)Validation Checks:
{
"required_fields": ["name", "version", "description", "author"],
"optional_fields": ["repository", "license", "homepage", "keywords"],
"version_pattern": "^\\d+\\.\\d+\\.\\d+$",
"max_file_size": 1048576,
"encoding": "utf-8"
}
Common Issues that Cause Installation Failures:
Required Structure:
plugin-root/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (REQUIRED)
├── agents/ # Agent definitions (optional)
├── skills/ # Skill definitions (optional)
├── commands/ # Command definitions (optional)
└── lib/ # Python utilities (optional)
Validation Rules:
.claude-plugin/plugin.json must exist and be valid JSON.md extension for agents/skills/commandsAgent Files (agents/*.md):
---
name: agent-name
description: When to invoke this agent (action-oriented)
tools: Read,Write,Edit,Bash,Grep,Glob # optional
model: inherit # optional
---
# Agent Title
Core responsibilities...
## Skills Integration
Reference skills by name...
## Approach
Detailed instructions...
## Handoff Protocol
How to return results...
Skill Files (skills/*/SKILL.md):
---
name: Skill Name
description: What this skill provides (200 char max)
version: 1.0.0
---
## Overview
What, when, and why...
## Domain-Specific Sections
2-5 sections with guidelines, examples, standards...
## When to Apply
Trigger conditions...
Command Files (commands/*.md):
## Usage sectionRequired YAML Structure:
---
name: string # Required for agents/skills
description: string # Required for agents/skills
version: string # Required for skills
tools: array # Optional for agents
model: string # Optional for agents
---
YAML Validation Rules:
File Path Handling:
Character Encoding:
Line Ending Compatibility:
git config --global core.autocrlf falseExternal Dependencies:
Claude Code Compatibility:
Pre-Installation Validation:
# Validate plugin before distribution
python -c "
import json
import os
# Check plugin manifest
try:
with open('.claude-plugin/plugin.json', 'r') as f:
manifest = json.load(f)
required = ['name', 'version', 'description', 'author']
missing = [field for field in required if field not in manifest]
if missing:
print(f'Missing required fields: {missing}')
exit(1)
print('✅ Plugin manifest valid')
except Exception as e:
print(f'❌ Plugin manifest error: {e}')
exit(1)
# Check file encoding
for root, dirs, files in os.walk('.'):
for file in files:
if file.endswith(('.json', '.md', '.py')):
filepath = os.path.join(root, file)
try:
with open(filepath, 'r', encoding='utf-8') as f:
f.read()
except UnicodeDecodeError:
print(f'❌ Invalid encoding: {filepath}')
exit(1)
print('✅ File encoding valid')
"
Common Installation Failure Causes:
Claude Code Version Compatibility:
| Plugin Version | Claude Code Support | Notes |
|---|---|---|
| 2.1.0+ | Latest | ✅ Full compatibility |
| 2.0.x | 2024-11+ | ✅ Compatible with auto-fix |
| 1.x.x | Pre-2024-11 | ⚠️ Limited features |
Plugin Breaking Changes:
Pre-Release Validation:
Automated Validation Script:
# Full plugin validation
def validate_plugin(plugin_dir="."):
issues = []
# 1. Manifest validation
manifest_path = os.path.join(plugin_dir, ".claude-plugin", "plugin.json")
if not validate_manifest(manifest_path):
issues.append("Invalid plugin manifest")
# 2. Directory structure
if not validate_structure(plugin_dir):
issues.append("Invalid directory structure")
# 3. File format validation
if not validate_file_formats(plugin_dir):
issues.append("File format issues found")
# 4. Encoding validation
if not validate_encoding(plugin_dir):
issues.append("File encoding issues found")
return issues
# Usage
issues = validate_plugin()
if issues:
print("Validation failed:")
for issue in issues:
print(f" ❌ {issue}")
exit(1)
else:
print("✅ Plugin validation passed")
Debug Steps:
Check Plugin Manifest:
python -m json.tool .claude-plugin/plugin.json
Validate File Encoding:
find . -type f -name "*.md" -exec file {} \;
Check Directory Structure:
tree .claude-plugin/ agents/ skills/ commands/
Test Installation:
# Test in clean directory
mkdir test-plugin && cp -r . test-plugin/
cd test-plugin
# Try installation here
Common Error Solutions:
Manifest Schema Validation:
Structure Validation:
Content Validation:
Compatibility Testing:
Error Categories:
Error Recovery:
This skill complements the existing plugin_validator.py by adding:
Use this skill together with the general plugin validator for comprehensive quality assurance.
Version: 1.0.0 Last Updated: 2025-10-23 Compatible With: Claude Code Plugin System v2.0+
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.