hook-scope-guide
Installation
SKILL.md
Hook Scope Decision Guide
This skill helps you choose the right location for Claude Code hooks based on their purpose, audience, and persistence needs.
Important: Auto-Loading Behavior
hooks/hooks.jsonis automatically loaded by Claude Code when the plugin is enabled. Do NOT add"hooks": "./hooks/hooks.json"to yourplugin.json- this causes duplicate load errors. Thehooksfield inplugin.jsonis only needed for additional hook files beyond the standardhooks/hooks.json.
The Three Scopes
| Scope | Location | Audience | Committed? | Persistence |
|---|---|---|---|---|
| Plugin | hooks/hooks.json in plugin |
Plugin users | With plugin | When plugin enabled |
| Project | .claude/settings.json |
Team members | Yes (repo) | Per project |
| Global | ~/.claude/settings.json |
Only you | Never | All sessions |