hooks-development — Claude Code skill: hooks and installation
The hooks-development skill guides you through building and debugging Claude Code hooks, with a focus on output visibility. Use it when a hook runs but its message never reaches the agent.
MIT 133 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill hooks-development -a claude-codeWhat hooks-development does
The guide covers PreToolUse and PostToolUse hooks, including a Bash pattern that reads an event payload from stdin, checks a condition, and emits JSON with jq -n. It also explains how response format and exit status affect what Claude can see.
One constraint matters before you write a PreToolUse hook: do not return updatedInput for AskUserQuestion. The skill explains that this can prevent the question dialog from appearing. It also outlines how to debug invisible output by checking execution, JSON, the matcher, and the exit code.
There are step-by-step checklists for creating a PostToolUse hook and investigating missing messages, plus reference files on lifecycle, templates, and debugging. Bash is the suggested starting point; Bun or TypeScript is reserved for hooks that parse structured data, call an API, share typed modules, or keep state.
What it helps with
- create a
PreToolUseorPostToolUsehook - make a hook message visible to Claude
- trace why a hook does not run
- validate a hook's JSON output and exit status
- avoid rewriting
AskUserQuestioninput
Example prompts for the agent
- Create a
PostToolUsehook that checks project files and sends Claude a message. - Debug why Claude cannot see my hook output, and validate the JSON response.
- Review my
PreToolUsehook forAskUserQuestion; leaveupdatedInputunchanged.
How to install hooks-development
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill hooks-development -a claude-code2Manually: put the files in place
~/.claude/skills/hooks-development/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hooks-development/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill hooks-development -a codex2Manually: put the files in place
.agents/skills/hooks-development/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill hooks-development -a cursor2Manually: put the files in place
.cursor/skills/hooks-development/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp-hooks/skills/hooks-development2Manually: put the files in place
.github/skills/hooks-development/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill hooks-development -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp-hooks/skills/hooks-developmentManually: put the files in place
.devin/skills/hooks-development/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill hooks-development -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hooks-development
How do I install hooks-development in Claude Code?
Run npx skills add terrylica/cc-skills --skill hooks-development -a claude-code. The skill file is at ~/.claude/skills/hooks-development/SKILL.md.
What does hooks-development do?
It explains how to build and debug Claude Code hooks, with guidance on output visibility and decision: block. It includes a Bash pattern and troubleshooting steps.
Can a PreToolUse hook return updatedInput for AskUserQuestion?
No. The guide warns that returning updatedInput for this tool can stop the question dialog from rendering.
Source text
SKILL.md · MIT
---
name: hooks-development
description: Claude Code hooks development guide. TRIGGERS - create hook, PostToolUse, PreToolUse, Stop hook, hook lifecycle, decision block.
allowed-tools: Read, Bash, Write, Edit, Glob, Grep
---
# Hooks Development
Guide for developing Claude Code hooks with proper output visibility patterns.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## When to Use This Skill
- Creating a new PostToolUse or PreToolUse hook
- Hook output is not visible to Claude (most common issue)
- User asks about `decision: block` pattern
- Debugging why hook messages don't appear
- User mentions "Claude Code hooks" or "hook visibility"
---
## Quick Reference: Visibility Patterns
**Critical insight**: PostToolUse hook stdout is only visible to Claude when JSON contains `"decision": "block"`.
| Output Format | Claude Visibility |
| ------------------------------ | ----------------- |
| Plain text | Not visible |
| JSON without `decision: block` | Not visible |
| JSON with `decision: block` | Visible |
**Exit code behavior**:
| Exit Code | stdout Behavior | Claude Visibility |
| --------- | --------------------------------------- | ----------------------------- |
| **0** | JSON parsed, shown in verbose mode only | Only if `"decision": "block"` |
| **2** | Ignored, uses stderr instead | stderr shown to Claude |
| **Other** | stderr shown in verbose mode | Not shown to Claude |
---
## Never rewrite AskUserQuestion
A PreToolUse hook must never return `updatedInput` for `AskUserQuestion` — not directly, and not through `allowWithInput`. For that tool `updatedInput` is the channel the dialog uses to deliver the user's `answers`, so a hook that returns it is taken as having answered: the menu never renders and the tool returns "The user did not answer the questions." Measured 2026-09-24 across every session transcript: 86 of 86 rewritten calls went unseen and unanswered, against 465 of 466 plain-`allow` calls that rendered and were answered.
- A plain `allow` is safe; the dialog still shows.
- To change what the user sees, `deny` with a reason that names exactly what the agent should re-ask, and make sure the re-ask passes unchanged so the loop settles in one round (`pretooluse-pr-premise-annotator.ts` is the worked example).
- Enforced three ways: `allowWithInput` refuses the tool at runtime, `TOOL_SCHEMAS` has no entry for it, and `scripts/validate-plugins.mjs` fails the gate when a hook whose matcher covers `AskUserQuestion` emits `updatedInput` or calls `allowWithInput`.
---
## Minimal Working Pattern
```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
#!/usr/bin/env bash
set -euo pipefail
# Read hook payload from stdin
PAYLOAD=$(cat)
FILE_PATH=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // empty')
[[ -z "$FILE_PATH" ]] && exit 0
# Your condition here
if [[ condition_met ]]; then
jq -n \
--arg reason "[HOOK] Your message to Claude" \
'{decision: "block", reason: $reason}'
fi
exit 0
SKILL_SCRIPT_EOF
```
**Key points**:
1. Use `jq -n` to generate valid JSON
2. Include `"decision": "block"` for visibility
3. Exit with code 0
4. The "blocking error" label is cosmetic - operation continues
---
## Language choice: shell vs Bun/TypeScript
**Default to shell (bash) for hooks.** A hook fires on every matching event and ~95% bail out immediately, so **process-startup latency dominates** — not the logic. Measured on a workstation: a full bash hook (keyword match + bail) ≈ **7 ms**; a _do-nothing_ Bun script ≈ **17 ms**. bash also needs no runtime dependency and matches existing hook convention. Keep the hot-path bail-out a bash builtin `case` (no `jq`/process spawn) — see the pre-jq-fastpath in the devops-tools SCS hooks.
**Reach for Bun/TypeScript only when a hook does real work** that amortizes the ~10 ms startup tax: parsing/transforming structured data, calling an API, sharing typed modules across many hooks, or maintaining state. For simple match-and-emit reminders, shell wins on speed, durability, and convention. (This is the language doctrine's "existing convention + SOTA-native ecosystem override the Bun-first default" clause in action.)
---
## TodoWrite Templates
### Creating a PostToolUse Hook
```markdown
1. [pending] Create hook script with shebang and set -euo pipefail
2. [pending] Parse PAYLOAD from stdin with jq
3. [pending] Add condition check for when to trigger
4. [pending] Output JSON with decision:block pattern
5. [pending] Register hook in hooks.json with matcher
6. [pending] Test by editing a matching file
7. [pending] Verify Claude sees the message in system-reminder
```
### Debugging Invisible Hook Output
```markdown
1. [pending] Verify hook executes (add debug log to /tmp)
2. [pending] Check JSON format is valid (pipe to jq .)
3. [pending] Confirm decision:block is present in output
4. [pending] Verify exit code is 0
5. [pending] Check hooks.json matcher pattern
6. [pending] Restart Claude Code session
```
---
## Reference Documentation
- [Lifecycle Reference](./references/lifecycle-reference.md) - All 10 hook events, diagrams, use cases, configuration pitfalls
- [Visibility Patterns](./references/visibility-patterns.md) - Full exit code and JSON schema details
- [Hook Templates](./references/hook-templates.md) - Copy-paste templates for common patterns
- [Debugging Guide](./references/debugging-guide.md) - Troubleshooting invisible output
---
## Post-Change Checklist (Self-Evolution)
When this skill is updated:
- [ ] Update [evolution-log.md](./references/evolution-log.md) with discovery
- [ ] Verify code examples still work
- [ ] Check if ADR needs updating: [PostToolUse Hook Visibility ADR](../../../../docs/adr/2025-12-17-posttooluse-hook-visibility.md)
---
## Related Resources
- [ADR: PostToolUse Hook Visibility](../../../../docs/adr/2025-12-17-posttooluse-hook-visibility.md)
- [GitHub Issue #3983](https://github.com/anthropics/claude-code/issues/3983) - Original bug report
- [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks) - Official documentation
---
## Troubleshooting
| Issue | Cause | Solution |
| -------------------------- | ------------------------------ | --------------------------------------------------- |
| Hook output not visible | Missing decision:block in JSON | Add `"decision": "block"` to JSON output |
| JSON parse error in hook | Invalid JSON syntax | Use `jq -n` to generate valid JSON |
| Hook not executing | Wrong matcher pattern | Check hooks.json matcher regex matches tool name |
| Plain text output ignored | Only JSON parsed | Wrap output in JSON with decision:block |
| Exit code 2 behavior | stderr used instead of stdout | Use exit 0 with JSON, or exit 2 for stderr messages |
| Session not seeing changes | Hooks cached | Restart Claude Code session after hook changes |
| Verbose mode not showing | Disabled by default | Enable verbose mode in Claude Code settings |
| jq command not found | jq not installed | `brew install jq` |
## Post-Execution Reflection
After this skill completes, check before closing:
1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills