From autonomous-agent
Validates Claude Code plugins for compliance with official guidelines including plugin.json manifest, directory structure, and formats for agents/skills/commands to prevent installation failures.
npx claudepluginhub bejranonda/llm-autonomous-agent-plugin-for-claude --plugin autonomous-agentThis skill uses the workspace's default tool permissions.
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.
Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.
Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.
Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.
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+