Skills、Subagents、Hooks

Cursor 的高级定制不是为了显得复杂，而是为了把反复出现的好做法沉淀下来。Skills 封装多步流程，Subagents 做上下文隔离和专业分工，Hooks 在固定事件上执行检查或拦截。

1. 先分清四种机制

flowchart TD
  Need["重复出现的问题"] --> Rule["Rule: 短约束"]
  Need --> Skill["Skill: 多步流程"]
  Need --> Subagent["Subagent: 独立角色"]
  Need --> Hook["Hook: 事件触发脚本"]

判断方式：

• Rule：一句长期约束，例如“共享组件不得写业务文案”。
• Skill：一套可复用流程，例如“发版检查：diff、test、changelog、敏感信息扫描”。
• Subagent：一个独立角色，例如 verifier、security-auditor、debugger。
• Hook：固定时机自动运行，例如 edit 后 format，shell 前拦截网络命令。

不要把所有东西都塞进 Rule。Rule 太长会污染上下文；Skill、Subagent、Hook 分别处理不同复杂度。

2. Skills：把流程打包成能力

官方 Skills 文档说明，Agent Skills 可以包含 domain knowledge、workflows、scripts、templates、references，并按需 progressive 加载——也就是 Skill 的内容只在 Agent 判断当前任务匹配它的 description 时才装入上下文，不会一次塞满。它适合详细、多步、可复用流程。

最小结构：

.cursor/
  skills/
    release-check/
      SKILL.md
      scripts/
        audit.sh
      references/
        checklist.md

SKILL.md 必须有 frontmatter（YAML 头部，文件最上方 --- 之间的元数据块），核心字段是 name 和 description，可用 paths 限定匹配文件。

适合做 Skill 的场景：

• 发版检查。
• 安全审计。
• 文档发布前 QA。
• 组件生成流程。
• 数据迁移预检。
• 文章终稿复检。

不适合 Skill 的场景：

• 只有一句编码偏好，用 Rule。
• 需要在每次 shell 命令前拦截，用 Hook。
• 需要独立上下文长期研究或验证，用 Subagent。

3. Subagents：把噪声和责任隔离

官方 Subagents 文档说明，每个 subagent 有自己的 context window（上下文窗口，模型一次能看到的总信息量），可以处理特定任务，再把结果返回给 parent agent。

它适合两类任务：

• 探索很吵：大量搜索、日志、命令输出不应该占满主对话。
• 责任要分开：实现者不应该同时充当唯一验证者。

常见角色：

• explorer：只读调查代码结构。
• verifier：验证已完成工作是否真实通过。
• security-auditor：检查敏感路径和漏洞风险。
• debugger：用独立上下文复现并定位问题。

一个 verifier subagent 应该默认 readonly：

---
name: verifier
description: Validates completed work and reports missing implementation, failed checks, and residual risk.
model: inherit
readonly: true
---

Validate the claimed work. Do not implement fixes.
Report what passed, what failed, and what evidence is missing.

这样可以避免“发现问题的人顺手改代码”，导致验证和实现混在一起。

4. Hooks：固定事件上的脚本和策略

官方 Hooks 文档说明，hooks 是 spawned processes（派生进程，hook 在 Cursor 之外独立启动的子进程），通过 stdin / stdout（标准输入输出）传 JSON，在 agent loop 的指定阶段运行。

适合 hooks：

• 文件编辑后运行 formatter。
• shell 执行前检查风险命令。
• MCP 调用前审查 tool arguments。
• sessionStart 注入项目上下文。
• afterFileEdit 扫描 secret 或 PII（Personally Identifiable Information，个人可识别信息，如手机号 / 邮箱 / 身份证号）。

不适合 hooks：

• 产品判断。
• 大量上下文推理。
• 需要人工审查的复杂决策。
• 失败后会造成生产副作用的自动流程。

重要边界：command hook exit code 2 才是阻止动作；其它非零通常是 hook failed，action 默认继续，也就是 fail-open（失败默认放行，与 fail-closed 失败默认拦截相反）。安全类 hook 不能只靠"脚本不报错"来保证——必须 explicit return exit code 2 才算拦下。配置 hooks 时也建议带上 timeout 和 log 路径，避免长时间挂起或安全 hook 静默失败。

5. 什么时候沉淀

不要过早自动化。一个 prompt 是否值得沉淀，至少看三个条件：

1. 已经重复使用三次以上。
2. 输入、输出和验收标准清楚。
3. 失败后有低成本回退方式。

沉淀顺序建议：

flowchart LR
  Prompt["一次性 Prompt"] --> Rule["短约束进 Rule"]
  Prompt --> Skill["多步流程进 Skill"]
  Skill --> Subagent["需要独立验证时拆 Subagent"]
  Skill --> Hook["需要固定触发时加 Hook"]

如果流程还不稳定，先保留成 prompt 或 checklist。Hook 尤其谨慎，因为它会在固定时机稳定触发，错误逻辑会稳定制造损害。

6. 一个发版检查例子

你每次发布前都要做：

• 看 git diff。
• 跑 lint / test / build。
• 扫描 secret。
• 生成 changelog。
• 检查文档链接。
• 输出发布风险。

拆法：

• 写一个 release-check Skill，描述步骤、脚本和输出格式。
• 写一个 readonly verifier Subagent，独立检查发布结果。
• 写一个 beforeShellExecution Hook，阻止未确认的 deploy 命令。
• 用 Project Rules 保留“发布前必须跑 build 和链接检查”的短约束。

这比把所有内容写进一个巨长 Always Apply rule 更可维护。

7. 商业级落地清单

上线前检查：

• Skill 的 description 足够具体，Agent 能判断何时调用。
• Skill scripts 有 --help 或清晰参数说明。
• Subagent 的 description 写清触发场景。
• Verifier / auditor 默认 readonly。
• Hook 有日志、timeout 和失败策略。
• 安全类 Hook 的 deny 路径可测试。
• Project-level 文件进入 Git，可被 review。
• User-level 文件不承载团队强规则。

官方来源

• Cursor Skills：官方 Skill 目录、SKILL.md、frontmatter、paths、scripts 和迁移说明。
• Cursor Subagents：官方 subagent 上下文隔离、并行、内置 agents、自定义字段和调用方式。
• Cursor Hooks：官方 hooks 事件、配置、command hooks、prompt hooks 和 exit code。

接下来去哪