Hook Creator 技能

开始时声明： "使用 hook-creator 技能创建/诊断 hooks 配置。"

核心流程

原则： 场景识别 → 模板匹配/对话构建 → 确定配置位置 → 验证 → 写入 → 确认生效。

一、触发关键词

二、模板库

通知类模板

桌面通知（Notification）

用户需求："Claude 完成时通知我"、"需要输入时提醒我"

配置示例：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "<平台命令>" }]
      }
    ]
  }
}

格式化类模板

Prettier 自动格式化（PostToolUse）

用户需求："编辑后自动格式化"、"每次写文件后格式化"

参数化选项：

• 包管理器：npm / bun / yarn / pnpm
• 匹配器：Edit|Write（默认）或仅 Write

配置示例：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r \".tool_input.file_path\" | xargs <包管理器> prettier --write" }
        ]
      }
    ]
  }
}

保护类模板

阻止敏感文件编辑（PreToolUse）

用户需求："阻止修改 .env"、"防止删除重要文件"

参数化选项：

• 受保护模式列表：.env、package-lock.json、.git/、*.secret 等

需要创建脚本文件 .claude/hooks/protect-files.sh：

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r ".tool_input.file_path // empty")

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern \"$pattern\"" >&2
    exit 2
  fi
done
exit 0

配置示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

上下文类模板

压缩后注入上下文（SessionStart）

用户需求："压缩后提醒项目约定"、"每次压缩后注入规则"

参数化选项：

• 注入内容：项目约定、最近工作、提醒事项

配置示例：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo \"Reminder: use Bun, not npm. Run bun test before committing.\"" }
        ]
      }
    ]
  }
}

审计类模板

配置更改审计（ConfigChange）

用户需求："记录配置文件变更"、"审计 settings 修改"

配置示例：

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "jq -c \"{timestamp: now | todate, source: .source, file: .file_path}\" >> ~/claude-config-audit.log" }
        ]
      }
    ]
  }
}

环境类模板

环境变量自动加载（CwdChanged + SessionStart）

用户需求："切换目录时加载 .envrc"、"自动加载 direnv"

配置示例：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "direnv export bash > \"$CLAUDE_ENV_FILE\"" }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          { "type": "command", "command": "direnv export bash > \"$CLAUDE_ENV_FILE\"" }
        ]
      }
    ]
  }
}

权限类模板

自动批准特定权限（PermissionRequest）

用户需求："跳过 ExitPlanMode 提示"、"自动批准某些工具"

参数化选项：

• 目标工具：ExitPlanMode、Bash(git *)、Read 等

配置示例：

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          { "type": "command", "command": "echo \"{\\\"hookSpecificOutput\\\": {\\\"hookEventName\\\": \\\"PermissionRequest\\\", \\\"decision\\\": {\\\"behavior\\\": \\\"allow\\\"}}}\"" }
        ]
      }
    ]
  }
}

高级类模板

基于提示的验证（Stop）

用户需求："停止前检查任务是否完成"、"让 Claude 判断是否可以停止"

配置示例：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

基于代理的验证（Stop）

用户需求："停止前验证测试通过"、"多轮检查后才能停止"

配置示例：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTP 回调（PostToolUse）

用户需求："发送事件到外部服务"、"POST 工具使用记录"

配置示例：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": { "Authorization": "Bearer $MY_TOKEN" },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

三、对话式构建流程

当用户需求不匹配模板时，通过问答逐步收集信息。一次一个问题。

问题序列

Q1: 触发时机

"这个 hook 应该在什么时机触发？"

Q2: 匹配条件

"需要匹配哪些工具或条件？"

根据事件类型提供选项：

可选追问：if 字段（更精确过滤）

"是否需要按命令参数过滤？例如仅匹配 git * 命令？"

Q3: 执行操作

"触发后要执行什么操作？"

根据类型追问具体内容：

• command: "具体命令是什么？"
• prompt: "判断条件是什么？返回什么格式？"
• agent: "验证任务是什么？超时时间？"
• http: "URL 是什么？需要哪些 headers？"

Q4: 是否阻断

"是否需要阻止操作或返回决策？"

Q5: 配置位置

"这个 hook 应该配置在哪里？"

四、验证与写入流程

步骤 0：确定配置位置

根据用户选择，确定目标文件：

• 全局 → ~/.claude/settings.json
• 项目 → .claude/settings.json
• 项目本地 → .claude/settings.local.json

步骤 1：去重检查

读取目标文件，检查是否已存在相同 event+matcher 的 hook。

去重逻辑：

• 相同 event + 相同 matcher → 提示用户选择：
• A) 保留现有 hook
• B) 替换为新 hook
• C) 添加为并行 hook（多个 hook 组）
• 相同 event + 不同 matcher → 直接追加
• 相同 event + 无 matcher → 检查是否已有无 matcher 的 hook

步骤 2：JSON 语法验证

确保生成的配置符合 schema：

• 必须字段：type、command/prompt/url
• matcher 格式正确
• hooks 数组结构正确

步骤 3：命令检查

检查命令依赖：

• jq 是否安装（大多数 hook 需要 JSON 解析）
• 格式化工具是否存在
• 脚本文件是否可执行（提示 chmod +x）
• 平台兼容性（如 osascript 仅 macOS）

步骤 4：合并写入

重要：保留现有配置，追加新 hook。不要替换整个文件。

使用 Edit 工具，在现有 hooks 对象中追加：

{
  "hooks": {
    "ExistingEvent": [...],  // 保留
    "NewEvent": [...]        // 新增
  }
}

如果是首次创建 hooks，添加整个 hooks 块。

步骤 5：确认生效

写入后提示用户：

Hook 已写入 <文件路径>

验证方式：
1. 运行 /hooks 查看配置
2. 触发对应事件测试

注意：如果 hook 未出现在 /hooks 中，可能需要：
- 重启会话（settings watcher 仅监视启动时已有 settings 文件的目录）
- 或打开 /hooks 菜单一次以重新加载配置

五、动态生成

当用户描述不匹配模板的需求时，通过意图识别生成 hook 配置。

意图识别示例

动态生成步骤

1. 提取关键信息：触发时机、目标工具/条件、执行操作、是否阻断
2. 映射到事件类型：根据触发时机选择事件
3. 构建 matcher/if：根据目标工具/条件
4. 构建命令或 prompt：根据执行操作
5. 询问配置位置：全局/项目/项目本地
6. 验证并写入

六、诊断功能

当用户说"检查 hooks"、"优化 hooks"、"hook 不工作"时执行诊断。

诊断项

优化建议

诊断流程

1. 读取所有 settings 文件（全局、项目、项目本地）
2. 合并 hooks 配置进行分析
3. 输出诊断报告和建议列表
4. 用户选择要执行的修复操作

七、Hook 事件完整列表

八、退出代码与 JSON 输出

退出代码

JSON 输出格式（exit 0 时）

PreToolUse 决策：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "原因说明",
    "updatedInput": { "file_path": "修改后的参数" }
  }
}

Stop/PostToolUse 阻止：

{
  "decision": "block",
  "reason": "原因说明",
  "systemMessage": "显示给用户的消息"
}

注入上下文：

{
  "hookSpecificOutput": {
    "hookEventName": "事件名",
    "additionalContext": "注入到 Claude 上下文的文本"
  }
}

九、常见问题排查

十、参考资源

• 官方参考：https://code.claude.com/docs/zh-CN/hooks