這個單元解決什麼問題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 與 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 文件,必要時才載入
examples
scripts
SKILL.md 是入口,其他檔案是輔助。SKILL.md 內用相對路徑引用 reference.md 等檔案時,Claude 會在需要時讀進來(見第 6 節漸進式揭露)。scripts/ 內的腳本由 Claude 透過 Bash tool 叫用,不是被讀進 context。
3. SKILL.md frontmatter 完整參考
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]:
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 連結引用。
漸進式揭露的 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]。
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]。
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 已接近上限,需要隔離執行。
自我檢核動手做
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,分別驗證使用者和模型的叫用權限。常見誤區
自我檢核
通過本單元的標準
- 你能寫出一個 frontmatter 完整、
description觸發條件精準的SKILL.md嗎? - 你能判斷一個需求該走 Skill、Rules、Command 還是 Subagent 嗎?說出決策依據。
- 你能用漸進式揭露策略,把一個 400 行的程序拆成 30 行
SKILL.md+references/子目錄嗎? - 你知道 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;
.mdcfrontmatter 與 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;跨工具共通專案規則檔標準)
CLAUDE.md與自動記憶見 04-1 CLAUDE.md 與記憶檔。- 規則檔 path-scoped 機制見 04-2 rules。
- 主動觸發 command 設計見 04-3 Command。
- Subagent 與 Skill 配合見 04-5 Subagent。
- 上下文工程與 token 預算見 01-4 上下文工程。