该技能聚焦 hooks.json 的编写与 hook 脚本设计,插件架构与 rules 另见其他文档。
用途:在 Claude Code 中通过 hooks 对工具调用做确定性检查、上下文注入或验证。
三种 hook 类型:command 运行 shell 脚本并从 stdin 读 JSON,适合正则、文件存在、JSON 校验等确定性检查;prompt 向上下文中注入文本,属于提示类;agent 启动验证智能体,用于复杂语义与多文件检查。选择流程:确定性检查用 command,需要 AI 判断用 agent,否则用 prompt。
阻断与提示:PreToolUse 配合 deny 可阻止工具执行,用于硬性质量门槛,如测试未过、文件超限、危险操作;PostToolUse 的 message 为提示,用于建议与提醒。经验法则是只阻断你会在代码评审中拒绝的内容。
事件选择:PreToolUse 在工具执行前触发,用于阻止与校验;PostToolUse 成功后触发,用于后续动作;PostToolUseFailure 用于错误恢复;UserPromptSubmit 用于上下文注入;Stop 用于清理与总结;SessionStart 用于环境检查。
matcher:使用正则匹配工具名,仅适用于 PreToolUse、PostToolUse、PostToolUseFailure。示例包括 "Bash"、"Write|Edit"、"mcp__.*" 等,部署前应测试匹配范围。
可移植路径:脚本路径应使用 ${CLAUDE_PLUGIN_ROOT},避免硬编码绝对路径。脚本需有 shebang、可执行权限,并向 stdout 输出合法 JSON,调试信息写入 stderr。
失败策略:fail-open 在脚本崩溃时放行,适合提示类与非关键检查;fail-closed 在崩溃时拒绝,仅用于安全关键场景,如阻止强推 main、密钥检测。
常见错误包括在 PostToolUse 阻断、事件大小写错误、脚本无执行权限、缺少 shebang、硬编码路径、stdout 混入调试、未设 timeout、matcher 过宽、缺少失败包装。部署前应按清单逐项核对。