Instrucciones de origen · Vista previa de solo lectura
name
hook-scope-guide
description
Select hook scope (plugin, project, global) by audience. Use when authoring a hook.
category
hook-development
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)
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 bash commands to personal audit trail
Question 2: Should this be version controlled?
Yes, as part of a distributable plugin → Plugin hooks
Yes, shared with team in repo → Project hooks
No, keep private → Global hooks
Question 3: What's the persistence requirement?
Only when my plugin is active → Plugin hooks
Always in this specific project → Project hooks
Always, in every project I work on → Global hooks
Scope Details
Plugin Hooks
Location: <plugin-root>/hooks/hooks.json
When to use:
The hook is intrinsic to your plugin's functionality
It should automatically activate when users enable your plugin
It only makes sense in the context of your plugin's features
Claude Code loads settings in this priority (highest first):
Enterprise policies (organization-managed)
Command-line arguments (claude --flag)
Local project settings (.claude/settings.local.json)
Shared project settings (.claude/settings.json)
User settings (~/.claude/settings.json)
Important: Multiple hooks from different scopes can respond to the same event. When they do, all matching hooks execute in parallel.
Quick Reference: Scope Selection
Is this hook part of a plugin's core functionality?
├─ YES → Plugin hooks (hooks/hooks.json in plugin)
└─ NO ↓
Should all team members on this project have this hook?
├─ YES → Project hooks (.claude/settings.json)
└─ NO ↓
Should this hook apply to all my Claude sessions?
├─ YES → Global hooks (~/.claude/settings.json)
└─ NO → Reconsider if you need a hook at all
SessionStart hooks now receive additional input fields via stdin:
Field
Type
Description
session_id
string
Unique session identifier
source
enum
"startup" | "resume" | "clear" | "compact"
agent_type
string
Agent name if --agent flag used, empty otherwise
Agent-Aware Hooks
The agent_type field enables scope-appropriate context injection:
# Skip heavy context for review agents
input_data = json.loads(sys.stdin.read())
if input_data.get("agent_type") in ["code-reviewer", "quick-query"]:
print(json.dumps({"hookSpecificOutput": {"additionalContext": "Minimal"}}))
This is particularly useful for:
Plugin hooks: Reduce overhead for lightweight agents
Project hooks: Skip governance for review-only agents
Global hooks: Customize logging verbosity per agent
Related Skills
abstract:hook-authoring - For hook rule syntax and patterns
abstract:validate-plugin - For validating plugin structure including hooks
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" to plugin.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.
