Claude Code Hook 开发指南
为 Claude Code 插件设计、配置、验证和调试事件驱动的 Hook。
内容强调输入校验、路径安全、变量引用、超时和用户确认，并警告不要记录敏感信息；但外部 Slack、数据库、指标和审计日志示例会传输或持久化工具输入、命令、用户信息及环境数据，未说明同意、最小权限、脱敏、访问控制或回滚。validate-write.sh 还把未转义路径拼入 JSON，可能破坏输出或造成注入。故扣除数据流透明度、隔离和恢复相关分数。
覆盖配置、事件、输入、退出码和调试流程，且提供示例脚本；但文档先称插件 hooks.json 使用 hooks 包装格式，后续插件配置示例又使用顶层事件，存在关键配置矛盾。Prompt hooks 的支持事件列表与 PostToolUse 示例不一致；部分引用的校验、测试脚本未在所给材料中提供。示例还存在脆弱的字符串匹配、symlink/路径边界未处理，以及 hook-linter 在 set -e 下使用 ((warnings++)) 可能提前退出。静态证据不足，按上限保守评分。
目标用户、触发短语、主要事件和 command/prompt 两类场景较明确；但未系统说明不适用场景、平台限制、依赖安装、权限前提和不同 Claude Code 版本差异。内容主要面向英文 Bash/Unix 环境，没有中文说明或中文示例；依赖 Claude Code、bash、jq 及可能的海外模型/服务，面向中国大陆网络的可达性和降级方案未交代。
SKILL.md 有名称、描述、版本、分层章节、示例、引用资料和调试工作流；仓库材料提供 Apache-2.0、官方维护背景和 README 的安装说明。扣分原因是缺少 changelog、兼容性矩阵、依赖安装说明、明确的更新责任/支持渠道和完整故障排查；文档引用的 references、examples、scripts 并非全部在给定材料中可核验，且部分文档示例互相不一致。
对创建常见 PreToolUse、Stop、SessionStart 等 hook 提供了可直接改写的配置和脚本模式，核心任务在 happy path 上可完成；但 prompt hook 的决策可靠性、并行执行语义、输出格式和权限行为缺少实际结果证明，示例安全检查也容易漏报或误报，部分脚本不可直接视为生产就绪。静态校准限制 effectiveness 不超过 7。
材料包含具体配置、脚本、测试命令、linter 和仓库 CI/许可证等可审计内容，达到有限可复核性；但本次未执行任何脚本，未提供真实测试结果、覆盖率、CI 对该 skill 关键路径的测试证据或多来源交叉验证。CI 内容主要针对插件仓库和 MCP URL，不证明本 skill 的行为。静态校准限制 verifiability 不超过 5。
- 不要直接部署示例中的 Slack、数据库、指标或审计日志集成；先明确用户同意、数据最小化、脱敏、凭据保护和访问控制。
- 在采用配置前解决 hooks.json 包装格式与顶层事件格式的矛盾，并核验当前 Claude Code 版本支持的事件、字段、决策输出和并行语义。
- 将示例脚本视为教学代码：补充 JSON 转义、规范化路径、symlink 防护、完整命令解析、依赖检查和可恢复的失败处理。
- 给定材料未证明引用的 validate-hook-schema.sh、test-hook.sh 等脚本存在或可运行；安装前应逐项核对实际 revision 内容。
- 面向中国大陆用户时，应确认 Claude Code、模型服务及外部集成的网络可达性，并准备无外部服务的降级方案。
它能做什么 & 适用场景
这是 anthropics/claude-plugins-official 中 plugin-dev 插件下的 hook-development 技能，专门指导 Claude Code 插件 Hook 的实现。它覆盖基于提示词的 Hook、命令 Hook、事件匹配器、结构化输入输出、安全校验和生命周期限制。内容尤其适合需要在工具执行前后进行验证、拦截危险操作、加载上下文或检查任务完成度的开发者。它依赖 Claude Code 的 Hook 配置和命令行调试流程，因此移植到其他客户端需要适配。
指导用户在 hooks/hooks.json 或 .claude/settings.json 中配置 Hook；为 PreToolUse、PostToolUse、Stop、SubagentStop、UserPromptSubmit、SessionStart、SessionEnd、PreCompact 和 Notification 编写匹配规则；配置 prompt 或 command 类型 Hook；通过 stdin 读取 JSON 事件数据，并生成结构化 JSON 决策、反馈或系统消息；使用 Bash、jq、${CLAUDE_PLUGIN_ROOT}、claude --debug 以及提供的校验、测试和 lint 脚本完成验证与调试。
- Claude Code 插件开发者希望在 Write 或 Edit 工具执行前检查路径遍历、凭据和敏感文件。
- 团队希望使用 Stop 或 SubagentStop Hook 检查测试、构建和任务完成情况。
- 开发者需要在 SessionStart 时加载项目上下文并持久化环境变量。
- 插件需要对 MCP 工具、Bash 命令或文件操作应用匹配规则和安全策略。
- 维护者希望在不改变插件核心代码的情况下，通过标志文件或配置文件临时启用严格校验。
优缺点一览
- 覆盖主要 Hook 事件、配置格式、输入输出和退出码。
- 同时讲解推荐的 prompt Hook 与确定性的 command Hook。
- 包含路径安全、输入校验、变量引用、超时和并行执行等实践。
- 提供校验脚本、测试脚本、lint 工具和示例脚本的使用说明。
- 内容面向 Claude Code 插件 Hook，不能直接作为通用 Agent Skills Hook 规范使用。
- Hook 在会话启动时加载，配置或脚本变更需要重启 Claude Code。
- 并行执行的 Hook 不共享输出且顺序不确定，复杂流程需要自行设计独立性。
- 材料没有给出跨平台测试结果，也没有证明所有示例在不同环境中均可用。
如何安装
该技能位于仓库的 plugins/plugin-dev/skills/hook-development/SKILL.md。仓库 README 说明，插件可在 Claude Code 中使用 /plugin install {plugin-name}@claude-plugins-official 安装，或通过 /plugin > Discover 浏览安装；材料未提供该技能单独安装的确切插件名或命令。
如何使用
在 Claude Code 中提出诸如“create a hook”“add a PreToolUse hook”“block dangerous commands”或“implement prompt-based hooks”等请求。实现时选择 prompt 或 command Hook，编辑 hooks/hooks.json，命令路径使用 ${CLAUDE_PLUGIN_ROOT}，再运行 scripts/validate-hook-schema.sh hooks/hooks.json、scripts/test-hook.sh，并用 claude --debug 测试。Hook 配置变更需要重启 Claude Code。