create-hooks

钩子是 Claude Code 的事件驱动自动化功能，可在工具使用、会话事件和用户交互时执行 shell 命令或大模型提示词。本技能将教你如何创建、配置和调试钩子，用于验证命令、自动化工作流、注入上下文，以及实现自定义完成条件。

钩子无需修改核心代码，即可通过编程方式控制 Claude 的行为，从而实现项目专属的自动化、安全检查和工作流定制。

钩子是 shell 命令或由大模型评估的提示词，可响应 Claude Code 事件执行。它们按照事件层级运行：事件（PreToolUse、PostToolUse、Stop 等）触发匹配器（工具模式），匹配器再触发钩子（命令或提示词）。钩子可以阻止操作、修改工具输入、注入上下文，也可以仅观察并记录 Claude 的操作。

<quick_start>

1. 创建钩子配置文件：
   • 项目级：.claude/hooks.json
   • 用户级：~/.claude/hooks.json
2. 选择钩子事件（触发时机）
3. 选择钩子类型（命令或提示词）
4. 配置匹配器（哪些工具会触发钩子）
5. 使用 claude --debug 进行测试

**记录所有 bash 命令**：

.claude/hooks.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \\\"No description\\\")\"' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ]
  }
}

此钩子：

• 在每次使用 Bash 工具前（PreToolUse）触发
• 执行 command（而不是大模型提示词）
• 将命令及其说明记录到文件中

</quick_start>

<hook_types>

事件	触发时机	能否阻止？
PreToolUse	工具执行前	可以
PostToolUse	工具执行后	不可以
UserPromptSubmit	用户提交提示词时	可以
Stop	Claude 尝试停止时	可以
SubagentStop	子 Agent 尝试停止时	可以
SessionStart	会话开始时	不可以
SessionEnd	会话结束时	不可以
PreCompact	上下文压缩前	可以
Notification	Claude 需要输入时	不可以

阻止型钩子可以返回 "decision": "block" 来阻止操作。详细用例请参阅 references/hook-types.md。 </hook_types>

<hook_anatomy> <hook_type name="command"> 类型：执行 shell 命令

适用场景：

• 简单验证（检查文件是否存在）
• 记录日志（追加到文件）
• 外部工具（格式化工具、代码检查工具）
• 桌面通知

输入：通过 stdin 传入 JSON 输出：通过 stdout 输出 JSON（可选）

{
  "type": "command",
  "command": "/path/to/script.sh",
  "timeout": 30000
}

</hook_type>

<hook_type name="prompt"> 类型：由大模型评估提示词

适用场景：

• 复杂的决策逻辑
• 自然语言验证
• 上下文感知检查
• 需要推理的情况

输入：包含 $ARGUMENTS 占位符的提示词 输出：包含 decision 和 reason 的 JSON

{
  "type": "prompt",
  "prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}

</hook_type> </hook_anatomy>

匹配器用于筛选会触发钩子的工具：

{
  "matcher": "Bash",           // Exact match
  "matcher": "Write|Edit",     // Multiple tools (regex OR)
  "matcher": "mcp__.*",        // All MCP tools
  "matcher": "mcp__memory__.*" // Specific MCP server
}

不设置匹配器：钩子对所有工具触发

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [...]  // No matcher - fires on every user prompt
      }
    ]
  }
}

<input_output> 钩子通过 stdin 接收 JSON，其中包含会话信息、当前目录和事件专属数据。阻止型钩子可以返回 JSON，以批准或阻止操作，或修改输入。

输出示例（阻止型钩子）：

{
  "decision": "approve" | "block",
  "reason": "Why this decision was made"
}

各钩子类型的完整数据结构请参阅 references/input-output-schemas.md。 </input_output>

<environment_variables> 钩子命令中可用：

变量	值
$CLAUDE_PROJECT_DIR	项目根目录
${CLAUDE_PLUGIN_ROOT}	插件目录（仅限插件钩子）
$ARGUMENTS	钩子输入 JSON（仅限提示词钩子）

示例：

{
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
}

</environment_variables>

<common_patterns> 需要输入时发送桌面通知：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

阻止具有破坏性的 git 命令：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

编辑后自动格式化代码：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_PROJECT_DIR",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

在会话开始时添加上下文：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
          }
        ]
      }
    ]
  }
}

</common_patterns>

始终使用调试标志测试钩子： ```bash claude --debug ``` 这会显示哪些钩子匹配、命令执行情况和输出。常见问题及解决方案请参阅 [references/troubleshooting.md](references/troubleshooting.md)。

<reference_guides> 钩子类型和事件：references/hook-types.md

• 钩子事件完整列表
• 各事件的触发时机
• 各事件的输入／输出架构
• 阻塞与非阻塞钩子

命令钩子与提示词钩子：references/command-vs-prompt.md

• 决策树：选择哪种类型
• 命令钩子的模式和示例
• 提示词钩子的模式和示例
• 性能注意事项

匹配器和模式：references/matchers.md

• 用于工具匹配的正则表达式模式
• MCP 工具匹配模式
• 多个工具匹配
• 匹配器问题的调试

输入／输出架构：references/input-output-schemas.md

• 各钩子类型的完整架构
• 字段说明和类型
• 钩子专用的输出字段
• 各事件的 JSON 示例

实用示例：references/examples.md

• 桌面通知
• 命令验证
• 自动格式化工作流
• 日志记录和审计跟踪
• 停止逻辑模式
• 会话上下文注入

故障排除：references/troubleshooting.md

• 钩子未触发
• 命令执行失败
• 提示词钩子问题
• 权限问题
• 超时处理
• 调试工作流 </reference_guides>

<security_checklist> 关键安全要求：

• 防止无限循环：在 Stop 钩子中检查 stop_hook_active 标志，避免递归触发
• 超时配置：设置合理的超时时间（默认值：60s），避免进程挂起
• 权限验证：确保钩子脚本具有可执行权限（chmod +x）
• 路径安全：使用包含 $CLAUDE_PROJECT_DIR 的绝对路径，避免路径注入
• JSON 验证：使用 jq 验证钩子配置，以便在使用前发现语法错误
• 选择性阻塞：谨慎使用阻塞钩子，避免干扰工作流

测试流程：

# Always test with debug flag first
claude --debug

# Validate JSON config
jq . .claude/hooks.json

</security_checklist>

<success_criteria> 可正常工作的钩子配置应满足以下条件：

• .claude/hooks.json 中的 JSON 有效（已使用 jq 验证）
• 根据使用场景选择了合适的钩子事件
• 匹配器模式正确，能够匹配目标工具
• 命令或提示词能够无错误执行
• 输出架构正确（阻塞钩子包含 decision/reason）
• 使用 --debug 标志进行测试，显示预期行为
• Stop 钩子中没有无限循环（会检查 stop_hook_active 标志）
• 设置了合理的超时时间（尤其是外部命令）
• 使用文件路径时，脚本文件具有可执行权限 </success_criteria>