---
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="/zh-Hant/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
  <Card title="下一篇" description="繼續把 Cursor Agent 帶到 CLI、Headless 和 CI。" href="/zh-Hant/docs/cursor/understanding/08-cli-headless-automation" />
  <Card title="官方 Skills" description="檢視官方重組頁裡的 Skill 結構和遷移邊界。" href="/zh-Hant/docs/cursor/official/02-context-customization/22-skills" />
</Cards>
