surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / hookify / commands / hookify.md

231 lines · 7.5 KBPreview CodeRaw

1	---
2	description: Create hooks to prevent unwanted behaviors from conversation analysis or explicit instructions
3	argument-hint: Optional specific behavior to address
4	allowed-tools: ["Read", "Write", "AskUserQuestion", "Task", "Grep", "TodoWrite", "Skill"]
5	---
6
7	# Hookify - Create Hooks from Unwanted Behaviors
8
9	FIRST: Load the hookify:writing-rules skill using the Skill tool to understand rule file format and syntax.
10
11	Create hook rules to prevent problematic behaviors by analyzing the conversation or from explicit user instructions.
12
13	## Your Task
14
15	You will help the user create hookify rules to prevent unwanted behaviors. Follow these steps:
16
17	### Step 1: Gather Behavior Information
18
19	If $ARGUMENTS is provided:
20	- User has given specific instructions: `$ARGUMENTS`
21	- Still analyze recent conversation (last 10-15 user messages) for additional context
22	- Look for examples of the behavior happening
23
24	If $ARGUMENTS is empty:
25	- Launch the conversation-analyzer agent to find problematic behaviors
26	- Agent will scan user prompts for frustration signals
27	- Agent will return structured findings
28
29	To analyze conversation:
30	Use the Task tool to launch conversation-analyzer agent:
31	```
32	{
33	"subagent_type": "general-purpose",
34	"description": "Analyze conversation for unwanted behaviors",
35	"prompt": "You are analyzing a Claude Code conversation to find behaviors the user wants to prevent.
36
37	Read user messages in the current conversation and identify:
38	1. Explicit requests to avoid something (\"don't do X\", \"stop doing Y\")
39	2. Corrections or reversions (user fixing Claude's actions)
40	3. Frustrated reactions (\"why did you do X?\", \"I didn't ask for that\")
41	4. Repeated issues (same problem multiple times)
42
43	For each issue found, extract:
44	- What tool was used (Bash, Edit, Write, etc.)
45	- Specific pattern or command
46	- Why it was problematic
47	- User's stated reason
48
49	Return findings as a structured list with:
50	- category: Type of issue
51	- tool: Which tool was involved
52	- pattern: Regex or literal pattern to match
53	- context: What happened
54	- severity: high/medium/low
55
56	Focus on the most recent issues (last 20-30 messages). Don't go back further unless explicitly asked."
57	}
58	```
59
60	### Step 2: Present Findings to User
61
62	After gathering behaviors (from arguments or agent), present to user using AskUserQuestion:
63
64	Question 1: Which behaviors to hookify?
65	- Header: "Create Rules"
66	- multiSelect: true
67	- Options: List each detected behavior (max 4)
68	- Label: Short description (e.g., "Block rm -rf")
69	- Description: Why it's problematic
70
71	Question 2: For each selected behavior, ask about action:
72	- "Should this block the operation or just warn?"
73	- Options:
74	- "Just warn" (action: warn - shows message but allows)
75	- "Block operation" (action: block - prevents execution)
76
77	Question 3: Ask for example patterns:
78	- "What patterns should trigger this rule?"
79	- Show detected patterns
80	- Allow user to refine or add more
81
82	### Step 3: Generate Rule Files
83
84	For each confirmed behavior, create a `.claude/hookify.{rule-name}.local.md` file:
85
86	Rule naming convention:
87	- Use kebab-case
88	- Be descriptive: `block-dangerous-rm`, `warn-console-log`, `require-tests-before-stop`
89	- Start with action verb: block, warn, prevent, require
90
91	File format:
92	```markdown
93	---
94	name: {rule-name}
95	enabled: true
96	event: {bash\|file\|stop\|prompt\|all}
97	pattern: {regex pattern}
98	action: {warn\|block}
99	---
100
101	{Message to show Claude when rule triggers}
102	```
103
104	Action values:
105	- `warn`: Show message but allow operation (default)
106	- `block`: Prevent operation or stop session
107
108	For more complex rules (multiple conditions):
109	```markdown
110	---
111	name: {rule-name}
112	enabled: true
113	event: file
114	conditions:
115	- field: file_path
116	operator: regex_match
117	pattern: \.env$
118	- field: new_text
119	operator: contains
120	pattern: API_KEY
121	---
122
123	{Warning message}
124	```
125
126	### Step 4: Create Files and Confirm
127
128	IMPORTANT: Rule files must be created in the current working directory's `.claude/` folder, NOT the plugin directory.
129
130	Use the current working directory (where Claude Code was started) as the base path.
131
132	1. Check if `.claude/` directory exists in current working directory
133	- If not, create it first with: `mkdir -p .claude`
134
135	2. Use Write tool to create each `.claude/hookify.{name}.local.md` file
136	- Use relative path from current working directory: `.claude/hookify.{name}.local.md`
137	- The path should resolve to the project's .claude directory, not the plugin's
138
139	3. Show user what was created:
140	```
141	Created 3 hookify rules:
142	- .claude/hookify.dangerous-rm.local.md
143	- .claude/hookify.console-log.local.md
144	- .claude/hookify.sensitive-files.local.md
145
146	These rules will trigger on:
147	- dangerous-rm: Bash commands matching "rm -rf"
148	- console-log: Edits adding console.log statements
149	- sensitive-files: Edits to .env or credentials files
150	```
151
152	4. Verify files were created in the correct location by listing them
153
154	5. Inform user: "Rules are active immediately - no restart needed!"
155
156	The hookify hooks are already loaded and will read your new rules on the next tool use.
157
158	## Event Types Reference
159
160	- bash: Matches Bash tool commands
161	- file: Matches Edit, Write, MultiEdit tools
162	- stop: Matches when agent wants to stop (use for completion checks)
163	- prompt: Matches when user submits prompts
164	- all: Matches all events
165
166	## Pattern Writing Tips
167
168	Bash patterns:
169	- Match dangerous commands: `rm\s+-rf\|chmod\s+777\|dd\s+if=`
170	- Match specific tools: `npm\s+install\s+\|pip\s+install`
171
172	File patterns:
173	- Match code patterns: `console\.log\(\|eval\(\|innerHTML\s*=`
174	- Match file paths: `\.env$\|\.git/\|node_modules/`
175
176	Stop patterns:
177	- Check for missing steps: (check transcript or completion criteria)
178
179	## Example Workflow
180
181	User says: "/hookify Don't use rm -rf without asking me first"
182
183	Your response:
184	1. Analyze: User wants to prevent rm -rf commands
185	2. Ask: "Should I block this command or just warn you?"
186	3. User selects: "Just warn"
187	4. Create `.claude/hookify.dangerous-rm.local.md`:
188	```markdown
189	---
190	name: warn-dangerous-rm
191	enabled: true
192	event: bash
193	pattern: rm\s+-rf
194	---
195
196	⚠️ Dangerous rm command detected
197
198	You requested to be warned before using rm -rf.
199	Please verify the path is correct.
200	```
201	5. Confirm: "Created hookify rule. It's active immediately - try triggering it!"
202
203	## Important Notes
204
205	- No restart needed: Rules take effect immediately on the next tool use
206	- File location: Create files in project's `.claude/` directory (current working directory), NOT the plugin's .claude/
207	- Regex syntax: Use Python regex syntax (raw strings, no need to escape in YAML)
208	- Action types: Rules can `warn` (default) or `block` operations
209	- Testing: Test rules immediately after creating them
210
211	## Troubleshooting
212
213	If rule file creation fails:
214	1. Check current working directory with pwd
215	2. Ensure `.claude/` directory exists (create with mkdir if needed)
216	3. Use absolute path if needed: `{cwd}/.claude/hookify.{name}.local.md`
217	4. Verify file was created with Glob or ls
218
219	If rule doesn't trigger after creation:
220	1. Verify file is in project `.claude/` not plugin `.claude/`
221	2. Check file with Read tool to ensure pattern is correct
222	3. Test pattern with: `python3 -c "import re; print(re.search(r'pattern', 'test text'))"`
223	4. Verify `enabled: true` in frontmatter
224	5. Remember: Rules work immediately, no restart needed
225
226	If blocking seems too strict:
227	1. Change `action: block` to `action: warn` in the rule file
228	2. Or adjust the pattern to be more specific
229	3. Changes take effect on next tool use
230
231	Use TodoWrite to track your progress through the steps.