Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill hooks-development -a claude-code
Open on GitHub

What 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 PreToolUse or PostToolUse hook
  • 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 AskUserQuestion input

Example prompts for the agent

  • Create a PostToolUse hook that checks project files and sends Claude a message.
  • Debug why Claude cannot see my hook output, and validate the JSON response.
  • Review my PreToolUse hook for AskUserQuestion; leave updatedInput unchanged.

How to install hooks-development

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill hooks-development -a claude-code

2Manually: put the files in place

~/.claude/skills/hooks-development/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hooks-development/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
link-validation link-validation runs an offline lychee pass over a project's markdown and reports broken relative links, root-relative paths and anchors. Handy right before you commit docs. CX Codex +1 135installs session-recovery session-recovery troubleshoots missing Claude Code sessions when claude -r reports no conversations found or files save to incorrect paths. CX Codex +1 135installs session-chronicle session-chronicle connects findings, decisions, and code changes to session UUIDs. Use it when you need to trace where work came from or record session provenance. CX Codex +1 135installs notion-sdk notion-sdk — a skill for managing Notion via the official Python SDK. Creates pages and databases, queries information, adds content blocks — all programmatically. CX Codex +1 133installs asciinema-cast-format asciinema-cast-format is a Claude Code skill that helps parse NDJSON headers and terminal events in asciinema v3 .cast recordings. CX Codex +1 132installs python-workspace python-workspace converts MQL5 indicators to Python and exports MetaTrader 5 data headlessly with automated correlation checks. CX Codex +1 131installs terminal-print terminal-print turns iTerm2 output or a session file into a PDF, then sends it to a network printer. It also provides an AirPrint workaround for blank pages on listed HP LaserJet Pro models. CX Codex +1 131installs doppler-workflows The doppler-workflows skill guides commands that use Doppler secrets for Python package publishing and AWS tasks. It also covers common authentication errors. CX Codex +1 130installs

Project sponsors

Companies that keep this analytics open