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