[BUG] plugin-dev:hook-development validate-hook-schema.sh doesn't support plugin wrapper format

[sjnims]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

The validate-hook-schema.sh script in the plugin-dev:hook-development skill doesn't support the plugin wrapper format that the same skill recommends for plugin hooks.

The skill's SKILL.md documents that plugin hooks/hooks.json files should use a wrapper format:

{
  "description": "Brief explanation of hooks (optional)",
  "hooks": {
    "UserPromptSubmit": [...]
  }
}

However, validate-hook-schema.sh iterates over root-level keys assuming events are at the top level:

for event in $(jq -r 'keys[]' "$HOOKS_FILE"); do

This causes the script to:

1. Flag "description" and "hooks" as unknown event types
2. Crash with a jq error when trying to iterate over these as arrays

What Should Happen?

The validation script should detect the plugin wrapper format and validate the hooks inside .hooks rather than at the root level.

Error Messages/Logs

🔍 Validating hooks configuration: hooks/hooks.json

Checking JSON syntax...
✅ Valid JSON

Checking root structure...
⚠️  Unknown event type: description
⚠️  Unknown event type: hooks
✅ Root structure valid

Validating individual hooks...
jq: error (at hooks/hooks.json:17): Cannot index string with number

Steps to Reproduce

1. Create a plugin with hooks/hooks.json using the recommended wrapper format:

   {
     "description": "My plugin hooks",
     "hooks": {
       "UserPromptSubmit": [
         {
           "matcher": "*",
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Test prompt",
               "timeout": 10
             }
           ]
         }
       ]
     }
   }
   

2. Run the validation script:

   bash ~/.claude/plugins/marketplaces/claude-code-plugins/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh hooks/hooks.json
   

3. Observe the warnings and error

Is this a regression?

No, this never worked

Claude Code Version

2.0.60 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

Suggested Fix

The script should detect the wrapper format and adjust the jq queries:

# Detect wrapper format
if jq -e '.hooks' "$HOOKS_FILE" > /dev/null 2>&1; then
  HOOKS_PATH=".hooks"
else
  HOOKS_PATH="."
fi

for event in $(jq -r "$HOOKS_PATH | keys[]" "$HOOKS_FILE"); do
  # ... validation logic using $HOOKS_PATH
done

Additional Gap: Missing UserPromptSubmit Pattern

The references/patterns.md file includes 10 hook patterns but none demonstrate UserPromptSubmit hooks, despite them being supported for prompt-based hooks per official documentation.

Related

• Official hooks docs confirm plugin wrapper format: https://docs.anthropic.com/en/docs/claude-code/hooks
• Skill location: plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[sjnims]

@github-actions, there’s an open PR