hook-development

Name: hook-development
Author: anthropics

byanthropics· 237 skills

Installs

12k

Stars

139k

Forks

22k

How to install hook-development?

anthropics/claude-code/hook-development

$npx -y skills add anthropics/claude-code --skill hook-development

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/anthropics/claude-code" --skill "anthropics/claude-code/hook-development"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/anthropics/claude-code" that are relevant to the current task. Run `npx skills add "https://github.com/anthropics/claude-code"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Hook Development for Claude Code Plugins
2
3	## Overview
4
5	Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.
6
7	Key capabilities:
8	- Validate tool calls before execution (PreToolUse)
9	- React to tool results (PostToolUse)
10	- Enforce completion standards (Stop, SubagentStop)
11	- Load project context (SessionStart)
12	- Automate workflows across the development lifecycle
13
14	## Hook Types
15
16	### Prompt-Based Hooks (Recommended)
17
18	Use LLM-driven decision making for context-aware validation:
19
20	```json
21	{
22	"type": "prompt",
23	"prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
24	"timeout": 30
25	}
26	```
27
28	Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse
29
30	Benefits:
31	- Context-aware decisions based on natural language reasoning
32	- Flexible evaluation logic without bash scripting
33	- Better edge case handling
34	- Easier to maintain and extend
35
36	### Command Hooks
37
38	Execute bash commands for deterministic checks:
39
40	```json
41	{
42	"type": "command",
43	"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
44	"timeout": 60
45	}
46	```
47
48	Use for:
49	- Fast deterministic validations
50	- File system operations
51	- External tool integrations
52	- Performance-critical checks
53
54	## Hook Configuration Formats
55
56	### Plugin hooks.json Format
57
58	For plugin hooks in `hooks/hooks.json`, use wrapper format:
59
60	```json
61	{
62	"description": "Brief explanation of hooks (optional)",
63	"hooks": {
64	"PreToolUse": [...],
65	"Stop": [...],
66	"SessionStart": [...]
67	}
68	}
69	```
70
71	Key points:
72	- `description` field is optional
73	- `hooks` field is required wrapper containing actual hook events
74	- This is the plugin-specific format
75
76	Example:
77	```json
78	{
79	"description": "Validation hooks for code quality",
80	"hooks": {
81	"PreToolUse": [
82	{
83	"matcher": "Write",
84	"hooks": [
85	{
86	"type": "command",
87	"command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
88	}
89	]
90	}
91	]
92	}
93	}
94	```
95
96	### Settings Format (Direct)
97
98	For user settings in `.claude/settings.json`, use direct format:
99
100	```json
101	{
102	"PreToolUse": [...],
103	"Stop": [...],
104	"SessionStart": [...]
105	}
106	```
107
108	Key points:
109	- No wrapper - events directly at top level
110	- No description field
111	- This is the settings format
112
113	Important: The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in `{"hooks": {...}}`.
114
115	## Hook Events
116
117	### PreToolUse
118
119	Execute before any tool runs. Use to approve, deny, or modify tool calls.
120
121	Example (prompt-based):
122	```json
123	{
124	"PreToolUse": [
125	{
126	"matcher": "Write\|Edit",
127	"hooks": [
128	{
129	"type": "prompt",
130	"prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."
131	}
132	]
133	}
134	]
135	}
136	```
137
138	Output for PreToolUse:
139	```json
140	{
141	"hookSpecificOutput": {
142	"permissionDecision": "allow\|deny\|ask",
143	"updatedInput": {"field": "modified_value"}
144	},
145	"systemMessage": "Explanation for Claude"
146	}
147	```
148
149	### PostToolUse
150
151	Execute after tool completes. Use to react to results, provide feedback, or log.
152
153	Example:
154	```json
155	{
156	"PostToolUse": [
157	{
158	"matcher": "Edit",
159	"hooks": [
160	{
161	"type": "prompt",
162	"prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback."
163	}
164	]
165	}
166	]
167	}
168	```
169
170	Output behavior:
171	- Exit 0: stdout shown in transcript
172	- Exit 2: stderr fed back to Claude
173	- systemMessage included in context
174
175	### Stop
176
177	Execute when main agent considers stopping. Use to validate completeness.
178
179	Example:
180	```json
181	{
182	"Stop": [
183	{
184	"matcher": "*",
185	"hooks": [
186	{
187	"type": "prompt",
188	"prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue."
189	}
190	]
191	}
192	]
193	}
194	```
195
196	Decision output:
197	```json
198	{
199	"decision": "approve\|block",
200	"reason": "Explanation",
201	"systemMessage": "Additional context"
202	}
203	```
204
205	### SubagentStop
206
207	Execute when subagent considers stopping. Use to ensure subagent completed its task.
208
209	Similar to Stop hook, but for subagents.
210
211	### UserPromptSubmit
212
213	Execute when user submits a prompt. Use to add context, validate, or block prompts.
214
215	Example:
216	```json
217	{
218	"UserPromptSubmit": [
219	{
220	"matcher": "*",
221	"hooks": [
222	{
223	"type": "prompt",
224	"prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings."
225	}
226	]
227	}
228	]
229	}
230	```
231
232	### SessionStart
233
234	Execute when Claude Code session begins. Use to load context and set environment.
235
236	Example:
237	```json
238	{
239	"SessionStart": [
240	{
241	"matcher": "*",
242	"hooks": [
243	{
244	"type": "command",
245	"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
246	}
247	]
248	}
249	]
250	}
251	```
252
253	Special capability: Persist environment variables using `$CLAUDE_ENV_FILE`:
254	```bash
255	echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
256	```
257
258	See `examples/load-context.sh` for complete example.
259
260	### SessionEnd
261
262	Execute when session ends. Use for cleanup, logging, and state preservation.
263
264	### PreCompact
265
266	Execute before context compaction. Use to add critical information to preserve.
267
268	### Notification
269
270	Execute when Claude sends notifications. Use to react to user notifications.
271
272	## Hook Output Format
273
274	### Standard Output (All Hooks)
275
276	```json
277	{
278	"continue": true,
279	"suppressOutput": false,
280	"systemMessage": "Message for Claude"
281	}
282	```
283
284	- `continue`: If false, halt processing (default true)
285	- `suppressOutput`: Hide output from transcript (default false)
286	- `systemMessage`: Message shown to Claude
287
288	### Exit Codes
289
290	- `0` - Success (stdout shown in transcript)
291	- `2` - Blocking error (stderr fed back to Claude)
292	- Other - Non-blocking error
293
294	## Hook Input Format
295
296	All hooks receive JSON via stdin with common fields:
297
298	```json
299	{
300	"session_id": "abc123",
301	"transcript_path": "/path/to/transcript.txt",
302	"cwd": "/current/working/dir",
303	"permission_mode": "ask\|allow",
304	"hook_event_name": "PreToolUse"
305	}
306	```
307
308	Event-specific fields:
309
310	- PreToolUse/PostToolUse: `tool_name`, `tool_input`, `tool_result`
311	- UserPromptSubmit: `user_prompt`
312	- Stop/SubagentStop: `reason`
313
314	Access fields in prompts using `$TOOL_INPUT`, `$TOOL_RESULT`, `$USER_PROMPT`, etc.
315
316	## Environment Variables
317
318	Available in all command hooks:
319
320	- `$CLAUDE_PROJECT_DIR` - Project root path
321	- `$CLAUDE_PLUGIN_ROOT` - Plugin directory (use for portable paths)
322	- `$CLAUDE_ENV_FILE` - SessionStart only: persist env vars here
323	- `$CLAUDE_CODE_REMOTE` - Set if running in remote context
324
325	Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:
326
327	```json
328	{
329	"type": "command",
330	"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
331	}
332	```
333
334	## Plugin Hook Configuration
335
336	In plugins, define hooks in `hooks/hooks.json`:
337
338	```json
339	{
340	"PreToolUse": [
341	{
342	"matcher": "Write\|Edit",
343	"hooks": [
344	{
345	"type": "prompt",
346	"prompt": "Validate file write safety"
347	}
348	]
349	}
350	],
351	"Stop": [
352	{
353	"matcher": "*",
354	"hooks": [
355	{
356	"type": "prompt",
357	"prompt": "Verify task completion"
358	}
359	]
360	}
361	],
362	"SessionStart": [
363	{
364	"matcher": "*",
365	"hooks": [
366	{
367	"type": "command",
368	"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
369	"timeout": 10
370	}
371	]
372	}
373	]
374	}
375	```
376
377	Plugin hooks merge with user's hooks and run in parallel.
378
379	## Matchers
380
381	### Tool Name Matching
382
383	Exact match:
384	```json
385	"matcher": "Write"
386	```
387
388	Multiple tools:
389	```json
390	"matcher": "Read\|Write\|Edit"
391	```
392
393	Wildcard (all tools):
394	```json
395	"matcher": "*"
396	```
397
398	Regex patterns:
399	```json
400	"matcher": "mcp__.__delete." // All MCP delete tools
401	```
402
403	Note: Matchers are case-sensitive.
404
405	### Common Patterns
406
407	```json
408	// All MCP tools
409	"matcher": "mcp__.*"
410
411	// Specific plugin's MCP tools
412	"matcher": "mcp__plugin_asana_.*"
413
414	// All file operations
415	"matcher": "Read\|Write\|Edit"
416
417	// Bash commands only
418	"matcher": "Bash"
419	```
420
421	## Security Best Practices
422
423	### Input Validation
424
425	Always validate inputs in command hooks:
426
427	```bash
428	#!/bin/bash
429	set -euo pipefail
430
431	input=$(cat)
432	tool_name=$(echo "$input" \| jq -r '.tool_name')
433
434	# Validate tool name format
435	if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then
436	echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2
437	exit 2
438	fi
439	```
440
441	### Path Safety
442
443	Check for path traversal and sensitive files:
444
445	```bash
446	file_path=$(echo "$input" \| jq -r '.tool_input.file_path')
447
448	# Deny path traversal
449	if [[ "$file_path" == ".." ]]; then
450	echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
451	exit 2
452	fi
453
454	# Deny sensitive files
455	if [[ "$file_path" == ".env" ]]; then
456	echo '{"decision": "deny", "reason": "Sensitive file"}' >&2
457	exit 2
458	fi
459	```
460
461	See `examples/validate-write.sh` and `examples/validate-bash.sh` for complete examples.
462
463	### Quote All Variables
464
465	```bash
466	# GOOD: Quoted
467	echo "$file_path"
468	cd "$CLAUDE_PROJECT_DIR"
469
470	# BAD: Unquoted (injection risk)
471	echo $file_path
472	cd $CLAUDE_PROJECT_DIR
473	```
474
475	### Set Appropriate Timeouts
476
477	```json
478	{
479	"type": "command",
480	"command": "bash script.sh",
481	"timeout": 10
482	}
483	```
484
485	Defaults: Command hooks (60s), Prompt hooks (30s)
486
487	## Performance Considerations
488
489	### Parallel Execution
490
491	All matching hooks run in parallel:
492
493	```json
494	{
495	"PreToolUse": [
496	{
497	"matcher": "Write",
498	"hooks": [
499	{"type": "command", "command": "check1.sh"}, // Parallel
500	{"type": "command", "command": "check2.sh"}, // Parallel
501	{"type": "prompt", "prompt": "Validate..."} // Parallel
502	]
503	}
504	]
505	}
506	```
507
508	Design implications:
509	- Hooks don't see each other's output
510	- Non-deterministic ordering
511	- Design for independence
512
513	### Optimization
514
515	1. Use command hooks for quick deterministic checks
516	2. Use prompt hooks for complex reasoning
517	3. Cache validation results in temp files
518	4. Minimize I/O in hot paths
519
520	## Temporarily Active Hooks
521
522	Create hooks that activate conditionally by checking for a flag file or configuration:
523
524	Pattern: Flag file activation
525	```bash
526	#!/bin/bash
527	# Only active when flag file exists
528	FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"
529
530	if [ ! -f "$FLAG_FILE" ]; then
531	# Flag not present, skip validation
532	exit 0
533	fi
534
535	# Flag present, run validation
536	input=$(cat)
537	# ... validation logic ...
538	```
539
540	Pattern: Configuration-based activation
541	```bash
542	#!/bin/bash
543	# Check configuration for activation
544	CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/plugin-config.json"
545
546	if [ -f "$CONFIG_FILE" ]; then
547	enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE")
548	if [ "$enabled" != "true" ]; then
549	exit 0 # Not enabled, skip
550	fi
551	fi
552
553	# Enabled, run hook logic
554	input=$(cat)
555	# ... hook logic ...
556	```
557
558	Use cases:
559	- Enable strict validation only when needed
560	- Temporary debugging hooks
561	- Project-specific hook behavior
562	- Feature flags for hooks
563
564	Best practice: Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.
565
566	## Hook Lifecycle and Limitations
567
568	### Hooks Load at Session Start
569
570	Important: Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.
571
572	Cannot hot-swap hooks:
573	- Editing `hooks/hooks.json` won't affect current session
574	- Adding new hook scripts won't be recognized
575	- Changing hook commands/prompts won't update
576	- Must restart Claude Code: exit and run `claude` again
577
578	To test hook changes:
579	1. Edit hook configuration or scripts
580	2. Exit Claude Code session
581	3. Restart: `claude` or `cc`
582	4. New hook configuration loads
583	5. Test hooks with `claude --debug`
584
585	### Hook Validation at Startup
586
587	Hooks are validated when Claude Code starts:
588	- Invalid JSON in hooks.json causes loading failure
589	- Missing scripts cause warnings
590	- Syntax errors reported in debug mode
591
592	Use `/hooks` command to review loaded hooks in current session.
593
594	## Debugging Hooks
595
596	### Enable Debug Mode
597
598	```bash
599	claude --debug
600	```
601
602	Look for hook registration, execution logs, input/output JSON, and timing information.
603
604	### Test Hook Scripts
605
606	Test command hooks directly:
607
608	```bash
609	echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' \| \
610	bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
611
612	echo "Exit code: $?"
613	```
614
615	### Validate JSON Output
616
617	Ensure hooks output valid JSON:
618
619	```bash
620	output=$(./your-hook.sh < test-input.json)
621	echo "$output" \| jq .
622	```
623
624	## Quick Reference
625
626	### Hook Events Summary
627
628	\| Event \| When \| Use For \|
629	\|-------\|------\|---------\|
630	\| PreToolUse \| Before tool \| Validation, modification \|
631	\| PostToolUse \| After tool \| Feedback, logging \|
632	\| UserPromptSubmit \| User input \| Context, validation \|
633	\| Stop \| Agent stopping \| Completeness check \|
634	\| SubagentStop \| Subagent done \| Task validation \|
635	\| SessionStart \| Session begins \| Context loading \|
636	\| SessionEnd \| Session ends \| Cleanup, logging \|
637	\| PreCompact \| Before compact \| Preserve context \|
638	\| Notification \| User notified \| Logging, reactions \|
639
640	### Best Practices
641
642	DO:
643	- ✅ Use prompt-based hooks for complex logic
644	- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability
645	- ✅ Validate all inputs in command hooks
646	- ✅ Quote all bash variables
647	- ✅ Set appropriate timeouts
648	- ✅ Return structured JSON output
649	- ✅ Test hooks thoroughly
650
651	DON'T:
652	- ❌ Use hardcoded paths
653	- ❌ Trust user input without validation
654	- ❌ Create long-running hooks
655	- ❌ Rely on hook execution order
656	- ❌ Modify global state unpredictably
657	- ❌ Log sensitive information
658
659	## Additional Resources
660
661	### Reference Files
662
663	For detailed patterns and advanced techniques, consult:
664
665	- `references/patterns.md` - Common hook patterns (8+ proven patterns)
666	- `references/migration.md` - Migrating from basic to advanced hooks
667	- `references/advanced.md` - Advanced use cases and techniques
668
669	### Example Hook Scripts
670
671	Working examples in `examples/`:
672
673	- `validate-write.sh` - File write validation example
674	- `validate-bash.sh` - Bash command validation example
675	- `load-context.sh` - SessionStart context loading example
676
677	### Utility Scripts
678
679	Development tools in `scripts/`:
680
681	- `validate-hook-schema.sh` - Validate hooks.json structure and syntax
682	- `test-hook.sh` - Test hooks with sample input before deployment
683	- `hook-linter.sh` - Check hook scripts for common issues and best practices
684
685	### External Resources
686
687	- Official Docs: https://docs.claude.com/en/docs/claude-code/hooks
688	- Examples: See security-guidance plugin in marketplace
689	- Testing: Use `claude --debug` for detailed logs
690	- Validation: Use `jq` to validate hook JSON output
691
692	## Implementation Workflow
693
694	To implement hooks in a plugin:
695
696	1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)
697	2. Decide between prompt-based (flexible) or command (deterministic) hooks
698	3. Write hook configuration in `hooks/hooks.json`
699	4. For command hooks, create hook scripts
700	5. Use ${CLAUDE_PLUGIN_ROOT} for all file references
701	6. Validate configuration with `scripts/validate-hook-schema.sh hooks/hooks.json`
702	7. Test hooks with `scripts/test-hook.sh` before deployment
703	8. Test in Claude Code with `claude --debug`
704	9. Document hooks in plugin README
705
706	Focus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.

6 picks

Type

Run `npx skills use "https://github.com/anthropics/claude-code" --skill "anthropics/claude-code/hook-development"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/anthropics/claude-code" that are relevant to the current task. Run `npx skills add "https://github.com/anthropics/claude-code"` and select the relevant skills, then follow their instructions.

hook-development

How to install hook-development?

Related

hook-development

How to install hook-development?

Related