Claude Code Skill 建立完整指南

Step 1–7 完整流程，適用於 VS Code + Claude Code 環境

前置準備：安裝 Claude Code

在終端機執行安裝指令：
npm install -g @anthropic/claude-code

Step 1 決定 Skill 的目的

開始前先回答這三個問題，目的越具體越好。

問題	範例答案
這個 Skill 要做什麼？	產出 Meta 廣告文案與圖片素材建議
什麼時候應該觸發？	使用者提到「廣告」、「文案」、「投放」等關鍵詞
輸出格式是什麼？	5組文案 + 素材建議 + 投放建議

注意事項

不要試圖讓一個 Skill 做太多事。觸發時機要主動，即使使用者沒有明確要求也應該觸發。輸出格式要先想清楚，後面 SKILL.md 都會依此撰寫。

Step 2 建立資料夾結構

在 VS Code 終端機執行（Windows PowerShell）：

mkdir my-skill
mkdir my-skill\references
mkdir my-skill\assets
mkdir my-skill\scripts

或直接在 VS Code 左側檔案總管右鍵新增資料夾。完成後結構如下：

my-skill/
├── SKILL.md           ← 核心文件（必要）
├── evals.json         ← 品質測試案例（必要）
├── trigger-evals.json ← 觸發時機測試（建議）
├── references/        ← 參考素材庫（選填）
├── assets/            ← 圖片、範本等（選填）
└── scripts/           ← 自動化腳本（選填）

重要：檔名不能有空格

例如應命名為 high-performance-examples.md，而非 high performance examples .md，多一個空格會導致 Claude 找不到檔案。

Step 3 撰寫 SKILL.md

這是最重要的一步。SKILL.md 需包含以下區塊：

name description（觸發條件）參考素材庫使用者需提供的資訊產出格式寫作原則輸出範例

---
name: skill名稱（英文小寫，用連字號）
description: |
  說明這個 Skill 做什麼，包含觸發關鍵詞。
  只要使用者提到「XXX」、「YYY」等關鍵詞，
  就必須立即使用這個 Skill，即使沒有明確要求。
---

三個關鍵原則

原則一：description 最重要 — Claude 決定「要不要用這個 Skill」的唯一依據，要包含觸發關鍵詞。

原則二：輸出範例要夠長 — 範例的長度就是 Claude 產出的長度基準，範例太短輸出就會太短。

原則三：fallback 邏輯要寫清楚 — 使用者沒提供某些資訊時，Skill 應該怎麼處理，要明確說明。

Step 4 建立測試案例

建立兩個測試檔案，分別測試不同面向：

檔案	測試什麼
evals.json	觸發後，輸出品質是否達標
trigger-evals.json	觸發時機對不對（該啟動時有啟動）

[
  {
    "prompt": "使用者的完整輸入（含所有必要資訊）",
    "assertions": [
      "產出 5 組文案（A-E）",
      "Primary Text 字數 ≥ 300 字",
      "每組 Headline 在 15 字以內",
      "文案結尾包含品牌署名"
    ]
  }
]

assertions 要細緻

不只驗證「有沒有」，也要驗證「好不好」。建議準備 5 個測試案例，涵蓋不同使用情境、有提供完整資訊 vs 部分資訊的情況。

Step 5 執行測試

啟動 Claude Code 後，在對話框輸入：

請讀取 my-skill/SKILL.md 與參考素材庫，
執行 my-skill/evals.json 的全部測試案例，
針對每個案例給我通過率與改善建議。

常見錯誤排除：

錯誤訊息	原因	解決方式
找不到 references/xxx.md	檔名有空格或路徑錯誤	VS Code 右鍵重新命名，確認無空格
find 指令無效	Windows 不支援 Linux 指令	改用 Get-ChildItem -Recurse -Filter "檔名"
指令重複執行	貼上時誤觸複製	一次只貼一行指令

Step 6 根據結果修改 SKILL.md

測試完後針對不通過的項目修改。最常需要調整的三個地方：

輸出內容太少 → 加字數要求 + 拉長範例格式欄位不完整 → 細化每個欄位說明與範例特殊情況未處理 → 加 fallback 邏輯

修改循環

修改 SKILL.md → 重新執行測試 → 看結果 → 再修改 → 重複直到全部通過

Step 7 打包成 .skill 檔

先確認資料夾結構完整：

Get-ChildItem -Recurse my-skill

確認無誤後，在 Claude Code 對話框輸入：

請將 my-skill/ 資料夾打包成 my-skill.skill 檔案，輸出到目前目錄下。

確認打包成功：

Get-ChildItem -Filter "*.skill"

完成

看到 .skill 檔案出現代表打包成功，可以安裝到任何 Claude Code 環境中使用。

快速檢查清單

Step 1：目的、觸發條件、輸出格式都想清楚

Step 2：資料夾結構完成，檔名無空格

Step 3：description 有寫觸發關鍵詞

Step 3：輸出範例夠長，fallback 邏輯完整

Step 4：evals.json 有 5 個測試案例

Step 4：assertions 有驗證「好不好」

Step 5：測試全部通過

Step 6：根據建議修改並重新測試

Step 7：打包完成，.skill 檔案存在