---
title: "Skills、Subagents、Hooks"
description: "把 Cursor 从一次性会话升级成可复用、可分工、可治理的工作流系统。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **本章目标**：你会判断一段经验应该写成 Rule、Skill、Subagent 还是 Hook，并知道这些机制各自的风险边界。

## 1. 先分清四种机制

```mermaid
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` 时才装入上下文，不会一次塞满。它适合详细、多步、可复用流程。

最小结构：

```text
.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：

```markdown
---
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. 失败后有低成本回退方式。

沉淀顺序建议：

```mermaid
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](https://cursor.com/docs/skills.md)：官方 Skill 目录、`SKILL.md`、frontmatter、paths、scripts 和迁移说明。
- [Cursor Subagents](https://cursor.com/docs/subagents.md)：官方 subagent 上下文隔离、并行、内置 agents、自定义字段和调用方式。
- [Cursor Hooks](https://cursor.com/docs/hooks.md)：官方 hooks 事件、配置、command hooks、prompt hooks 和 exit code。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先理解 MCP、Browser、Terminal 的权限边界。" href="/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
  <Card title="下一篇" description="继续把 Cursor Agent 带到 CLI、Headless 和 CI。" href="/docs/cursor/understanding/08-cli-headless-automation" />
  <Card title="官方 Skills" description="查看官方重组页里的 Skill 结构和迁移边界。" href="/docs/cursor/official/02-context-customization/22-skills" />
</Cards>
