Align the repo with the plugin and hook references

[jackyraimond]

Three findings from reading the plugins reference and the hooks reference against what this repo actually does.

1. Our validator rejected valid hooks

validate.sh knew nine hook events. Claude Code ships around thirty. A contributor opening a PR for a hook on PostToolUseFailure, PermissionRequest, FileChanged, SubagentStart, TaskCompleted, PostCompact, Setup or CwdChanged would have been told by our own CI that the event does not exist.

The list is now complete as of today, but more importantly an unknown event is a warning, not a failure. This list will go stale again, and a validator that is one release behind should not block work it has no business blocking. A typo still surfaces — verified: FileChanged passes clean, PostToolUze warns and the build stays green.

2. There is an official validator we were not using

claude plugin validate ./hooks/<name> --strict

It checks the manifest against the real schema and catches what ours cannot: a misspelled field name (it even suggests the intended one), a value of the wrong type, a field left over from another tool's manifest. --strict turns warnings into errors, which is what you want before publishing.

Added as a plugin-validate job. It is deliberately not in the ruleset's required checks yet — it installs Claude Code from npm on every run, so let it prove itself over a few PRs first, then add it.

The marketplace manifest is validated without --strict: the official validator warns about a catalog with no plugins, which is the correct state for main until a hook merges. It also warned that the marketplace had no description, so that is fixed too.

3. Shell form was the wrong default

The template handed a string to sh -c:

{ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/my-new-hook.py" }

Exec form spawns the script directly, no shell involved, and the docs recommend it whenever a path placeholder is in play:

{ "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/my-new-hook.py"] }

Quoting, spaces and $ in a path stop being the author's problem. validate.sh now understands both forms — shell form stays supported for hooks that genuinely need a pipe or &&.

Also

• Manifest metadata the schema supports: $schema (editor autocomplete), keywords, license, homepage, repository.
• A README section on the features we are not yet using: userConfig, defaultEnabled, async/asyncRewake, the if filter, ${CLAUDE_PLUGIN_DATA}.
• CONTRIBUTING now states that anything deciding what a hook may do belongs in userConfig, not in a file inside the project. That rule exists because of a real hole, fixed separately in the project-checks PR.

Testing

./scripts/validate.sh and claude plugin validate --strict both pass. Command-form handling was tested four ways: exec form resolves the script, shell form still resolves it, exec form without ${CLAUDE_PLUGIN_ROOT} fails, and a hard-coded personal path in args fails.

🤖 Generated with Claude Code