Claude Code Skills 實戰教學：從零打造你的 AI 自動化工作流

你每天用 Claude Code 對話、寫程式、改文件，但每次開新 session 都要重複說明同樣的規則和流程嗎？Skills 是 Claude Code 的「可重用指令集」，能把你反覆執行的工作流程固化成一鍵觸發的自動化系統。2026 年 3 月的 Claude Code 2.1.0 帶來了 Skills 2.0 重大升級，新增 Forked Context、Hot Reload、Skill Creator 等功能。這篇文章用我們自己運行中的真實案例，帶你從理解 Skills 基礎到掌握 2.0 新功能。

TL;DR

• Skills 是用 Markdown 寫的可重用指令集，讓 Claude Code 從「聊天助手」變成「流程自動化引擎」
• 搞懂 CLAUDE.md（永遠載入的規則）vs Skills（按需載入的工作流）vs Hooks（自動觸發的腳本）三者的分工，是設計好工作流的前提
• 2.0 新增：Forked Context（隔離執行）、Hot Reload（存檔即生效）、Hooks in Frontmatter（skill 內建鉤子）、Skill Creator（互動建立 + 品質測試）
• 引數語法：$ARGUMENTS[0] 或簡寫 $0，支援多引數傳遞
• 實戰案例：用多個 Skills 串起從選題到發布的完整內容產線
• 安全注意：Snyk ToxicSkills 研究發現約 13% 公開 Skills 含嚴重安全問題，安裝第三方 Skills 前務必審查原始碼

為什麼你需要 Skills？從「重複貼指令」到「一鍵執行流程」

如果你有以下經驗，你需要 Skills：

• 每次開新 session 都要貼上同一段「請按照以下格式...」的指令
• 同一個工作流程（寫文章、做 code review、整理報告）每次都要從頭說明步驟
• 團隊中每個人對 Claude 下的指令品質參差不齊，產出不穩定

Skills 解決的核心問題很簡單：把你反覆執行的指令集封裝成可重用模組。寫好一次，之後用 /skill-name 一鍵觸發，不用每次從頭教 Claude 怎麼做。

你可以把 Skills 想成你為 Claude 寫的 SOP 手冊。新員工第一天上班你不會口頭講一遍流程就期望他記住，你會給他一份文件。Skills 就是那份文件。

適合 Skills 化的工作類型：

• 有固定步驟的流程：code review checklist、文章撰寫流程、PR 模板
• 需要特定格式輸出的任務：commit message 格式、報告模板、changelog 生成
• 多階段的工作流：研究 → 大綱 → 撰寫 → 審查，每個階段有不同的規則和產出

Skills vs CLAUDE.md vs Hooks：三層機制的分工決策框架

Claude Code 有三種自訂機制，搞混它們是最常見的錯誤。根據官方文件的設計，三者的分工如下：

你要定義的是...	放在哪裡	載入方式	適合場景
所有對話都適用的規則	CLAUDE.md	每次 session 自動載入	品牌語調、禁止事項、專案慣例
特定任務的完整流程	Skills（SKILL.md）	Claude 判斷相關時載入，或用戶手動觸發	寫文章、做 code review、研究報告
每次都必須自動執行的檢查	Hooks（.claude/hooks/）	基於事件自動執行	lint、format、commit 訊息檢查

CLAUDE.md 是你的「永遠生效的公司規章」。它在每次 session 開始時自動載入，始終佔用 context。適合放精簡、全局適用的規則，例如「所有回覆使用繁體中文」、「禁止使用某些 API pattern」。

Skills 是你的「工作手冊」。啟動時只有 description（一句話摘要）進入 context，Claude 判斷當前任務與某個 Skill 相關時，才會載入完整內容。你也可以用 /skill-name 手動觸發。這樣設計的好處是不浪費 token。

Hooks 是你的「自動化門禁系統」。它基於事件（如 tool call、notification）加上 matcher 條件自動執行 shell 命令或 HTTP 請求，不需要 Claude 判斷。例如：每次 commit 前自動跑 linter。

常見錯誤：

• 把所有東西塞進 CLAUDE.md：你的 code review 流程有 200 行，但 90% 的對話不需要它。放在 CLAUDE.md 就是每次對話都浪費這些 token。應該做成 Skill。
• 把全局規則寫成 Skill：「所有程式碼使用 TypeScript」這種規則如果放在 Skill 裡，Claude 不一定每次都會載入。應該放在 CLAUDE.md。

判斷原則：問自己「這條規則是每次對話都需要的嗎？」如果是，放 CLAUDE.md。如果只在特定任務需要，做成 Skill。如果需要無條件自動執行，用 Hooks。

SKILL.md 怎麼寫？結構拆解與設計原則

根據官方文件，一個 SKILL.md 由兩部分組成：

---
description: "執行 code review，檢查程式碼品質、安全性和效能"
---

# Code Review Skill

## 步驟 1：讀取變更
讀取 git diff，理解本次變更的範圍和目的。

## 步驟 2：品質檢查
逐一檢查以下項目...

YAML Frontmatter（--- 之間的部分）告訴 Claude 這個 Skill 是做什麼的。所有欄位都是 optional，但 description 強烈建議填寫，因為它是 Claude 判斷是否載入這個 Skill 的依據。

Markdown Body 是 Claude 載入 Skill 後會遵循的完整指令。

重要的進階 Frontmatter 欄位

欄位	用途	範例
description	Claude 判斷是否載入的依據（建議填寫）	"研究主題並產出 Research Brief"
user-invocable	是否允許用戶用 /command 手動觸發	true
allowed-tools	限制 Skill 可使用的工具	["Read", "Grep", "WebSearch"]
model	指定執行模型	"claude-sonnet-4-6"
context	🆕 設定執行環境（fork = 隔離子環境）	fork
agent	🆕 搭配 context: fork 指定 subagent 類型	"research"
hooks	🆕 在 skill 內定義 scoped hooks	見下方範例
skills	🆕 注入其他 skills 到 subagent context	["fact-check"]

Progressive Disclosure 設計模式

官方建議 SKILL.md 控制在 500 行以內。超過的話，把詳細參考資料拆到獨立檔案：

.claude/skills/
  my-skill/
    SKILL.md          ← 主要指令（500 行內）
    templates/         ← 模板檔案
    reference.md       ← 詳細參考資料

SKILL.md 裡用 Read 指令引導 Claude 在需要時才讀取獨立檔案，而非一次全部載入。這就是 Progressive Disclosure：先給核心指令，需要時再展開細節。

真實案例：obra/superpowers 的 brainstorming Skill

來看一個在社群廣泛使用的真實 Skill。obra/superpowers 是由 Jesse Vincent 開發的開源 Skills 框架，提供一套結構化的 AI 開發方法論。其中 brainstorming Skill 的設計值得學習：

---
name: brainstorming
description: "You MUST use this before any creative work - creating features,
  building components, adding functionality, or modifying behavior. Explores
  user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

## Overview
Help turn ideas into fully formed designs and specs through natural
collaborative dialogue. Start by understanding the current project context,
then ask questions one at a time to refine the idea.

## Checklist
1. **Explore project context** — check files, docs, recent commits
2. **Ask clarifying questions** — one at a time, understand purpose/constraints
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
4. **Present design** — get user approval after each section
5. **Write design doc** — save to docs/plans/
6. **Transition to implementation** — invoke writing-plans skill

這個 Skill 展示了幾個好的設計原則：

• description 明確且強勢：用 "You MUST use this before any creative work" 確保 Claude 在相關情境一定會載入
• 有 Hard Gate：明確禁止在設計未核准前寫任何程式碼
• Checklist 驅動：逐步執行，每步有明確產出
• 銜接下一個 Skill：完成後自動導向 writing-plans Skill，形成 pipeline

你可以直接 clone 這個 repo 到 ~/.claude/skills/ 使用，也可以參考它的結構設計自己的 Skill。

Skills 2.0：六大新功能完整解析

Claude Code 2.1.0 對 Skills 做了一次大幅度的架構升級。如果你已經在用 Skills，這些新功能會讓你的工作流更強大；如果你正要開始，現在是最好的時機。

Forked Context：隔離執行，不污染主對話

這是 2.0 最重要的新功能。在 frontmatter 加上 context: fork，整個 skill 會在獨立的子環境中執行。子環境看不到主對話的歷史記錄，執行完畢後只把最終結果回傳主對話，中間過程完全隔離。

---
description: "執行深度市場調研"
context: fork
agent: research
allowed-tools: ["Read", "Grep", "WebSearch"]
---

什麼時候該用？ 需要大量搜尋、分析、或複雜推理的 skill。根據實測，調研類 skill 加上 context: fork 後，主對話的 context 消耗從數千 token 降到只有最終摘要的幾百 token。

注意事項：fork 會產生少量額外延遲，且子環境無法存取主對話記錄。設計 skill 時要確保所有必要資訊都寫在 skill 本身或透過檔案傳遞，不能依賴對話上下文。

Hot Reload：存檔即生效，不用重啟

過去修改 SKILL.md 後需要重啟 Claude Code session 才能看到變更。2.0 引入 Hot Reload，存檔後新版本立即生效。

這聽起來是小改動，但對 skill 開發的體驗影響很大。以前每次調整 skill 都要中斷對話、重新啟動、重新載入 context，整個迭代循環很慢。現在改完存檔就能直接測試，大幅縮短開發迭代時間。

注意：這也意味著存檔即上線。如果你正在編輯一個 skill 寫到一半，Claude 已經可以看到半成品了。建議在獨立分支或臨時目錄中開發，測完再搬到正式位置。

Hooks in Frontmatter：Skill 內建事件鉤子

以前 Hooks 只能在 settings 檔案中全局設定。2.0 允許直接在 skill 的 frontmatter 裡定義 scoped hooks，只在該 skill 執行期間生效，skill 結束後自動清除。

---
description: "安全部署流程"
hooks:
  PreToolUse:
    - matcher: "Bash"
      command: "node validate-command.js"
  PostToolUse:
    - matcher: "Write"
      command: "npx eslint --fix $FILE"
---

上面這個範例做了兩件事：每次 skill 要執行 Bash 命令前，先跑驗證腳本；每次寫入檔案後，自動跑 ESLint 修正。這些 hooks 只在這個 skill 的生命週期內有效，不會影響其他對話。

實用場景：部署 skill 加命令白名單驗證、code review skill 寫完修正後自動跑 linter、資料處理 skill 完成後自動驗證輸出格式。

Skill Creator：互動式建立與品質測試

如果你覺得手寫 SKILL.md 有門檻，Skill Creator 是官方提供的互動式建立工具，可在 Claude.ai、Cowork 或 Claude Code 中使用。

Skill Creator 最有價值的功能不是「幫你生成 SKILL.md」，而是 evals（品質測試）。你可以定義測試 prompt 和預期結果，讓它自動跑 benchmark 驗證 skill 是否可靠。還支援 A/B comparator，同時跑兩個版本的 skill 做盲測比較。

實測心得：Skill Creator 特別適合最佳化 description 欄位。它會分析你的 description 被觸發的成功率，找出 false positive（不該觸發卻觸發了）和 false negative（該觸發卻沒觸發），然後建議修改。根據社群測試，auto-activation 的基礎成功率只有約 20%，透過最佳化 description 和搭配 hooks 可以提升到 84%。

Custom Agent Support：指定 Subagent 執行

Skills 2.0 可以透過 agent 欄位搭配 context: fork，指定使用內建 agent（如 Explore、Plan）或自訂 agent（來自 .claude/agents/）來執行 skill。還能用 skills 欄位注入其他 skills 到 subagent 的 context 中。

---
description: "用研究 agent 做市場調研"
context: fork
agent: research
skills: ["fact-check", "source-validation"]
---

這讓你可以建立多層 agent 協作架構：主 agent 調度任務，research agent 做調研，review agent 做審查，每個 agent 帶著自己需要的 skills 獨立工作。

引數語法

Skills 支援引數傳遞，語法為 $ARGUMENTS[0]（或簡寫 $0、$1、$2...）：

將 $0 元件從 $1 遷移到 $2。

執行 /migrate-component SearchBar React Vue 時，$0 = SearchBar、$1 = React、$2 = Vue。

安全風險與防禦：從 ToxicSkills 研究學到的事

Skills 生態系在 2026 年初爆發性成長，光是 skills.sh 一個平台就有超過 83,000 個公開 Skills。但生態系快速膨脹也帶來了安全問題。

Snyk 於 2026 年 2 月發表的 ToxicSkills 報告是首份針對 Agent Skills 生態系的全面安全審計，結果令人警惕：在分析的 3,984 個公開 skills 中，13.4%（534 個）含嚴重安全問題，36.82%（1,467 個）至少含一個安全缺陷。攻擊手法包括惡意軟體散佈、憑證竊取、prompt injection。

五條具體防護措施：

1. 安裝前先讀原始碼。SKILL.md 就是 Markdown 文件，花 2 分鐘瀏覽一遍不難。重點看有沒有可疑的 WebFetch 到不明 URL、Bash 執行外部腳本、或要求關閉安全限制的指令。
2. 用 allowed-tools 限制權限。特別是涉及 Bash、Write 等高權限操作的 skill，明確列出允許的工具，不要給予無限制的存取。
3. 善用 Hooks in Frontmatter 做命令驗證。在 PreToolUse 加入驗證腳本，攔截可疑的 Bash 命令。
4. 優先使用官方或知名維護者的 Skills。anthropics/skills 是官方維護的 repo，品質和安全性有基本保障。
5. 注意 context: fork + 無限制 tools 的組合。fork 環境中的 skill 如果沒有 allowed-tools 限制，等於給了一個不受監督的 agent 完整權限。

實戰案例：用 Skills 串起多階段內容產線

講理論不如看實際運行的系統。我們用 Claude Code Skills 架了一條完整的內容產線，從選題到發布全程由 AI agent 協作完成。以下分享幾個關鍵的設計原則。

架構概覽

全局規則放 CLAUDE.md：品牌語調、格式規範、絕對禁止事項。這些是每次對話都需要遵守的，所以放在永遠載入的 CLAUDE.md。

每個階段一個 Skill：內容產線拆成多個獨立階段，例如選題篩選、市場調研、大綱設計、草稿撰寫、品質審查、多語系翻譯等。每個階段對應一個 Skill，用 /command 觸發。

這樣拆分的好處是每個 Skill 職責單一、容易維護，而且可以獨立迭代某個階段而不影響其他流程。

三個關鍵設計原則

1. 每個 Skill 都有 HITL（Human-in-the-loop）暫停點

每個 Skill 執行完畢後會強制暫停，等用戶確認才進入下一階段。這不是技術限制，而是刻意設計。根據實際使用經驗，AI 如果一路自動跑完整條 pipeline，最終產出的品質明顯低於人類在每個階段介入調整的結果。

實作方式很簡單，在 Skill 的指令中加入類似的規則：

## HITL 規則
完成後必須停止，顯示摘要並等待用戶回應：
- 輸入 `yes` → 進入下一階段
- 輸入 `revise: [說明]` → 調整後重新確認
- 輸入 `no` → 暫停

2. 用 Subagent 隔離搜尋雜訊

需要搜尋外部資訊的 Skill（例如調研、事實查核），不會在主對話中直接搜尋。而是啟動一個獨立的 subagent 去做 WebSearch，只把結構化摘要傳回主對話。這樣主 context 不會被搜尋結果的雜訊污染。

3. Skill 之間透過檔案傳遞資料

每個工作項目有一個對應的 Markdown 檔案，每個 Skill 執行完畢後把產出 append 到這個檔案。下一個 Skill 讀取同一個檔案就能接續上一階段的產出。這比依賴 context 傳遞更可靠，因為 context 會隨 session 結束而消失，但檔案持久保存。

Context 預算管理

當 Skills 數量增加，所有 description 加起來不能超出 context 預算。根據官方文件，Skills 的 context 預算是 context window 的 2%，fallback 上限 16,000 字元。實務上的做法是：

• 每個 Skill 的 description 控制在 1-2 句話（約 50-100 字元）
• 用 /context 定期檢查是否有 Skill 被排除
• 不常用的 Skill 考慮移除或合併

升級到 2.0 後的改進

我們的產線在 Skills 2.0 後做了兩個關鍵升級：

用 context: fork 隔離搜尋雜訊。原本我們在 skill 內手動啟動 subagent 做 WebSearch 隔離，現在只需要在 frontmatter 加一行 context: fork，整個 skill 就自動在隔離環境執行。程式碼更簡潔，效果相同。

用 Hooks in Frontmatter 取代全局 hooks。原本我們的事實查核 hook 是全局設定，每次對話都會載入。現在把它移到對應的 skill frontmatter 裡，只在需要事實查核的 skill 執行時才生效，其他對話完全不受影響。

效果

這套系統讓我們從「每篇文章手動指導 AI 花數小時」變成「走 pipeline 大幅縮短產出時間，同時維持可發布品質」。更重要的是，品質穩定了。不管是誰啟動 pipeline，產出都會經過相同的品質關卡。

風險揭露與注意事項

Skills 不是銀彈，有幾個你必須知道的限制：

Skills 載入不是確定性的。 Claude 根據當前任務的相關性判斷是否載入某個 Skill。如果你的 description 寫得太模糊，或者對話內容跟 Skill 的描述不夠匹配，Claude 可能跳過它。應對方式：寫清楚且具體的 description，並設定 user-invocable: true 讓你能用 /command 手動觸發。

Context 預算有上限。 Skills 過多時，部分 Skill 會被排除在 context 之外。你可以用 /context 命令檢查哪些被排除了。如果需要調整預算上限，可以設定環境變數 SLASH_COMMAND_TOOL_CHAR_BUDGET。

維護成本是真實的。 Skills 不是寫完就不用管了。隨著專案演進、工具更新、流程調整，Skills 會過時。我們的做法是每個月做一次 Skills review，檢查哪些已經不符合現狀。

安全性需要注意。 Skills 可以透過 allowed-tools 欄位限制 Claude 在執行該 Skill 時能使用哪些工具。如果你的 Skill 涉及敏感操作（如部署、刪除檔案），建議明確限制可用工具範圍。

Auto-activation 的可靠度比你想像的低。 根據社群實測，Skills 的自動觸發基礎成功率只有約 20%。也就是說，你期望 Claude 在特定場景自動載入某個 skill，但五次裡只有一次會成功。應對方式：用 user-invocable: true 確保能手動 /command 觸發；搭配 Hooks 強制觸發可將成功率提升到約 84%；使用 Skill Creator 最佳化 description 的觸發精準度。

Forked Context 會加速消耗用量配額。 每個 fork 是獨立的 agent session，會額外消耗 API tokens。如果你的 skill 頻繁 fork（例如每次對話都觸發），注意 Anthropic 的用量上限和 5 小時重置窗口。

不需要為每件事都建 Skill。 如果一個任務你只做一次，直接在對話中說明就好。Skills 的投資回報來自重複使用。一個粗略的判斷標準：如果你預期同樣的流程會執行超過 3 次，就值得做成 Skill。

結論

Skills 2.0 讓 Claude Code 從「可重用指令集」進化到「可程式化的 agent 系統」。Forked Context 讓 skill 能在隔離環境獨立工作，Hot Reload 讓迭代速度大幅提升，Hooks in Frontmatter 讓每個 skill 自帶安全護欄，Skill Creator 讓非工程師也能建立和測試 skill。

如果你是新手，建議從 Skill Creator 開始，用互動對話建出你的第一個 skill，再用 evals 驗證它是否可靠。

如果你已經有 skills，先做兩件事：評估哪些 skill 適合加上 context: fork 隔離執行；檢查是否有第三方 skills 需要安全審查。

想更深入了解 Skills 生態系中值得安裝的現成方案，可以參考我們的 Skills 精選推薦。