HookDevelopment（钩子开发技能）Skill 如何实现事件驱动自动化？

钩子开发技能：让 Claude 代码插件的每一次动作都可验证、可拦截、可自动化

核心结论速览

它是什么：钩子开发技能（HookDevelopment）是一份围绕 Claude 代码插件「钩子（Hooks）」的完整实践指南，把 9 类钩子事件、两种钩子类型、两套配置格式、输入输出契约与安全规范一次性讲透。
解决什么问题：不用再翻文档猜格式，不用再为「插件 hooks.json 为什么没生效」「输出该返回什么字段」反复试错。
最大亮点：重点推荐基于提示（prompt）的钩子——用自然语言推理做上下文感知的决策，替代脆弱的 bash 判断逻辑。
覆盖场景：危险命令拦截、文件写入安全校验、任务完成度把关、会话启动自动加载上下文、上下文压缩前保存关键信息等。
使用门槛：需要具备基础的 JSON 与 Shell 能力，钩子改动必须重启会话才能生效，这是最容易踩的坑。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

钩子开发技能（英文名：HookDevelopment，技能 ID：12189，版本 0.1.0）是一个面向 Claude 代码插件开发者的技能，专门解决「钩子怎么写、写到哪、写成什么样」的问题。

它解决的真实痛点

钩子本质上是事件驱动的自动化脚本，在 Claude 代码执行工具调用、会话开始、代理准备停止等关键时刻被触发。它的价值很高——可以拦截危险命令、校验文件写入路径、强制「测试跑完才能收工」——但落地门槛也不低：

钩子有两个配置文件位置（插件 hooks/hooks.json 与用户 .claude/settings.json），两者的外层结构完全不同，一个是包装器格式，一个是直接格式，写错就静默不生效；
不同事件（PreToolUse、Stop、UserPromptSubmit 等）返回的 JSON 字段各不相同，permissionDecision、decision、continue、systemMessage 各有语义；
钩子命令里的路径必须可移植，硬编码路径会在别人机器上直接崩掉；
钩子在会话启动时加载，改完配置不重启就永远看不到效果。

这个技能就是把这些「隐性知识」结构化成一份可执行的说明书。

如何「一键安装」并验证生效

AI 技能的安装通常通过技能市场、插件市场或本地技能目录完成，具体入口与命令以官方说明为准。通用流程如下：

准备前提：本地已安装并可正常运行 Claude 代码 CLI；确认你的账号或工作区支持安装外部技能；如需开发插件钩子，先准备好插件目录结构（含 hooks/ 目录）。
执行安装：在技能市场/插件市场中搜索「钩子开发」或「HookDevelopment」，点击安装或一键添加到当前环境；若为本地技能，则按官方说明放入技能目录。
验证是否生效：新开一个会话，直接用自然语言描述需求，例如「帮我添加一个 PreToolUse 钩子，阻止删除操作」，若技能已加载，回复会围绕钩子事件、配置格式、输出结构展开，而不是泛泛而谈。
验证环境侧能力：在 Claude 代码会话中执行 /hooks 命令可查看当前会话已加载的钩子；启动时加 --debug 参数可看到钩子注册、执行日志与输入/输出 JSON。

2. 该技能的主要功能和特点

9 类钩子事件全覆盖：PreToolUse（工具执行前）、PostToolUse（工具完成后）、UserPromptSubmit（用户提交提示）、Stop（主代理准备停止）、SubagentStop（子代理准备停止）、SessionStart（会话开始）、SessionEnd（会话结束）、PreCompact（上下文压缩前）、Notification（发送通知时），每一类都给出时机说明、示例配置与输出契约。
两种钩子类型，按场景选型：基于提示的钩子用 LLM 做上下文感知决策，适合复杂逻辑与边缘情况；命令钩子执行 bash 脚本做确定性检查，适合快速校验与外部工具集成。技能明确指出「大多数场景优先用提示钩子」。
两套配置格式严格区分：插件 hooks/hooks.json 必须用 {"hooks": {...}} 包装器（可选 description 字段）；用户 .claude/settings.json 则是事件直接位于顶层的直接格式。这是新手最容易写错的地方，技能把它作为「关键点」反复强调。
输入输出契约明确：所有钩子通过 stdin 接收统一 JSON（含 session_id、transcript_path、cwd、permission_mode、hook_event_name），事件特定字段如 tool_name、tool_input、tool_result、user_prompt 可直接在提示中用 $TOOL_INPUT、$USER_PROMPT 引用。
匹配器（matcher）规则清晰：支持精确匹配（Write）、多工具（Read|Write|Edit）、通配符（*）、正则（mcp__.*__delete.*），并提示匹配器区分大小写。
可移植路径规范：命令钩子统一使用 ${CLAUDE_PLUGIN_ROOT} 指向插件目录，避免硬编码路径导致的跨机器失效。
安全最佳实践成体系：输入校验、路径遍历拦截、敏感文件（如 .env）拒绝、变量全部加引号防注入、设置合理超时（命令钩子默认 60 秒、提示钩子默认 30 秒）。
附带实用工具链：validate-hook-schema.sh 校验 hooks.json 结构与语法、test-hook.sh 用样本输入预演、hook-linter.sh 检查脚本规范。
支持临时激活：通过标志文件或配置开关，让严格校验只在需要时开启，避免日常开发被过度拦截。

与普通做法相比强在哪：普通做法是照着一份示例复制粘贴、试错调试；这个技能提供的是选型决策 + 格式契约 + 安全清单 + 调试路径的完整闭环，尤其把「基于提示的钩子」这套较新的 API 用法讲得足够细。

3. 如何使用该技能？

以下为典型的分步骤使用流程，可按需裁剪。

第 1 步：明确要挂钩的事件

先回答「我要在什么时刻介入」。拦危险命令 → PreToolUse；检查编辑结果 → PostToolUse；把关任务是否真的做完 → Stop；会话启动加载项目类型 → SessionStart。

第 2 步：选择钩子类型

需要判断语义、处理边缘情况 → 用提示钩子
需要毫秒级确定性校验、调用外部工具 → 用命令钩子

第 3 步：编写配置（注意格式）

插件内写在 hooks/hooks.json，使用包装器格式：

{
  "description": "代码质量的验证钩子",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "验证文件写入安全性。检查系统路径、凭据、路径遍历、敏感内容。返回 approve 或 deny。",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

如果是写在用户设置的 .claude/settings.json，则去掉外层包装，事件直接放顶层。

第 4 步：如需命令钩子，编写脚本

脚本从 stdin 读取 JSON，处理后输出结构化结果：

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 10
}

第 5 步：理解输出契约

PreToolUse 的输出：

{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": {"field": "modified_value"}
  },
  "systemMessage": "给 Claude 的解释"
}

Stop 钩子的输出：

{
  "decision": "approve|block",
  "reason": "解释原因",
  "systemMessage": "额外上下文"
}

通用输出字段为 continue（false 则停止处理）、suppressOutput（隐藏转录输出）、systemMessage（给 Claude 的消息）。退出码语义：0 成功、2 阻塞错误（stderr 反馈给 Claude）、其他为非阻塞错误。

第 6 步：验证配置

运行 scripts/validate-hook-schema.sh hooks/hooks.json 检查结构，再用 scripts/test-hook.sh 用样本输入预演。

第 7 步：重启会话并调试

钩子在会话开始时加载且不能热替换。修改配置后必须退出并重新运行 claude，然后用 /hooks 查看已加载列表、用 claude --debug 查看执行日志。也可直接测试脚本：

echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \
  bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
钩子开发技能（HookDevelopment）	Claude 代码插件钩子的开发指南与范式库	9 类事件说明、提示/命令双类型、双配置格式、匹配器、输出契约、安全规范、校验脚本	需安装技能；需 JSON 与 Shell 基础	插件作者、团队平台工程师做安全护栏与流程自动化	优势：覆盖全面、格式与坑点讲透、强调可移植路径与安全；不足：需理解事件模型，改动需重启会话
手工编写 settings.json 钩子	官方原生用法，直接配置	支持全部钩子事件与输出结构	门槛最低，但缺少格式校验与选型建议	个人快速试水、单点小需求	优势：零依赖、立即生效；不足：易写错包装器格式、无安全清单、维护成本高
Git 钩子框架（如 pre-commit、Husky）	提交阶段的代码质量闸门	提交前跑 lint、格式化、测试	需配置仓库与本地环境	代码入库前的静态检查	优势：生态成熟、团队通用；不足：只覆盖 git 动作，管不到 AI 代理的工具调用与会话生命周期
CI 流水线（如 GitHub Actions）	持续集成阶段的自动化校验	构建、测试、扫描、部署	需维护流水线配置与运行环境	合并前与发布前把关	优势：权威、可审计；不足：反馈链路长，无法在代理「执行工具的那一刻」实时拦截

选型建议：如果你的诉求是「在 AI 代理动手之前就拦住」，钩子类方案是唯一解；如果只是「代码入库前跑一遍检查」，Git 钩子或 CI 更成熟。两者并不冲突，实际项目中常常三层并用。

5. 该技能的典型应用场景与实际体验情况

场景一：团队架构师设置危险命令护栏

痛点：代理可能执行 rm -rf、写入系统路径或读取 .env 文件。用法：配置 PreToolUse 命令钩子，matcher 设为 Bash，脚本读取 stdin 的 tool_input.file_path，检测到 .. 路径遍历或 .env 时输出 {"decision": "deny", "reason": "敏感文件"} 并以退出码 2 结束。

场景二：插件作者用提示钩子做上下文感知的写入校验

痛点：bash 判断只能做字符串匹配，无法理解「这次写入是否合理」。用法：在 hooks/hooks.json 中为 Write|Edit 挂一个 type: "prompt" 的钩子，提示中列出检查项（系统路径、凭据、路径遍历、敏感内容），要求返回 approve 或 deny。相比硬编码规则，边缘情况处理更自然。

场景三：用 Stop 钩子强制「做完才算完」

痛点：代理过早宣布任务完成，测试没跑、构建没验。用法：Stop 钩子设置提示「验证任务完成情况：测试运行、构建成功、问题已回答。返回 approve 停止或 block 并带原因继续」。当返回 block 时，代理会带着理由继续干活。

场景四：SessionStart 自动加载项目上下文

痛点：每次新会话都要重复交代项目类型、构建命令。用法：命令钩子在会话开始时执行 load-context.sh，并通过 $CLAUDE_ENV_FILE 持久化环境变量，例如 echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"。

实际体验情况

上手难度：中等。事件模型本身直观，真正的门槛在于两套配置格式的区分与输出字段的准确使用，技能把这些全部写清了，照抄示例基本能跑通。
效果：提示钩子在语义判断类任务上表现明显优于纯 bash 规则；命令钩子在确定性检查上延迟可控。
注意事项：① 改配置必须重启会话，否则永远不生效；② 所有匹配钩子并行执行且看不到彼此输出，设计时必须让每个钩子独立；③ 钩子执行顺序不确定，不能依赖先后关系；④ 超时要设置合理，避免长阻塞拖慢每次工具调用；⑤ 不要在钩子里记录敏感信息。

6. 该技能能为用户带来的价值

效率提升：省去在官方文档与试错之间反复横跳的时间。格式、字段、匹配器、退出码一次讲清，把「半天调不通」压缩为「照着写就能跑」。
门槛降低：把「设计模式」级的知识下放——基于提示的钩子让不擅长写 bash 的开发者也能做出上下文感知的校验逻辑。
风险下降：内置的安全最佳实践（输入校验、路径遍历拦截、变量引号、超时设置）直接降低了钩子本身成为安全漏洞的概率。
可量化收益：把重复的评审规则固化为钩子后，每次工具调用都自动过一遍检查；Stop 钩子减少「返工式」往返；SessionStart 省掉每次会话的重复交代。
长期价值：钩子是插件可复用资产。一次写好的校验逻辑可以随插件分发给整个团队，形成统一的工程规范；技能中提到的迁移文档与模式库，也为后续从基础钩子升级到高级钩子留出了路径。

7. 常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认生效？ A：通过技能市场/插件市场搜索「钩子开发」或「HookDevelopment」一键添加，或按官方说明放入本地技能目录（具体入口与命令以官方说明为准）。验证方式：新开会话用自然语言提出钩子相关需求，若能返回事件类型、配置格式与输出字段的具体说明，说明技能已加载。

Q2：它是收费的吗？ A：技能本身的定价与授权方式取决于发布方的说明，请以官方页面标注为准。技能内容依赖 Claude 代码环境，Claude 侧的订阅或额度规则同样以官方说明为准。

Q3：适合谁用？我只写业务代码需要吗？ A：最适合 Claude 代码插件作者、团队平台/效能工程师、以及需要为 AI 代理设置安全护栏的团队。如果你只是日常写业务代码，不涉及插件开发或代理行为约束，优先级可以放低；但如果你曾被「代理误删文件」「任务没做完就收工」坑过，Stop 与 PreToolUse 钩子就非常值得一看。

Q4：为什么我改了 hooks.json 却完全没反应？ A：最常见的原因是没有重启会话。钩子在会话开始时加载且不支持热替换，编辑配置文件、新增脚本、修改命令或提示都必须退出并重新运行 claude 才生效。其次检查格式：插件内必须用 {"hooks": {...}} 包装器，用户设置才是事件直接在顶层的直接格式。可用 claude --debug 查看注册与执行日志。

Q5：提示钩子和命令钩子怎么选？和竞品方案怎么配合？ A：复杂判断、需要理解语义、边缘情况多 → 提示钩子；快速确定性校验、文件系统操作、外部工具集成 → 命令钩子。与 Git 钩子、CI 的分工是：钩子管「AI 代理执行动作的那一刻」，Git 钩子管「代码入库前」，CI 管「合并与发布前」，三者叠加形成完整防线。