creating-claude-hooks-skill

Name: creating-claude-hooks-skill
Author: AgentWorkforce

769stars58forks

How to install creating-claude-hooks-skill?

agentworkforce/relay/creating-claude-hooks-skill

$npx -y skills add AgentWorkforce/relay --skill creating-claude-hooks-skill

Installs into the current project.

Summary

Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure

Files · 1

View on GitHub

SKILL.md

1	# Creating Claude Code Hooks
2
3	Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.
4
5	## When to Use This Skill
6
7	Activate this skill when:
8
9	- User asks to create a new Claude Code hook
10	- User wants to publish a hook as a PRPM package
11	- User needs to understand hook format or events
12	- User is troubleshooting hook execution
13	- User asks about hook vs skill vs command differences
14
15	## Quick Reference
16
17	### Hook File Format
18
19	\| Aspect \| Requirement \|
20	\| --------------- \| ------------------------------------------------- \|
21	\| Location \| `.claude/hooks/<event-name>` \|
22	\| Format \| Executable file (shell, TypeScript, Python, etc.) \|
23	\| Permissions \| Must be executable (`chmod +x`) \|
24	\| Shebang \| Required (`#!/bin/bash` or `#!/usr/bin/env node`) \|
25	\| Input \| JSON via stdin \|
26	\| Output \| Text via stdout (shown to user) \|
27	\| Exit Codes \| `0` = success, `2` = block, other = error \|
28
29	### Available Events
30
31	\| Event \| When It Fires \| Common Use Cases \|
32	\| -------------------- \| --------------------------- \| ---------------------------------------- \|
33	\| `session-start` \| New session begins \| Environment setup, logging, checks \|
34	\| `user-prompt-submit` \| Before user input processes \| Validation, enhancement, filtering \|
35	\| `tool-call` \| Before tool execution \| Permission checks, logging, modification \|
36	\| `assistant-response` \| After assistant responds \| Formatting, logging, cleanup \|
37
38	## Hook Format Requirements
39
40	### File Location
41
42	Project hooks:
43
44	```
45	.claude/hooks/session-start
46	.claude/hooks/user-prompt-submit
47	```
48
49	User-global hooks:
50
51	```
52	~/.claude/hooks/session-start
53	~/.claude/hooks/tool-call
54	```
55
56	### Executable Requirements
57
58	Every hook MUST:
59
60	1. Have a shebang line:
61
62	```bash
63	#!/bin/bash
64	# or
65	#!/usr/bin/env node
66	# or
67	#!/usr/bin/env python3
68	```
69
70	2. Be executable:
71
72	```bash
73	chmod +x .claude/hooks/session-start
74	```
75
76	3. Handle JSON input from stdin:
77
78	```bash
79	#!/bin/bash
80	INPUT=$(cat)
81	FILE=$(echo "$INPUT" \| jq -r '.input.file_path // empty')
82	```
83
84	4. Exit with appropriate code:
85
86	```bash
87	exit 0 # Success
88	exit 2 # Block operation
89	exit 1 # Error (logs but continues)
90	```
91
92	## Input/Output Format
93
94	### JSON Input Structure
95
96	Hooks receive JSON via stdin with event-specific data:
97
98	```json
99	{
100	"event": "tool-call",
101	"timestamp": "2025-01-15T10:30:00Z",
102	"session_id": "abc123",
103	"current_dir": "/path/to/project",
104	"input": {
105	"file_path": "/path/to/file.ts",
106	"command": "npm test",
107	"old_string": "...",
108	"new_string": "..."
109	}
110	}
111	```
112
113	### Stdout Output
114
115	- Normal output shows in transcript
116	- Empty output runs silently
117	- Use stderr (`>&2`) for errors
118
119	### Exit Codes
120
121	\| Code \| Meaning \| Behavior \|
122	\| ------------ \| ------- \| -------------------------- \|
123	\| `0` \| Success \| Continue normally \|
124	\| `2` \| Block \| Stop operation, show error \|
125	\| `1` or other \| Error \| Log error, continue \|
126
127	## Schema Validation
128
129	Hooks should validate against the JSON schema:
130
131	Schema URL: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json
132
133	Required frontmatter fields:
134
135	- `name` - Hook identifier (lowercase, hyphens only)
136	- `description` - What the hook does
137	- `event` - Event type (optional, inferred from filename)
138	- `language` - bash, typescript, javascript, python, binary (optional)
139	- `hookType: "hook"` - For round-trip conversion
140
141	## Common Mistakes
142
143	\| Mistake \| Problem \| Solution \|
144	\| ---------------------- \| ------------------------- \| ------------------------------------ \|
145	\| Not quoting variables \| Breaks on spaces \| Always use `"$VAR"` \|
146	\| Missing shebang \| Won't execute \| Add `#!/bin/bash` \|
147	\| Not executable \| Permission denied \| Run `chmod +x hook-file` \|
148	\| Logging to stdout \| Clutters transcript \| Use stderr: `echo "log" >&2` \|
149	\| Wrong exit code \| Doesn't block when needed \| Use `exit 2` to block \|
150	\| No input validation \| Security risk \| Always validate JSON fields \|
151	\| Slow operations \| Blocks Claude \| Run in background or use PostToolUse \|
152	\| Absolute paths missing \| Can't find scripts \| Use

People who liked this also viewed

6 picks

Type

creating-claude-hooks-skill

769stars58forks

View on GitHub

How to install creating-claude-hooks-skill?

agentworkforce/relay/creating-claude-hooks-skill

$npx -y skills add AgentWorkforce/relay --skill creating-claude-hooks-skill

Installs into the current project.

Summary

Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure

Files · 1

View on GitHub

SKILL.md

1	# Creating Claude Code Hooks
2
3	Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.
4
5	## When to Use This Skill
6
7	Activate this skill when:
8
9	- User asks to create a new Claude Code hook
10	- User wants to publish a hook as a PRPM package
11	- User needs to understand hook format or events
12	- User is troubleshooting hook execution
13	- User asks about hook vs skill vs command differences
14
15	## Quick Reference
16
17	### Hook File Format
18
19	\| Aspect \| Requirement \|
20	\| --------------- \| ------------------------------------------------- \|
21	\| Location \| `.claude/hooks/<event-name>` \|
22	\| Format \| Executable file (shell, TypeScript, Python, etc.) \|
23	\| Permissions \| Must be executable (`chmod +x`) \|
24	\| Shebang \| Required (`#!/bin/bash` or `#!/usr/bin/env node`) \|
25	\| Input \| JSON via stdin \|
26	\| Output \| Text via stdout (shown to user) \|
27	\| Exit Codes \| `0` = success, `2` = block, other = error \|
28
29	### Available Events
30
31	\| Event \| When It Fires \| Common Use Cases \|
32	\| -------------------- \| --------------------------- \| ---------------------------------------- \|
33	\| `session-start` \| New session begins \| Environment setup, logging, checks \|
34	\| `user-prompt-submit` \| Before user input processes \| Validation, enhancement, filtering \|
35	\| `tool-call` \| Before tool execution \| Permission checks, logging, modification \|
36	\| `assistant-response` \| After assistant responds \| Formatting, logging, cleanup \|
37
38	## Hook Format Requirements
39
40	### File Location
41
42	Project hooks:
43
44	```
45	.claude/hooks/session-start
46	.claude/hooks/user-prompt-submit
47	```
48
49	User-global hooks:
50
51	```
52	~/.claude/hooks/session-start
53	~/.claude/hooks/tool-call
54	```
55
56	### Executable Requirements
57
58	Every hook MUST:
59
60	1. Have a shebang line:
61
62	```bash
63	#!/bin/bash
64	# or
65	#!/usr/bin/env node
66	# or
67	#!/usr/bin/env python3
68	```
69
70	2. Be executable:
71
72	```bash
73	chmod +x .claude/hooks/session-start
74	```
75
76	3. Handle JSON input from stdin:
77
78	```bash
79	#!/bin/bash
80	INPUT=$(cat)
81	FILE=$(echo "$INPUT" \| jq -r '.input.file_path // empty')
82	```
83
84	4. Exit with appropriate code:
85
86	```bash
87	exit 0 # Success
88	exit 2 # Block operation
89	exit 1 # Error (logs but continues)
90	```
91
92	## Input/Output Format
93
94	### JSON Input Structure
95
96	Hooks receive JSON via stdin with event-specific data:
97
98	```json
99	{
100	"event": "tool-call",
101	"timestamp": "2025-01-15T10:30:00Z",
102	"session_id": "abc123",
103	"current_dir": "/path/to/project",
104	"input": {
105	"file_path": "/path/to/file.ts",
106	"command": "npm test",
107	"old_string": "...",
108	"new_string": "..."
109	}
110	}
111	```
112
113	### Stdout Output
114
115	- Normal output shows in transcript
116	- Empty output runs silently
117	- Use stderr (`>&2`) for errors
118
119	### Exit Codes
120
121	\| Code \| Meaning \| Behavior \|
122	\| ------------ \| ------- \| -------------------------- \|
123	\| `0` \| Success \| Continue normally \|
124	\| `2` \| Block \| Stop operation, show error \|
125	\| `1` or other \| Error \| Log error, continue \|
126
127	## Schema Validation
128
129	Hooks should validate against the JSON schema:
130
131	Schema URL: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json
132
133	Required frontmatter fields:
134
135	- `name` - Hook identifier (lowercase, hyphens only)
136	- `description` - What the hook does
137	- `event` - Event type (optional, inferred from filename)
138	- `language` - bash, typescript, javascript, python, binary (optional)
139	- `hookType: "hook"` - For round-trip conversion
140
141	## Common Mistakes
142
143	\| Mistake \| Problem \| Solution \|
144	\| ---------------------- \| ------------------------- \| ------------------------------------ \|
145	\| Not quoting variables \| Breaks on spaces \| Always use `"$VAR"` \|
146	\| Missing shebang \| Won't execute \| Add `#!/bin/bash` \|
147	\| Not executable \| Permission denied \| Run `chmod +x hook-file` \|
148	\| Logging to stdout \| Clutters transcript \| Use stderr: `echo "log" >&2` \|
149	\| Wrong exit code \| Doesn't block when needed \| Use `exit 2` to block \|
150	\| No input validation \| Security risk \| Always validate JSON fields \|
151	\| Slow operations \| Blocks Claude \| Run in background or use PostToolUse \|
152	\| Absolute paths missing \| Can't find scripts \| Use

People who liked this also viewed

6 picks

Type