Skills 是「需要時才載入」的模組化能力包：一個含 SKILL.md 的資料夾，封裝可重複使用的指令、流程、參考資料與可執行腳本。本指南以官方文件為權威骨幹整理。
不同於把所有內容塞進 system prompt，skill 的內容是按需載入：常駐 context 的只有 metadata（name + description，每個約 100 tokens），主體只在被觸發時才載入。
SKILL.md 的資料夾，外加選用的 scripts／templates／參考文件。CLAUDE.md 某段已變成「程序」而非「事實」；想跨 session 重用領域知識；需要可執行腳本綁定能力。/v1/skills 或 pre-built skill_id）。不跨平台同步。必需入口檔：YAML frontmatter + 主體指令。
metadata 常駐、主體觸發才載、資源用到才讀。
name/description/allowed-tools/context… 控制行為。
自動觸發 vs /name 手動；可關自動、限工具。
綁可執行腳本、!`cmd` 動態上下文、context:fork。
| 層級 | 內容 | 何時載入 | Token 成本 |
|---|---|---|---|
| L1 Metadata | name + description | 啟動時，常駐 system prompt | 每個 skill ~100 tokens |
| L2 SKILL.md 主體 | 主要指令、流程、quick-start | skill 被觸發時 | 建議 < 5k tokens / < 500 行 |
| L3 Bundled 資源 | reference.md、scripts/、examples/ | 被引用 / 用到時 | 讀取前不佔 context（無上限） |
system prompt 含所有 skills 的 name + description。
使用者需求相關 → Claude 執行 cat skill-dir/SKILL.md 載入主體。
SKILL.md 指到 forms.md → 只有需要時才 cat forms.md。
跑 python scripts/validate.py——只有輸出進 context，原始碼不進。
壓縮後行為：SKILL.md 被叫用後以單一訊息進入對話並留在 session（不會每回合重讀）。auto-compaction 後，每個 skill 只重新附加前 5,000 tokens、所有 skill 共享 25,000 tokens 預算，最近叫用者優先；若 skill 失效就用 /name 重新叫用。
| 欄位 | 用途 |
|---|---|
description | 什麼 + 何時用；自動發現的依據（強烈建議） |
name | 清單顯示名；預設目錄名（通常不決定 /command 名） |
when_to_use | 補充觸發語；與 description 合併（上限 1,536 字元） |
argument-hint | autocomplete 提示，如 [issue-number] |
arguments | 具名位置參數，供 $name 替換 |
disable-model-invocation | true → 只能你手動叫用；對 Claude 隱藏 description |
user-invocable | false → 從 / 選單隱藏；只有 Claude 能用 |
allowed-tools / disallowed-tools | skill 啟用時預先核准／封鎖的工具 |
model / effort | 本回合覆寫模型／effort（low…max） |
context / agent | fork → 隔離 subagent 執行；指定 agent 類型 |
paths | glob；只在處理符合路徑檔案時自動啟用 |
hooks / shell | skill 生命週期 hooks；! 命令的 shell（bash/powershell） |
| 範疇 | 路徑 | 適用 |
|---|---|---|
| 個人 | ~/.claude/skills/<name>/SKILL.md | 你所有專案 |
| 專案 | .claude/skills/<name>/SKILL.md | 本專案（隨 git 共享） |
| Plugin | <plugin>/skills/<name>/SKILL.md | 啟用該 plugin 處；用 plugin:skill 命名空間，不衝突 |
| 企業 | 由 managed settings 部署 | 全組織 |
Claude Code 監看 skill 目錄：新增/改/刪即時生效；新增「最上層 skills 目錄」需重啟 session（或用 /reload-skills 重新掃描）。
| Frontmatter | 你叫用 | Claude 叫用 | 對 Claude 可見 |
|---|---|---|---|
| （預設） | ✓ | ✓ | name + description |
disable-model-invocation: true | ✓ | ✗ | 隱藏 |
user-invocable: false | ✗ | ✓ | name + description |
有副作用一定關自動：deploy、commit、發訊息、刪資料等 → disable-model-invocation: true，只由你手動 /name 觸發。背景知識型（如遺留系統說明）→ user-invocable: false，讓 Claude 靜默套用。
也可用權限規則控制：Skill(commit)（精確）、Skill(review-pr *)（前綴）允許；單獨 Skill 拒絕全部。
| 變數 | 展開為 |
|---|---|
$ARGUMENTS / $ARGUMENTS[N] / $N | /skill 後的完整參數字串 / 第 N 個（0-based） |
$name | arguments frontmatter 宣告的具名參數 |
${CLAUDE_SESSION_ID} / ${CLAUDE_EFFORT} | 目前 session ID / effort 字串 |
${CLAUDE_SKILL_DIR} | 此 skill 目錄絕對路徑（引用隨附腳本必用） |
!`cmd`（Claude 看到前先執行）! 須在行首或空白後；輸出只替換一次（不再掃描）；可用 "disableSkillShellExecution": true 全域停用。
context: fork — 隔離 subagent 執行fork 警告：只對「有明確可執行指令」的 skill 有意義。只含準則（如 API 慣例）的 skill 丟給 subagent 會空手而回。allowed-tools 只是預先核准、不是 sandbox——其他工具仍可呼叫，要擋請用 deny 規則。
口訣：事實 → CLAUDE.md；一次性任務 → prompt；可重複的程序 + 上下文 → skill。
| 面向 | CLAUDE.md | Prompt | Skill |
|---|---|---|---|
| 載入 | 永遠在 context | 每回合 | 按需（觸發時） |
| Token 成本 | 持續 | 每回合 | ~100 metadata；主體用到才算 |
| 範疇 | 專案/全域事實 | 一次性指令 | 可重用領域能力 |
| 可分享 | per-project | 不持久 | Plugins、VCS、managed settings |
| 可執行碼 | ✗ | ✗ | ✓（隨附腳本） |
| 叫用 | 隱含 | 隱含 | 顯式 /name 或自動觸發 |
Claude Code 內建（prompt-based，/ 叫用） | 用途 |
|---|---|
/code-review | 審 bug、可讀性、慣例（--fix／--comment／雲端深審） |
/debug | 工具輔助的系統化除錯 |
/batch · /loop | 跨多檔/輸入批次；重複跑到條件達成 |
/claude-api | 最新 Claude API 參考 + 8 語言 SDK |
/run · /verify · /run-skill-generator | 啟動/驗證 app 確認變更（需 v2.1.145+） |
| 平台 | 安裝/分享 | 網路 · 套件 |
|---|---|---|
| Claude Code | 檔案系統（個人/專案/plugin） | 完整網路（同本機程式）；建議 local 安裝套件 |
| claude.ai | 上傳 .zip（Settings → Features，需開 code execution） | 依設定；可 runtime 裝 npm/PyPI |
| Claude API | /v1/skills 或 pre-built skill_id（workspace 共享，需 3 個 beta header） | 無網路；僅預裝套件 |
pre-built skill_id：pptx / xlsx / docx / pdf。官方範例庫：github.com/anthropics/skills（可 /plugin marketplace add anthropics/skills 安裝 document-skills / example-skills）。
processing-pdfs）；避免 helper/utils/含 anthropic/claude。${CLAUDE_SKILL_DIR} 引腳本。只用可信來源的 skill。Skill 同時提供「指令 + 可執行碼」，惡意 skill 可引導 Claude 呼叫任何可用工具。把 skill 當軟體套件審查。
| 風險 | 說明 |
|---|---|
| 資料外洩 | 非預期網路呼叫洩漏資料 |
| 工具濫用 | Bash/檔案工具被用於宣稱用途之外 |
| 外部依賴汙染 | 抓外部 URL 的 skill 可能被換內容毒化 |
| Prompt injection | 外部內容夾帶惡意指令 |
緩解：審查 skill 目錄所有檔案（SKILL.md、scripts、images）；專案 .claude/skills/ 在接受 workspace trust 前先看過；對有敏感資料的 production 格外小心。Claude API runtime 無網路；Claude Code 有完整網路（同本機程式）。
以 Claude Code 的 summarize-changes 為例（摘要未提交變更並標風險）。
mkdir -p ~/.claude/skills/summarize-changes
frontmatter 給 description（what+when），主體用 !`git diff HEAD` 注入即時 diff + 摘要指令。
在 git repo 開 claude，輸入 /summarize-changes，或自然語言「What did I change?」。
/skills 確認可見、/reload-skills 套用變更、/doctor 檢查 description 預算。
description + 最小主體/fix-issue 123 帶 $ARGUMENTSargument-hint、拆 reference.mddisable-model-invocation${CLAUDE_SKILL_DIR}）! 注入即時上下文、context:fork 隔離paths 限定自動啟用；最小化 allowed-tools以官方文件為權威骨幹整理。
/simplify、claude project purge 等）未在官方 Skills 文件佐證，故從略，請以官方 /help 與文件為準。/run、/verify、/run-skill-generator 需 Claude Code v2.1.145+。