hook-scope-guide

# 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.json` is automatically loaded** by Claude Code when the plugin is enabled. > Do NOT add `"hooks": "./hooks/hooks.json"` to your `plugin.json` - this causes duplicate load errors. > The `hooks` field in `plugin.json` is only needed for additional hook files beyond the standard `hooks/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 | ## Decision Framework ### Question 1: Who needs this hook? **Only plugin users** → Plugin hooks - Hook is part of plugin's core functionality - Users expect it when they enable your plugin - Example: A YAML plugin validates YAML syntax on edit **All team members on this project** → Project hooks - Codebase-specific rules or protections - Team conventions that should be enforced - Example: Block modifications to `/src/production/` configs **Only me, everywhere** → Global hooks - Personal preferences or workflow optimizations - Cross-project utilities like logging - Example: Log all ba...