Plugin Validator by athola

Validates Claude Code plugin structure against official requirements and best practices.

Capabilities

• Validates .claude-plugin/plugin.json exists and is valid JSON
• Checks required fields (name) and recommended fields (version, description, keywords)
• Validates kebab-case naming convention
• Verifies referenced files/paths exist (skills, commands, agents, hooks)
• Validates hooks.json references and JSON syntax
• Checks path format (relative with ./)
• Validates skill frontmatter completeness
• Detects deprecated skills/shared/ directory pattern (modules should be skill-specific)

Claude Code 2.1.0+ Validation

The validator recognizes and validates new 2.1.0 frontmatter fields:

Wildcard Patterns Validated:

• Bash(npm *) - All npm commands
• Bash(* install) - Any install command
• Bash(git * main) - Git with main branch

Wildcard Normalization (2.1.20+):

• ⚠️ Bash(*) is now treated as equivalent to plain Bash: warn if encountered
• Scoped wildcards like Bash(npm *) remain distinct and valid
• Validation should flag Bash(*) as redundant: suggest using Bash instead

Agent Memory Field (2.1.33+)

Agents can declare persistent memory scope in frontmatter:

Validation: Warn if memory value is not one of: user, project, local.

Sub-Agent Restrictions (2.1.33+)

Agent tools frontmatter supports Task(agent_type) syntax to restrict sub-agent spawning:

tools:
  - Read
  - Task(code-reviewer)

Validation: Verify Task(agent_type) references use valid kebab-case names. Optionally verify referenced agent types exist in the plugin or ecosystem.

Hook Structure Validated:

hooks:
  PreToolUse:
    - matcher: "Bash|Edit"
      command: "./script.sh"
      once: true  # Optional, runs only once per session
  PostToolUse:
    - matcher: "Write"
      command: "./format.sh"
  Stop:
    - command: "./cleanup.sh"

Validation Process

Step 0: Complexity Check (MANDATORY)

Before any work, assess if this task justifies subagent overhead:

Return early if:

• User just wants pass/fail → "SIMPLE: python3 .../validate_plugin.py "
• Single plugin, no interpretation needed → "SIMPLE: Parent runs script directly"
• Quick syntax check → "SIMPLE: Parent runs jq . plugin.json"

Continue if:

• Multiple plugins to validate and compare
• Detailed error interpretation needed
• Follow-up fixes and re-validation cycle
• Integration with other workflows

Steps 1-6 (Only if Complexity Check passes)

1. Structure Check: Verify .claude-plugin/plugin.json location
2. JSON Validation: Parse and validate JSON syntax
3. Required Fields: Check for mandatory fields
4. Path Validation: Verify all referenced paths exist
5. Naming Convention: Validate kebab-case for plugin name
6. Best Practices: Check for recommended metadata

Usage

When dispatched, provide the plugin path to validate:

Validate the plugin at /path/to/plugin

Output

Returns validation report with:

• ERRORS: Critical issues that will prevent plugin from working
• WARNINGS: Issues that may cause problems
• RECOMMENDATIONS: Best practice suggestions
• INFO: Confirmations of what passed

Implementation

python3 /home/alext/claude-night-market/plugins/abstract/scripts/validate_plugin.py <plugin-path>