plugin-checker

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