Skip to main content
這個單元解決什麼問題Skill 把重複流程封裝成模型能依 description 自動叫用的程序。它不只是一個 SKILL.md:依需求嚴謹度與適用範圍,會有 references/ 放 few-shot 範本與規格、scripts/ 放可執行工具腳本。本單元從零製作一個實用 Skill,講解 description 寫法、漸進式揭露(progressive disclosure)省 token 的策略,並對照各家等價機制。

學習目標

  • 寫一個結構正確的 SKILL.md,含 description 與必要的 frontmatter 欄位。
  • 判斷何時建立 references/ 子目錄(few-shot 範本、規格文件)與 scripts/ 子目錄(可執行腳本)。
  • 用漸進式揭露策略控制 token 消耗,讓複雜 Skill 不在每次叫用時傾倒全部內容。
  • 判斷需求該做成 Skill、Rules 還是 Subagent,並說出判準。
  • 對照各家工具中等價的 Skill 封裝機制,並知道主要差異點。

1. Skill 是什麼

Skill 是一個放進 ~/.claude/skills/<name>/.claude/skills/<name>/ 的目錄,內含 SKILL.md(必要)與可選的 references/scripts/。Claude 在對話中description 語意自動叫用它,使用者也可以用 /<name> 主動觸發 [1]。 CLAUDE.md 的根本差別:
Skill 是「依需求帶進來」的單元CLAUDE.md 像放在桌上的桌面日曆,每天都在眼前。Skill 像抽屜裡的說明書,你要修水電才拿出來、修完放回去。把昂貴的內容從「每天付費」變成「用才付費」,就是 Skill 機制的本質價值。
Skill 與 Command 已合併為同一底層截至 2026-06,Claude Code 的 .claude/commands/<name>.md.claude/skills/<name>/SKILL.md 在底層是同一個機制,都會產生 /<name> 命令。差別在後者有目錄可放 references/scripts/、前者只有單一檔 [1]。本單元講後者(Skill),主動觸發的設計面見 04-3

2. 目錄結構

my-skill
SKILL.md · 必要:主指令與 frontmatter
reference.md · 選填:細部 API 文件,必要時才載入
SKILL.md 是入口,其他檔案是輔助。SKILL.md 內用相對路徑引用 reference.md 等檔案時,Claude 會在需要時讀進來(見第 6 節漸進式揭露)。scripts/ 內的腳本由 Claude 透過 Bash tool 叫用,不是被讀進 context。

3. SKILL.md frontmatter 完整參考

逐欄位(截至 2026-06,依官方 Skills 章節 [1]):
allowed-tools 不會「拒絕」未列出的工具allowed-tools 只是「免確認」清單,沒列的工具還是能用,受 session 權限設定管。要阻擋特定工具,請在 settings.json 的 deny 規則設 [1]。

4. 觸發控制:description、when_to_use 與 paths

description 寫法決定模型會不會叫用你的 Skill。爛的 description 會誤觸或漏觸。
描述寫法對照太泛,會誤觸:
太窄,會漏觸:
剛好:
觀察點:把觸發關鍵字(口語短語、英文同義)放進 description,模型比對時較容易命中。
paths 進一步把觸發條件收斂到「只在工作到某類檔案時」才叫用:
模型只在編輯 src/api/ 下的檔案時把這個 Skill 列為候選。

5. 嚴謹度分級:Level 1 到 Level 3

Level 1:單檔 Skill

只有 SKILL.md,程序 50 行以內,無外部依賴。適合個人重複工作流的快速封裝。

Level 2:含 few-shot 的 Skill

SKILL.md + references/ 內的格式範例或規格文件。適合需要嚴格輸出格式(學術摘要、標準報告、合約條款)的場景。
abstract-writer
SKILL.md
references
example-1.md · 完整摘要範例
example-2.md · 邊界情境
style-guide.md · 風格規範
SKILL.md 內引用:

Level 3:含可執行 scripts 的 Skill

SKILL.md + scripts/ 內的腳本(Python、Bash、Node.js 等)。適合需要真實計算、外部 API、或批次處理的任務,需同步考慮 allowed-tools 的安全設定。
codebase-visualizer
SKILL.md
scripts
visualize.py
SKILL.md 內用 ${CLAUDE_SKILL_DIR} 引用同目錄的腳本(確保路徑解析與 skill 安裝位置無關)[1]:
從 Level 1 開始,按需要升級不要跳級。Level 1 寫完跑得起來後,如果你發現 Claude 輸出格式漂移,再加 few-shot(升級到 Level 2);如果你發現需要跑計算或外部 API,再加 scripts(升級到 Level 3)。Level 3 寫得最重,但不一定適合每個工作流。

6. 漸進式揭露(progressive disclosure)

Skill 的核心 token 管理策略。SKILL.md 載入就進 context 並在 session 內持續留存 [1],但附屬檔案references/scripts/)是按需載入的。意思是:
  • 簡單的 Skill:SKILL.md 全部進 context。
  • 複雜的 Skill:把詳細規格、API 文件、few-shot 範例都放 references/SKILL.md 只描述「何時該讀哪個 references/ 檔」,用 Markdown 連結引用。
好處:每次叫用 Skill 的 token 成本只跟「當下用到的 references/ 內容」成正比,跟 Skill 整體大小無關。
漸進式揭露的 token 節省一個「產學術摘要」Skill,SKILL.md 30 行,內含 5 個 markdown 連結指向 references/ 下 5 份各 80 行的格式範本。沒做漸進式揭露:把 5 份範本全文塞進 SKILL.md,每次叫用 = 30 + 5 x 80 = 430 行。做漸進式揭露SKILL.md 30 行,5 個 markdown 連結,Claude 真的要看範例時才讀某一個 references/ 檔。平均每次叫用 = 30 + 80 = 110 行,省 75%。在 200k context window 下,110 與 430 看起來都小。但乘上叫用次數與團隊規模,這是每月數百美元的成本差距。

7. Skill 內容生命週期

Skill 觸發時,SKILL.md 渲染後的內容($ARGUMENTS 已替換、!`cmd` 已執行)會以單一訊息形式進入 session 對話歷史,在後續輪次中持續存在 [1]。 /compact 摘要對話以釋放 context 時,Claude Code 會重新掛載(reattach)最近叫用過的 Skill 內容,每個 Skill 保留前 5,000 token,多個 Skill 共用 25,000 token 預算,從最近叫用的開始填。意思是:同一 session 叫用太多 Skill,較舊的會被完全丟掉 [1]。
Skill 看似「失效」不一定是丟失如果 Skill 叫用後幾輪你覺得它「沒在影響行為」,通常內容還在 context,只是模型在那一輪選擇了其他工具。強化 description 與指令措辭,或對關鍵行為加 Hook 強制 [1]。

8. 動態 context 注入:!`command`

SKILL.md 內可用 !`<command>` 在送進 Claude 之前先執行 shell,把輸出嵌入 [1]:
規則:
  • 執行於當前 shell(macOS/Linux 預設 bash,Windows 可設 shell: powershell)。
  • 輸出以純文字插入,不會再被重新解析為 !` 預留位。
  • 內聯形式只認行首或緊接空白的 !,像 KEY=!`cmd`! 不會觸發。
  • 多行用 ```! fence 形式。
  • 組織可在 settings 設 "disableSkillShellExecution": true 全面關閉(bundled 與 managed skill 不受影響)[1]。
動態注入 = 你的 shell 在跑!`cmd` 是用你的本機 shell 執行,不是 sandbox。Skill 內容若由他人提供(共享 repo、plugin 市集),注入的指令就等於把 shell 控制權交給它。永遠自己 review 過 SKILL.md 才 trust

9. 工具對照

命名澄清與重要事實
  • Claude Code Skill 遵循 Agent Skills 開放標準agentskills.io)[1]。這標準是多家 AI 工具共用的,意味著你寫的 Skill 在合規的編輯器 / CLI 中應該能直接裝。
  • OpenAI Codex 的 Skill 機制:以 config.toml[skills] 區段設定,個人層 ~/.agents/skills/<name>/SKILL.md、專案層 <repo>/.agents/skills/<name>/SKILL.md(trusted 才載入,以 config.toml[[skills.config]] 啟用控制)。路徑是 .agents/skills/,非 .codex/skills/(依 developers.openai.com/codex/skills,截至 2026-06)。
  • GitHub Copilot 的「Skills」與「Copilot Extensions」是兩件事:前者是本機 CLI 的 SKILL.md 機制,後者是 GitHub Marketplace 上的第三方擴充。本表只列前者。
  • Cursor 沒有原生「Skill」機制,.cursor/rules/*.mdc 在功能上更接近 Claude 的 rules,.cursorrules 為單檔 rules 變體 [3]。

10. 與 Subagent 的配合

Skill 提供程序(步驟、判準、格式),Subagent 提供獨立 context(隔離執行環境)。兩者組合(見 04-5):
當設了 context: fork 時,Skill 內容變成 subagent 的 task prompt,subagent 在乾淨 context 裡執行,結果摘要回傳主對話 [1]。 何時用 context: fork
  • Skill 內要跑大量讀取、計算,不想污染主對話 context。
  • 任務可平行化,每個 task 各自獨立。
  • 主對話 context 已接近上限,需要隔離執行。
context: fork 需要 Skill 內含「任務」Skill 內容若只是「遵守這些 API 慣例」(規範式、沒有明確任務),context: fork 會讓 subagent 收到「慣例」但沒「要做什麼」,回傳空結果。context: fork 適合有明確步驟的程序型 Skill [1]。

自我檢核動手做

1

Level 1 起手

挑一個你每週重複 3 次以上的工作流,寫一份 30 行以內的 SKILL.md,含 description 與 2-3 個 markdown 步驟。放到 ~/.claude/skills/<name>/SKILL.md,啟動 session 測試自動觸發與 /<name> 手動觸發。
2

升級到 Level 2

把上面那份升級,加 references/example.md 放一份完整 few-shot 範例,SKILL.md 內用 markdown 連結引用。比較有 / 無範例時 Claude 輸出品質。
3

觀察 token 成本

在同一個工作階段裡叫用 Skill 多次,然後跑 /context 看 Skill 內容佔了多少 context。對照 SKILL.md 行數驗證「Skill 內容整個進 context」的設計事實。
4

測試觸發控制

寫兩個 Skill,一個用 disable-model-invocation: true、一個用 user-invocable: false,分別驗證使用者和模型的叫用權限。

常見誤區

反模式清單
  • description 寫太泛(「幫我做各種任務」):模型在無關情境誤觸,污染 context。縮到具體可辨識的觸發條件與關鍵字。
  • 把所有規格文件塞進 SKILL.md:每次叫用都傾倒全部 token。改用 references/ 搭配漸進式揭露,內容只在需要時讀進。
  • 跳過 Level 1 直接寫 Level 3:過度工程化一個其實 30 行就能解決的需求。先驗證流程本身值得封裝,再決定是否升級。
  • 不設 allowed-tools 就在 Level 3 跑 shell 腳本SKILL.md!`cmd`scripts/ 內的執行呼叫都應該用 allowed-tools 明確允許的範圍。沒設時,Claude 用的是當前 session 權限,可能觸發大量確認或被完全擋下。
  • Skill 內含敏感資訊並 commit 進公開 repo:API key、絕對路徑、內部 URL 都會被讀進 context 與上版控。需要動態注入的值應透過環境變數或動態 shell 取得,不寫死在 SKILL.md 內。
  • 沒考慮 description 截斷:每個 Skill 的 description + when_to_use 合計在 1,536 字元內才會完整進 skill 列表 [1]。超過會被切,切掉的部分對模型不可見。

自我檢核

通過本單元的標準
  1. 你能寫出一個 frontmatter 完整、description 觸發條件精準的 SKILL.md 嗎?
  2. 你能判斷一個需求該走 Skill、Rules、Command 還是 Subagent 嗎?說出決策依據。
  3. 你能用漸進式揭露策略,把一個 400 行的程序拆成 30 行 SKILL.md + references/ 子目錄嗎?
  4. 你知道 Skill 內容進 context 後的生命週期嗎(/compact 行為、25k token 預算)?

來源與延伸閱讀

事實主張依官方文件,快變動項標註截至 2026-05。
  • [1] Anthropic, “Extend Claude with skills,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/skills (截至 2026-06;含 frontmatter 完整參考、references/scripts/、動態注入、context: fork、生命週期)
  • [2] Anthropic, “Commands,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/commands (截至 2026-06;command 與 skill 合併機制)
  • [3] Cursor, “Rules,” cursor.com, 2026. [Online]. Available: https://cursor.com/docs/context/rules (截至 2026-06;.mdc frontmatter 與 globs 機制)
  • [4] Agent Skills Open Standard, “Agent Skills,” 2026. [Online]. Available: https://agentskills.io (截至 2026-06;Claude Code 與其他 AI 工具共用的 Skill 封裝開放標準)
  • [5] Agentic AI Foundation (Linux Foundation), “AGENTS.md,” 2026. [Online]. Available: https://agents.md/ (截至 2026-06;跨工具共通專案規則檔標準)