name	plugin-checker
description	Use this skill when asked to "validate plugin", "check plugin structure", "verify plugin", "audit plugin", "is my plugin correct", "plugin issues", or when troubleshooting plugin problems.

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

Install Skill

SKILL.md