Hook Scope Decision Guide
Overview
This skill helps you choose the right location for Claude Code hooks based on their purpose, audience, and persistence needs.
When NOT To Use
- Writing the hook itself (use
abstract:hook-authoring) - Scoring an existing hook (use
abstract:hooks-eval)
Decision Framework
Three questions pick the scope: who needs this hook, should it be
version controlled, and how long should it persist. Plugin hooks
(hooks/hooks.json in the plugin) serve plugin users while the plugin
is enabled. Project hooks (.claude/settings.json) serve the team and
are committed. Global hooks (~/.claude/settings.json) serve only you,
in every session, and are never committed.
The question tree, per-scope configuration and examples, loading
precedence, security considerations, migration and troubleshooting are
written once, in
plugins/abstract/skills/hook-authoring/modules/scope-selection.md.
Read it before choosing. Agent-aware SessionStart hooks are covered in
abstract:hook-authoring under Hook Event Types.
Related Skills
- abstract:hook-authoring - For hook rule syntax and patterns
- abstract:validate-plugin - For validating plugin structure including hooks
References
Exit Criteria
- A single scope (plugin / project / global) is selected and the rationale traces through at least two of the three decision questions (audience, version control, persistence).
- The selected scope's file location (
hooks/hooks.json,.claude/settings.json, or~/.claude/settings.json) is confirmed to exist or is created at the correct path. - Plugin hooks do not add
"hooks": "./hooks/hooks.json"toplugin.json(duplicate-load guard). This absence is verified before the hook is deployed. - Global hooks are flagged with a security note confirming they apply to all Claude sessions on this machine.
