用途
Claude Code Hooks 是一个关于创建 Claude Code 钩子（hooks）的元参考技能，用于构建由 Claude Code 事件触发的自动化。它给出的是一套编写事件驱动钩子的规范与模板，适合需要在 Claude Code 各生命周期节点插入自定义逻辑的场景。
主要能力
该技能梳理了 Claude Code 的钩子事件体系，可用于：为 Claude Code 构建事件驱动自动化；创建 PreToolUse 守卫以拦截危险命令；实现 PostToolUse 的格式化、lint 或审计；添加 Stop 钩子用于测试或通知；配置 SessionStart/SessionEnd 进行环境管理；以及在无头模式下将 Claude Code 与 CI/CD 管线集成。
文档中列出的事件包括：SessionStart（会话开始/恢复，用于初始化环境）、UserPromptSubmit（用户提交提示，用于预处理/校验输入）、PreToolUse（工具执行前，用于校验、拦截危险命令）、PermissionRequest（权限对话框显示时，用于自动允许/拒绝权限）、PostToolUse（工具成功后，用于格式化、审计、通知）、PostToolUseFailure（工具失败后，用于捕获失败、补充指引）、SubagentStart（子代理生成时，用于检查子代理元数据）、Stop（Claude 结束时，用于运行测试、总结）、SubagentStop（子代理结束时，用于核验完成情况）、Notification（收到通知时，用于告警集成）、PreCompact（上下文压缩前，用于保留关键上下文）、Setup（--init/--maintenance，用于初始化仓库/环境）、SessionEnd（会话结束时，用于清理、保存状态）。
使用方式
钩子脚本通常放在 .claude/hooks/ 目录下，例如 pre-tool-validate.sh、post-tool-format.sh、post-tool-audit.sh、stop-run-tests.sh、session-start-init.sh。配置写在 settings.json 的 hooks 字段中，按事件名组织，可设置 matcher 来过滤触发的工具（精确匹配如 Write、正则如 Edit|Write 或 Notebook.*、全部匹配用 * 或省略），并用 type 指定 command 或 prompt，通过 command 指定脚本路径（可使用 $CLAUDE_PROJECT_DIR）。
执行模型方面：钩子通过 stdin 接收 JSON 载荷（应视为不可信输入），并以你的用户权限运行（在 Bash 工具沙箱之外）。单个钩子命令默认超时为 60 秒；所有匹配的钩子并行运行；完全相同的命令会被去重。
钩子输入示例为包含 hook_event_name、tool_name、tool_input 的 JSON。可用的 shell 环境变量包括 CLAUDE_PROJECT_DIR、CLAUDE_PLUGIN_ROOT（仅插件钩子）、CLAUDE_CODE_REMOTE、CLAUDE_ENV_FILE。
退出码语义：0 表示成功，写入 stdout 的 JSON 会被解析用于结构化控制；2 表示阻塞性错误，stderr 成为消息且 stdout 中的 JSON 被忽略；其他值表示非阻塞错误，执行继续，stderr 在 verbose 模式下可见。对于 UserPromptSubmit、SessionStart 和 Setup，非 JSON 的 stdout（退出码 0）会被注入 Claude 的上下文；其他多数事件只在 verbose 模式显示 stdout。
决策控制与输入修改（v2.0.10+）：PreToolUse 钩子可以 allow/deny/ask，并可通过 updatedInput 修改工具输入。输出使用 hookSpecificOutput 结构，包含 hookEventName、permissionDecision、permissionDecisionReason、updatedInput、additionalContext。旧的 decision/reason 字段已弃用，建议使用 hookSpecificOutput 字段。
文档还提供了提示词型钩子（type: "prompt"），用于复杂决策，适合 Stop 与 SubagentStop 决策；其响应结构为允许 {"ok": true}，阻止 {"ok": false, "reason": "..."}。可以将命令型与提示词型钩子组合使用：命令钩子做快速确定性检查，提示词钩子做需要判断的决策。
适用场景与限制
适用于需要为 Claude Code 增加安全防护（如拦截 rm -rf /、阻止对 main/master 的强制推送、提示凭据泄露）、自动化代码质量（保存后格式化、安全审计）、会话生命周期管理（初始化、清理）、以及 CI/CD 无头集成的开发者。
限制与注意事项：钩子接收的输入应视为不可信，必须校验并正确加引号、使用绝对路径、避免对不可信输入使用 eval、脚本顶部使用 set -euo pipefail、保持钩子快速（<1 秒）、记录操作以便审计、部署前手动测试。所有匹配的钩子并行执行，因此无法保证顺序；若需要严格顺序（如格式化→lint→测试），应编写一个包装脚本按序执行。官方文档链接与更多资料见 skills.sh 的对应页面。