Skills 機制：載入、觸發與執行

90 秒總覽

Claude Code 的 skills 不是單一來源。`src/commands.ts` 會把 bundled skills、`.claude/skills`、plugin skills、legacy commands-as-skills 與其他 command 來源整合為同一個 registry，再由 `getSkillToolCommands()` 和 `getSlashCommandToolSkills()` 分別提供給模型側與使用者側流程。實際觸發有兩條主路：使用者 `/skill` 走 `processSlashCommand.tsx`，模型主動使用 skill 走 `SkillTool.ts`。兩條路最後都會把 skill 內容注入回合上下文，並套用 allowed tools、model、effort、permission 與 compaction 保留機制。

執行路徑（主骨架）

// src/commands.ts
export async function getCommands(cwd: string): Promise<Command[]> {
  const allCommands = await loadAllCommands(cwd)
  const dynamicSkills = getDynamicSkills()
  // availability + isEnabled 過濾
  return ...
}

export const getSkillToolCommands = memoize(async (cwd: string) => ...)
export const getSlashCommandToolSkills = memoize(async (cwd: string) => ...)

重點：skills 先進同一份 command registry，再由不同入口做二次過濾，而不是維護兩套獨立清單。

啟動/刷新：載入 skills 來源（bundled + skill dirs + plugin + legacy）
合併進 commands registry（含 dynamic/conditional skills）
每回合附件：注入 skill listing 與必要 discovery 信號

使用者路徑：
  /xxx -> processSlashCommand -> getMessagesForPromptSlashCommand
  -> 注入 SKILL 內容 + command permissions attachment -> 查詢主回合

模型路徑：
  SkillTool(skill,args) -> validate + permission
  -> inline 或 fork 執行
  -> 注入 skill 內容/結果並更新 context modifier

flowchart TD
  A[載入 skills 來源] --> B[getCommands 合併 registry]
  B --> C{觸發來源}
  C -->|使用者 /skill| D[processSlashCommand.tsx]
  C -->|模型 SkillTool| E[SkillTool.ts]
  D --> F[getMessagesForPromptSlashCommand]
  E --> G{inline 或 fork}
  F --> H[注入 skill 內容與權限]
  G --> H
  H --> I[query loop 執行]
  I --> J[compaction 保留與後續恢復]

觸發判斷與時機（回合引擎視角）

在回合引擎中，skills 的「使用時機」不是硬編碼 if/else，而是由三層訊號組合出來：可見性（listing）、相關性提示（discovery）、以及模型最終是否呼叫 `SkillTool`。這三層對應到不同模組，不能混成同一件事。

Turn 開始
  -> getAttachmentMessages: 注入 skill_listing（可用技能清單）
  -> query.ts: startSkillDiscoveryPrefetch（背景預抓技能相關線索）
  -> 模型先執行一般推理與工具呼叫
  -> query.ts: collectSkillDiscoveryPrefetch（把 discovery 線索注入）
  -> 模型判斷是否呼叫 SkillTool
       若呼叫: SkillTool.validate -> checkPermissions -> call(inline/fork)
       若不呼叫: 繼續一般工具路徑

sequenceDiagram
  participant U as User
  participant Q as query.ts
  participant A as attachments.ts
  participant M as Model
  participant S as SkillTool
  U->>Q: submit message
  Q->>A: getAttachmentMessages
  A-->>Q: skill_listing
  Q->>Q: startSkillDiscoveryPrefetch
  Q->>M: send context + tools
  M-->>Q: tool calls / reasoning
  Q->>Q: collectSkillDiscoveryPrefetch
  Q->>M: inject skill_discovery (if any)
  M->>S: call SkillTool? (optional)
  S-->>M: inline/fork result
  M-->>Q: final response

讀文件 vs 執行 Script：觸發階段對照

這裡要先拆開三件事：系統讀 `SKILL.md`、skill 內容被展開注入、模型後續呼叫工具去讀檔或執行命令。它們是不同階段，不要混在一起判斷。

場景案例（判讀模板）

關鍵決策（為什麼這樣設計）

替代方案與取捨

失敗路徑與防護

實作驗證（你改完要怎麼確認）

• 確認本頁敘述可對應到以下程式碼：`src/commands.ts`、`src/skills/loadSkillsDir.ts`、`src/utils/plugins/loadPluginCommands.ts`、`src/utils/processUserInput/processSlashCommand.tsx`、`src/tools/SkillTool/SkillTool.ts`、`src/utils/attachments.ts`、`src/query.ts`。
• 確認使用者路徑：`/skills` 相關敘述與 slash command 流程一致，未把 SkillTool 與 slash 流程混為一談。
• 確認模型路徑：有清楚描述 validate/permission/context(inline,fork) 的先後順序。
• 確認時機路徑：有明確區分 listing、discovery、SkillTool call 三層，且每層都有對應 src 位置。
• 確認讀/執行路徑：有清楚區分「讀 SKILL.md」「展開 skill」「Read/Grep 讀文件」「shell script 執行」。
• 確認案例段落：至少 4 個場景，且每個都有「是否執行 script」的明確判斷。
• 確認導覽可從首頁、群組頁與側欄進入本頁，且 active page 高亮正確。
• 確認本頁語言、術語與既有網站一致（台灣正體中文，避免外部推測性敘述）。