技能介绍

要解决什么问题

在 Cursor 里让 Agent 在特定时机执行自定义逻辑——审计终端命令、拦截危险工具调用、在编辑后自动格式化、或在子任务结束后追加跟进——需要正确配置 Hooks：hooks.json、事件类型、matcher，以及通过 stdin/stdout 交换 JSON 的命令或提示钩子。手写时容易选错作用域（项目 .cursor/ 与用户 ~/.cursor/）、路径相对基准不一致，或 matcher 用了 POSIX 正则导致钩子根本不触发。

技能如何引导实现

本技能要求你在写文件前先澄清六件事：作用域、触发事件、行为（审计 / 拒绝 / 改写输入 / 注入上下文）、实现方式（command 或 prompt）、过滤条件、以及失败时 fail open 还是 fail closed。随后按窄事件选型（例如拦 Shell 用 beforeShellExecution，改工具入参用 preToolUse），创建或更新对应位置的 hooks.json（schema version 1），并在 hooks/ 下落地可执行脚本。

实现流程强调可验证性：先无 matcher 或最简单 matcher 跑通；命令钩子检查 shebang、chmod +x 以及 jq/python3 等依赖是否在钩子进程的 $PATH 上；按事件只返回支持的输出字段（如 preToolUse 的 permission、updated_input）。文档内附事件速查表与最终检查清单，便于在 Cursor Hooks 设置页或 Hooks 输出通道里对照调试。

适用边界与注意点

项目钩子适合进仓库、团队共享；用户钩子适合个人策略，路径写法与项目级不同。
命令钩子默认非 0 退出（除退出码 2 表示拒绝）多为 fail open；需要「钩子挂了也拦截」时显式设 failClosed: true。
复杂过滤可先写在脚本里，matcher 稳定后再收紧；编辑已有配置时只改相关条目，保留无关 hook 定义。

截图预览

使用场景

在团队仓库里统一拦截 `git push --force`、生产环境部署类 Shell，需在 Agent 执行前用 `beforeShellExecution` 做 allow/deny。
Agent 用 Write/Tab 改完代码后希望自动跑 formatter，需挂 `afterFileEdit` 并在脚本里按文件类型调用本地 CLI。
担心提示词里误贴 API Key，要在发送前用 `beforeSubmitPrompt` 做策略检查或拒绝提交。
用 Task 子代理做探索循环时，想在 `subagentStop` 返回 `followup_message` 自动追加下一步，而不只靠对话口述。