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

你每天用 Claude Code 對話、寫程式、改文件，但每次開新 session 都要重複說明同樣的規則和流程嗎？Skills 是 Claude Code 的「可重用指令集」，能把你反覆執行的工作流程固化成一鍵觸發的自動化系統。這篇文章用我們自己運行中的真實案例，帶你從理解 Skills 到設計一套完整的工作流。

TL;DR

• Skills 是用 Markdown 寫的可重用指令集，讓 Claude Code 從「聊天助手」變成「流程自動化引擎」
• 搞懂 CLAUDE.md（永遠載入的規則）vs Skills（按需載入的工作流）vs Hooks（自動觸發的腳本）三者的分工，是設計好工作流的前提
• 一個 SKILL.md 只需要 frontmatter（description）加上 markdown 指令，500 行以內最佳
• 實戰案例：Shareuhack 用 13 個 Skills 串起從選題到發布的完整內容產線
• 注意 context 預算限制（context window 的 2%，也就是模型記憶容量上限的 2%），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"
agent	搭配 context: fork 指定 subagent 類型	"research"

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 是一套開源的 Claude Code Skills 集合，其中 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。

實戰案例：Shareuhack 的 13 個 Skills 內容產線

講理論不如看實際運行的系統。Shareuhack（就是你正在看的這個網站）用 Claude Code Skills 架了一條完整的內容產線，從選題到發布全程由 AI agent 協作完成。

架構概覽

全局規則放 CLAUDE.md：品牌語調（實戰權威、務實對話）、frontmatter 格式規範、絕對禁止事項（不虛構、不用 GitHub alerts）。這些是每次對話都需要遵守的，所以放在永遠載入的 CLAUDE.md。

每個階段一個 Skill：

/ideate → /research → /setup-notebook → /architect → /write → /content-review → /translate

每個 Skill 負責一個階段：/ideate 做快速篩選（3 分鐘內決定值不值得做），/research 啟動 subagent 做深度市場調研，/architect 設計文章大綱，/write 按大綱產出草稿，/content-review 用 40 分制做雙視角審查，/translate 處理多語系翻譯。

三個關鍵設計決策

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

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

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

2. 用 Subagent 隔離 WebSearch 雜訊

/research 和 /write 這類需要搜尋外部資訊的 Skill，不會在主對話中直接搜尋。而是啟動一個獨立的 subagent 去做 WebSearch，只把結構化摘要傳回主對話。這樣主 context 不會被搜尋結果的雜訊污染。

3. Skill 之間透過 pipeline file 傳遞資料

每篇文章有一個 content/pipeline/[slug].md 檔案，每個 Skill 執行完畢後把產出 append 到這個檔案。下一個 Skill 讀取同一個檔案就能接續上一階段的產出。這比依賴 context 傳遞更可靠，因為 context 會隨 session 結束而消失，但 pipeline file 持久保存。

Context 預算管理

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

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

效果

這套系統讓我們從「每篇文章手動指導 AI 花 3 小時」變成「走 pipeline 約 1 小時產出可發布品質的草稿」。更重要的是，品質穩定了。不管是誰啟動 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 涉及敏感操作（如部署、刪除檔案），建議明確限制可用工具範圍。

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

結論

Skills 把 Claude Code 從「需要每次手動指導的對話工具」變成「可以一鍵啟動的流程引擎」。核心概念很簡單：用 Markdown 寫出你的工作流程，讓 Claude 按照流程執行。

建議你的第一步：找出你最常重複的一個工作流程（code review、寫週報、整理會議紀錄），花 10 分鐘寫一個 SKILL.md。不需要一步到位，先從最簡單的版本開始，用了幾次之後再逐步完善。

如果你想建立更複雜的自動化系統，可以搭配 Hooks 做事件驅動的自動檢查，或者用 Subagent 讓 Skills 之間協作。這些進階主題就留給你自己探索了。