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。

接下來去哪