Plugin Checker Skill

This skill provides comprehensive validation guidelines for Claude Code plugins, helping identify structural issues, misconfigurations, and best practice violations.

Validation Checklist

1. Plugin Manifest Validation

Check .claude-plugin/plugin.json:

Required:

• File exists at .claude-plugin/plugin.json
• Valid JSON syntax
• name field present and valid

Name validation:

• Uses kebab-case (lowercase letters, numbers, hyphens)
• Length between 3-50 characters
• No spaces or special characters
• Starts with a letter

Optional fields (if present):

• version follows semver (X.Y.Z)
• description is a non-empty string
• author has name field (string)
• author.email is valid email format (if present)

2. Directory Structure Validation

Required structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json    ← REQUIRED

Valid optional directories:

• agents/ - Contains .md files only
• skills/ - Contains subdirectories with SKILL.md
• commands/ - Contains .md files only
• hooks/ - Contains hooks.json
• scripts/ - Contains executable scripts

Invalid patterns to flag:

• ❌ AGENTS.md at root (should be agents/*.md)
• ❌ SKILL.md at root (should be skills/*/SKILL.md)
• ❌ Nested .claude-plugin/ directories
• ❌ Files directly in skills/ (should be in subdirs)

3. Agent File Validation

For each file in agents/*.md:

Frontmatter checks:

• File starts with ---
• Valid YAML frontmatter
• name field present
• description field present

Name field:

• Lowercase letters, numbers, hyphens only
• 3-50 characters
• Matches filename (recommended)

Description field:

• Contains trigger conditions
• Has at least one <example> block (recommended)
• Example has user:, assistant:, <commentary>

Model field (if present):

• Valid value: inherit, sonnet, opus, haiku

Color field (if present):

• Valid value: blue, cyan, green, yellow, magenta, red

Tools field (if present):

• Is an array
• Contains valid tool names

Content check:

• Has system prompt after frontmatter
• System prompt is substantial (>20 chars)

4. Skill Directory Validation

For each directory in skills/*/:

Structure:

• Contains SKILL.md file
• SKILL.md has YAML frontmatter

Frontmatter:

• name field present
• description field present with trigger phrases

Optional subdirectories:

• references/ - Additional documentation
• examples/ - Working examples
• scripts/ - Utility scripts

5. Command File Validation

For each file in commands/*.md:

Frontmatter:

• description field present
• argument-hint is string (if present)
• allowed-tools is array (if present)

Naming:

• Filename is kebab-case
• No spaces or special characters

6. Hooks Validation

For hooks/hooks.json:

JSON structure:

• Valid JSON syntax
• Has hooks object at root (or in description + hooks)

Event names (if present):

• PreToolUse
• PostToolUse
• Stop
• SubagentStop
• SessionStart
• SessionEnd
• UserPromptSubmit
• PreCompact
• Notification
• PermissionRequest

Hook entries:

• matcher field present (for tool events)
• hooks array present
• Each hook has type ("command" or "prompt")
• Command hooks have command field
• Prompt hooks have prompt field

Path portability:

• Uses ${CLAUDE_PLUGIN_ROOT} for plugin paths
• No hardcoded absolute paths

Script references:

• Referenced scripts exist
• Scripts are executable (have shebang)

7. Security Checks

Credentials:

• No hardcoded API keys or tokens
• No passwords in configuration
• Environment variables used for secrets

URLs:

• MCP servers use HTTPS/WSS (not HTTP/WS)

Scripts:

• No obvious command injection vulnerabilities
• Input validation present
• Variables properly quoted

Common Issues and Fixes

Issue: "plugin not found"

Cause: Missing or invalid plugin.json Fix: Create .claude-plugin/plugin.json with valid JSON and name field

Issue: "agents not loading"

Cause: Agents not in correct location Fix: Move to agents/ directory with .md extension

Issue: "skill not triggering"

Cause: Weak trigger description or wrong structure Fix:

• Ensure skills/{name}/SKILL.md structure
• Add specific trigger phrases to description

Issue: "hooks not running"

Cause: Invalid hooks.json or script permissions Fix:

• Validate JSON syntax
• Make scripts executable: chmod +x scripts/*.sh
• Use ${CLAUDE_PLUGIN_ROOT} in paths

Issue: "command not appearing"

Cause: Missing frontmatter or wrong location Fix: Ensure commands/*.md with description in frontmatter

Validation Commands

Quick structure check:

# Check plugin.json exists and is valid
jq . my-plugin/.claude-plugin/plugin.json

# List all components
find my-plugin -name "*.md" -o -name "*.json" | head -20

# Check hooks.json
jq . my-plugin/hooks/hooks.json 2>/dev/null || echo "No hooks.json"

Test plugin locally:

claude --plugin-dir /path/to/my-plugin

Debug mode:

claude --debug --plugin-dir /path/to/my-plugin

Validation Report Format

When reporting validation results:

## Plugin Validation Report

### Plugin: [name]
Location: [path]

### Summary
[PASS/FAIL] - [brief assessment]

### Critical Issues (must fix)
- [ ] `path/to/file` - [issue] - [fix]

### Warnings (should fix)
- [ ] `path/to/file` - [issue] - [recommendation]

### Components Found
- Agents: [count] files
- Skills: [count] directories
- Commands: [count] files
- Hooks: [present/not present]

### Positive Findings
- [What's done correctly]

### Recommendations
1. [Priority fix]
2. [Improvement suggestion]

Quick Validation Script

#!/bin/bash
# validate-plugin.sh <plugin-dir>

PLUGIN_DIR="${1:-.}"

echo "=== Plugin Validation ==="

# Check plugin.json
if [ -f "$PLUGIN_DIR/.claude-plugin/plugin.json" ]; then
  echo "✓ plugin.json exists"
  NAME=$(jq -r '.name' "$PLUGIN_DIR/.claude-plugin/plugin.json" 2>/dev/null)
  if [ -n "$NAME" ] && [ "$NAME" != "null" ]; then
    echo "✓ name: $NAME"
  else
    echo "✗ ERROR: name field missing or invalid"
  fi
else
  echo "✗ CRITICAL: .claude-plugin/plugin.json not found"
fi

# Check agents
if [ -d "$PLUGIN_DIR/agents" ]; then
  AGENT_COUNT=$(find "$PLUGIN_DIR/agents" -name "*.md" | wc -l)
  echo "✓ agents/: $AGENT_COUNT files"
fi

# Check skills
if [ -d "$PLUGIN_DIR/skills" ]; then
  SKILL_COUNT=$(find "$PLUGIN_DIR/skills" -name "SKILL.md" | wc -l)
  echo "✓ skills/: $SKILL_COUNT SKILL.md files"
fi

# Check commands
if [ -d "$PLUGIN_DIR/commands" ]; then
  CMD_COUNT=$(find "$PLUGIN_DIR/commands" -name "*.md" | wc -l)
  echo "✓ commands/: $CMD_COUNT files"
fi

# Check hooks
if [ -f "$PLUGIN_DIR/hooks/hooks.json" ]; then
  if jq empty "$PLUGIN_DIR/hooks/hooks.json" 2>/dev/null; then
    echo "✓ hooks/hooks.json: valid JSON"
  else
    echo "✗ hooks/hooks.json: invalid JSON"
  fi
fi

echo "=== Validation Complete ==="

References

• Plugin structure: https://code.claude.com/docs/en/plugins-reference
• Hooks reference: https://code.claude.com/docs/en/hooks
• Official examples: https://github.com/anthropics/claude-code/tree/main/plugins