Claude Code Skills 與 Skill Creator：打造你的專屬 AI 工具包

用 Claude Code 一段時間之後，漸漸發現有些任務每次都要重新跟 Claude 解釋一遍背景：「我們的 commit 格式是這樣」、「記得用這個框架的慣例」、「這個專案有這些規則」。

Skills 就是為了解決這個問題而生的，讓你把這些重複的知識和流程打包起來，之後直接叫出來用就好。

---

什麼是 Skills？

Skills 是一種「可攜式的指令包」，本質上是一個資料夾，裡面放了 Claude 需要知道的知識、腳本和資源。 當你啟動一個 Skill，Claude 就會自動載入對應的指令，不需要你每次重新說明。

官方的 anthropics/skills 倉庫提供了幾個現成的範例：

• pdf / docx / xlsx / pptx：讀取和分析各種文件格式
• webapp-testing：用 Playwright 測試本地網頁應用程式
• algorithmic-art：用 p5.js 生成演算法藝術
• brand-guidelines：套用品牌設計規範
• mcp-builder：快速建立 MCP 工具

這些只是範本，更有趣的是你可以自己做一個符合自己需求的 Skill。

---

Skills 的結構

每個 Skill 是一個資料夾，裡面至少要有一個 SKILL.md：

my-skill/
├── SKILL.md          # 必要，Skill 的核心定義
├── scripts/          # 可選，Python / Bash / JS 腳本（確定性任務）
├── references/       # 可選，補充文件，供 Claude 按需參考
└── assets/           # 可選，輸出用的靜態資源（模板、字體、圖片等）

scripts/、references/、assets/ 三個目錄的定位不一樣，值得區分清楚：

• scripts/ 放的是 Claude 會去執行的程式碼，像是確定性的格式轉換、資料處理
• references/ 放的是文件，Claude 在需要時會讀進 context 參考
• assets/ 放的是輸出用的檔案，像是 PowerPoint 模板、字體、Logo，不是讓 Claude 讀的，而是讓 Claude 拿來用的

---

SKILL.md 的格式

SKILL.md 用 YAML frontmatter 加上 Markdown 內文：

---
name: my-skill
description: This skill should be used when the user asks to "do X", "handle Y", or mentions Z-related topic. Describe what this skill does and when to trigger it.
---

# 詳細的操作指令

...

Frontmatter 有幾個欄位：

欄位	必填	說明
name	✓	小寫字母、數字、連字號，最長 64 字，需與資料夾同名
description	✓	說明 Skill 做什麼、何時觸發，最長 1024 字
license	—	授權聲明
compatibility	—	環境需求（套件、網路等）
allowed-tools	—	預先核准的工具清單（實驗性）

有兩個寫法慣例值得注意。Description 要用第三人稱格式，也就是「This skill should be used when the user asks to...」，不是「Use this skill when...」。

至於 SKILL.md 的內文，則建議用祈使句，動詞開頭的直接指令，而不是「You should do...」這樣的第二人稱。

---

三層載入機制

Skills 設計了一個漸進式載入機制，避免每次都把所有資訊塞進 context：

第一層：隨時在場（約 100 words） 只有 name 和 description 會一直在 context 裡。Claude 用這個判斷哪個 Skill 需要啟動。

第二層：啟動時載入 當 Claude 判斷你的需求符合這個 Skill，才會把 SKILL.md 的內文讀進來。 建議控制在 500 行以內，大約 1,500 到 2,000 words 是理想範圍。

第三層：按需載入scripts/、references/、assets/ 只在真的需要時才載入。 大量的參考文件或資料放這裡，不會一開始就佔用 context。

這個機制讓你可以安裝很多個 Skill，但 token 消耗依然受控。

---

一個真實的 Skill 範例

xlsx Skill 的 description 是個很好的範本，看它怎麼把觸發情境列得非常具體：

---
name: xlsx
description: "Use this skill any time a spreadsheet file is the primary input or output.
  This means any task where the user wants to: open, read, edit, or fix an existing
  .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting,
  charting, cleaning messy data); create a new spreadsheet from scratch or from other
  data sources; or convert between tabular file formats. Trigger especially when the
  user references a spreadsheet file by name or path — even casually (like \"the xlsx
  in my downloads\") — and wants something done to it or produced from it. Do NOT trigger
  when the primary deliverable is a Word document, HTML report, standalone Python script,
  database pipeline, or Google Sheets API integration, even if tabular data is involved."
license: Proprietary. LICENSE.txt has complete terms
---

注意幾點：觸發條件列得很細，包含使用者可能說的各種方式；更重要的是，它還明確說了什麼情況下不要觸發，避免搶到不屬於自己的任務。

SKILL.md 的內文也同樣具體，以 xlsx Skill 為例，裡面直接給了操作模式、錯誤處理流程，甚至連 Excel 公式的顏色編碼規範都定義好了，Claude 執行任務時完全不需要自己摸索。

---

安裝現有的 Skills

官方 Skills 可以透過 plugin 市集安裝：

/plugin marketplace add anthropics/skills

裝好之後，直接自然地跟 Claude 說就可以觸發，不用記指令：

幫我分析這份 contract.pdf 裡的付款條款

把 sales_report.xlsx 的季度資料加上一欄 profit margin

Claude 會自動判斷要用哪個 Skill 來處理。

---

用 Skill Creator 打造自己的 Skill

官方提供了 Skill Creator plugin，這是專門用來開發和測試 Skill 的工具包。它本身也是一個 Skill，安裝後只要告訴 Claude 你想建立或改善一個 Skill，它就會自動觸發。

整個開發流程是一個迭代迴圈：定義需求、撰寫草稿、跑測試、看結果、修改、再跑。

具體來說：

首先，Skill Creator 會問你幾個問題：這個 Skill 要做什麼、什麼情況下應該觸發、輸出格式是什麼、有沒有邊界情況要注意。問完之後，它會幫你產生 SKILL.md 草稿，並建立 2–3 個測試案例存成 evals/evals.json：

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "使用者的實際需求",
      "expected_output": "期望的輸出描述",
      "files": []
    }
  ]
}

測試怎麼跑

接著 Skill Creator 會對每個測試案例同時跑兩個版本：一個「有 Skill」，一個「沒有 Skill」（改善現有 Skill 時則是跑舊版本作為 baseline）。 兩個版本平行執行，跑完之後透過 eval viewer 讓你瀏覽輸出結果，留下反饋。

在等待執行的過程中，Skill Creator 不會閒著，它會同時草擬定量評估的 assertions，也就是針對每個測試案例寫下可客觀判斷的期望，例如「輸出包含欄位 X」、「使用了腳本 Y」。 等結果出來，就會有 Grader 子代理自動評估每個 assertion 是否通過。

三個幕後子代理

Skill Creator 內建三個專屬子代理，各司其職：

Grader（評分者）負責把 assertion 對照執行紀錄和輸出檔案逐條評判，通過或不通過、附上具體證據。它有個有趣的工作：除了評估你預先定義的 assertions，它還會主動從輸出中提取隱含的宣稱（例如「此 Skill 產生了 12 個欄位」），然後一一查核，補抓你沒寫到的盲點。更重要的是，它也會批判 evals 本身，如果某個 assertion 太容易通過（例如只檢查檔案存在而不檢查內容），它會指出來。

Comparator（比較者）是盲測。它收到兩份輸出，但不知道哪份是哪個 Skill 產生的，純粹從「內容正確性、完整性、準確性」和「結構組織、格式、易用性」六個維度各給 1–5 分，加總得出 1–10 的總分，選出贏家。 去掉身份資訊是為了避免偏見。

Analyzer（分析者）是 Comparator 之後的後處理。它「解盲」，知道了哪份輸出是哪個 Skill 的，然後去讀兩個 Skill 的 SKILL.md 和執行紀錄，找出「贏家為什麼贏、輸家哪裡輸了」，最後給出有優先級（high / medium / low）的改善建議，分類包括指令措辭、腳本工具、範例覆蓋、錯誤處理等。

Description 優化

Skill 做得差不多之後，Skill Creator 還提供一個獨立的 description 優化流程，專門解決 undertrigger（觸發率不足）的問題。

它會先產生 20 個觸發評估查詢，其中 8–10 個「應該觸發」，8–10 個「不應該觸發」。這些查詢要夠具體，不能是「格式化這份資料」這種空泛描述，而是要像真實使用者會說的：帶有檔案路徑、公司名稱、個人背景的完整情境句。

你看過這些查詢、確認沒問題之後，優化腳本會跑起來：把查詢集 60% 用於訓練、40% 留作測試，每個查詢跑三次取觸發率均值，然後讓 Claude 開啟延伸思考（extended thinking）提出改進的 description，再重新評估，最多迭代五輪。最後用測試集的分數（而非訓練集）選出最佳版本，避免過擬合。

這個流程跑完，你會得到一個更新的 description，Skill Creator 會把前後版本和分數一起展示給你確認。

觸發機制的一個微妙點

有一件事值得知道：Claude 只會在「自己處理不來」的任務上去查 Skill。太簡單的一步請求，例如「讀一下這個 PDF」，即使 description 完全吻合，也可能不觸發 Skill，因為 Claude 覺得自己直接處理就好了。 複雜、多步驟、或需要專業知識的任務才會可靠地觸發。所以測試案例要設計得夠有深度，才能真正測試出 description 的觸發品質。

---

寫好 Description 是關鍵

測試幾個 Skill 下來，發現 description 寫得好不好，直接決定了 Skill 能不能在對的時機自動觸發。

Skill Creator 的文件裡提到一個觀察：Skill 的問題通常不是「亂觸發」，而是「沒有觸發」（undertrigger）。解法是讓 description 更「主動」，把所有相關的使用情境都明確列出來，即使使用者沒有用精確的關鍵字。

來看個例子，假設你在做一個 dashboard 生成 Skill：

❌ 太模糊，容易漏觸發：

description: 建立資料視覺化介面。

✅ 明確列出觸發情境：

description: This skill should be used when the user asks to build a dashboard or data visualization interface. Use this skill whenever the user mentions dashboards, internal metrics, data display, or wants to visualize any kind of company data, even if they don't explicitly say "dashboard".

另外，description 也值得說明不觸發的邊界，特別是當你的 Skill 和其他 Skill 的領域有重疊時，像 xlsx Skill 那樣明確排除「主要產出是 HTML 報表」的情況。

---

實作時踩過的坑

1. name 和資料夾名稱要完全一致

SKILL.md 裡的 name 欄位必須和資料夾名稱相同，否則 Skill 無法正確載入。

2. SKILL.md 要主動指向子目錄資源

Claude 不會自動掃描 references/ 裡面有什麼，你需要在 SKILL.md 內文裡明確告訴它：

## 延伸資源

需要更詳細的規則時，參考：
- **`references/formatting-guide.md`** — 格式規範細節
- **`scripts/validate.py`** — 格式驗證腳本

忘記這步的話，那些精心準備的參考文件就白費了。

3. SKILL.md 內文不要塞太多

SKILL.md 啟動時整個讀進 context，建議控制在 1,500 到 2,000 words 左右。 大量的參考資料、邊界情況說明、詳細範例，都搬到 references/ 目錄，按需載入。

4. description 不要超過 1024 字元

description 雖然要寫得完整，但有字元上限，而且它一直佔用 context，重點放在「觸發情境」和「做什麼」就好，不需要把整個操作流程都塞進去。

---

自己從零寫一個 Skill

如果不用 Skill Creator，從零開始寫一個最簡單的 Skill 也不複雜，只要一個資料夾加一個 SKILL.md。這裡用一個 commit message 規範的 Skill 來示範整個流程。

先建立資料夾，名稱就是 Skill 的 name：

mkdir -p ~/.claude/skills/commit-helper

放在 ~/.claude/skills/ 下的 Skill 是個人全域的，在你的任何專案都有效。 如果只想在特定專案使用，可以放在專案根目錄的 .claude/skills/ 下，這個資料夾也可以 commit 進 repo 跟著版控。

不過有個反直覺的地方：當兩個層級存在同名 Skill 時，全域 Skill 的優先級高於專案 Skill。所以如果全域已經有一個 commit-helper，專案裡的同名版本不會生效。

接著建立 SKILL.md：

---
name: commit-helper
description: This skill should be used when the user wants to write a commit message,
  asks "how should I commit this", or is about to run git commit. Guides writing
  conventional commit messages following the Conventional Commits specification.
---

# Commit Message 指引

Follow the Conventional Commits format: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

Rules:
- Keep the subject line under 72 characters
- Use present tense ("add feature", not "added feature")
- No period at the end of the subject line
- Reference issue numbers when relevant: `fix(auth): correct token expiry (#123)`

Examples:
Input: 新增使用者登入功能，用 JWT 處理 token
Output: feat(auth): add JWT-based user authentication

Input: 修復購物車數量計算錯誤
Output: fix(cart): correct item quantity calculation

這樣就完成了。來拆解每個部分：

name 欄位對應資料夾名稱，必須完全一致。命名規則是小寫字母、數字和連字號，不能有大寫。

description 是 Claude 判斷要不要啟動這個 Skill 的唯一依據。它一直在 context 裡，所以要寫得精準但不囉嗦。這裡用第三人稱格式（This skill should be used when...），並且明確列出幾種觸發場景：「想寫 commit message」、「問 how should I commit this」、「要跑 git commit」。 這三種說法分別對應不同使用者的口頭習慣，都能觸發。

內文 用祈使句寫直接指令（Follow、Keep、Use），不用「你應該...」這樣的第二人稱。最後的 Examples 區塊很重要，因為 Input/Output 的對比比起文字描述更直接，Claude 更容易理解期望的輸出格式。

存好之後，開一個新的對話，之後只要說「幫我寫這次的 commit」，Claude 就會套用這套規則來建議 commit message，不用每次再解釋格式。

這個例子雖然簡單，但可以感受到把知識寫成 Skill 帶來的幾個具體好處。

第一個是一致性。以前每次請 Claude 寫 commit message，它的風格多少會有差異，有時用過去式、有時用中文。寫成 Skill 之後，每次都會照固定格式輸出，整個 git log 風格統一，之後 changelog 也好自動生成。

第二個是可以隨時疊加細節。需求可以一直增長：這個月 code review 之後發現 scope 的寫法有爭議，直接去改 SKILL.md 就好；下次加入新成員，把 Skill 資料夾複製給他，規範同步就完成了。 相比在 chat 裡每次貼上規則，Skill 是可以持續維護的。

第三個是不佔任何 context，除非真的要寫 commit。skills 的 description 雖然一直在，但它很短，只要不觸發，完整的 commit 規則不會干擾其他任何對話。 這和在 CLAUDE.md 裡寫死規則不一樣，CLAUDE.md 的內容從打開專案的那一刻起就全部進 context，不管當下的任務是不是跟 commit 有關。

---

Skills 和 CLAUDE.md 的差異

用過 CLAUDE.md 的人可能會有個疑問：兩者都是給 Claude 的指令，到底有什麼不同？

簡單說：CLAUDE.md 是「這個專案的說明書」，Skills 是「你個人的工具包」。

	CLAUDE.md	Skills
作用範圍	綁定在某個專案目錄	可攜，跨專案使用
觸發方式	進入專案時自動載入	Claude 依需求判斷是否啟動
適合放什麼	這個 repo 特有的規範、架構說明	可重複使用的流程、領域知識
維護方式	跟著 repo 版控	獨立管理，可分享給他人

舉個具體例子。這個部落格的 VitePress 目錄結構、frontmatter 格式、URL rewrite 邏輯，適合放在 CLAUDE.md，因為這些是這個 repo 特有的，換個專案就沒用了。但「寫 conventional commit」、「處理 Excel 檔案」、「套用品牌設計規範」這類知識，放在 Skills 更合適，因為在任何專案都能直接用。

兩者可以並存，互補。

CLAUDE.md 告訴 Claude「這個專案是什麼」，Skills 告訴 Claude「遇到 X 情況要怎麼做」。

---

團隊開發時怎麼共享 Skills

個人 Skill 寫好之後，下一個問題通常是：怎麼讓整個團隊都用到？

最直接的方式是把 Skills 放進專案的版本控制。在 repo 根目錄建立 .claude/skills/，把 Skill 資料夾放進去，commit 上去，之後 clone 這個 repo 的人就自動拿到這些 Skills。這特別適合和專案強相關的 Skill，例如「按照這個 codebase 的命名慣例產生 component」，放全域沒有意義，但放 repo 裡就能讓所有貢獻者共享同一套規則。

如果 Skill 不屬於某個特定 repo，而是整個組織都想用的通用工具，可以另外建一個獨立的 skills repo，然後用 plugin marketplace 的方式發佈：

/plugin marketplace add your-org/skills

這樣成員只要執行一次安裝，就能用到所有共享的 Skills，之後更新也只要在 repo 上改，不用每個人手動同步。anthropics/skills 就是這個模式。

第三個管道是把 Skill 打包成 .skill 檔案。Skill Creator 裡有一個 package_skill.py 腳本，可以把整個 Skill 資料夾打包成單一檔案，方便透過 Slack、email 或 PR 傳給同事，接收方直接安裝就好，不需要接觸 repo。

---

Skill 什麼時候該拆、什麼時候該合

寫幾個 Skill 之後，難免會碰到這個問題：兩件事該放在同一個 Skill 裡，還是分開？

傾向分開的情況： 兩個功能的觸發時機根本不同，強行放在一起只會讓 description 越來越難寫，而且 Claude 可能因為無法精確判斷而誤觸發。例如「產生測試案例」和「跑 E2E 測試」，雖然都跟測試有關，但前者是在寫 code 的當下觸發，後者是準備部署的時候觸發，分開讓兩個 description 都能寫得更精準。另外，當 SKILL.md 的內文開始逼近 500 行，也是一個該考慮拆分的訊號，可以把其中一個領域移到獨立 Skill，再用 references/ 的方式讓它們按需互相參照。

傾向合在一起的情況： 兩個任務幾乎總是同時出現，每次用一個必然也用另一個，拆開反而增加維護成本。或者兩個任務共用大量的背景知識，合在一起可以讓這些知識只寫一次。

最實用的判斷方式是問：「這兩件事的觸發場景，我能用一句話說清楚嗎？」如果 description 需要塞很多「也可以用來做 Y，以及 Z」，通常就是一個應該拆分的訊號。

---

總結

Skills 解決的是「重複解釋背景」的問題，把工作流程、規範或領域知識打包成可以隨時叫用的工具。Skill Creator 讓開發流程有了明確的迭代結構；project-level 的 .claude/skills/ 讓 Skills 可以跟著 repo 走、隨團隊共享；拆或合的判斷則回歸到一個問題：這個 Skill 的觸發時機，能不能用一句話說清楚。

如果你有某個任務需要每隔幾天就跟 Claude 重新解釋一遍，那大概就是值得做成 Skill 的候選。最小可行的 Skill 只需要一個資料夾加一個 SKILL.md，門檻很低，可以先試試看效果。