什麼是好的 Skill？讓 Agent Skill 真正有用的設計原則

多數 Skill 都很爛，原因在這

Agent skill 生態系在 2026 年 3 月突破 351,000 個。數字看起來很漂亮。然後你開始用。多數是廢物。該觸發的不觸發。不該觸發的亂觸發。給的指令空泛到 agent 沒載入反而表現更好。

寫一個 SKILL.md 非常簡單。建個目錄、丟個 Markdown 檔進去、寫幾行 YAML frontmatter，你就有了一個「skill」。逐步教學五分鐘搞定。但格式正確和 skill 真正能用，是完全不同的兩件事。

品質門檻這麼低，因為生態系獎勵數量而非效果。SkillsMP 爬 GitHub 上任何帶 SKILL.md 的東西就收錄。結果：數千個看起來完整但一碰真實 prompt 就崩潰的 skill。

本文聚焦「語法正確的 skill」和「真正好用的 skill」之間的差距。如果你已經會寫 SKILL.md 格式，接下來該學的就是設計思維 -- 把人們真的在用的 skill 和在 marketplace 上長灰塵的 skill 區分開來的東西。

原則來自 Anthropic 的 Skill Creator 方法論、Jesse Vincent 的 Superpowers 框架、ETH Zurich 關於 context 檔案有效性的研究，以及大量閱讀 skill 執行逐字稿來看東西實際在哪裡壞掉。

原則一：Description 決定一切

SKILL.md frontmatter 裡的 description 欄位是主要觸發機制。使用者發 prompt 時，agent 讀每個已安裝 skill 的 description 來決定載入哪些。Description 含糊，skill 就 undertrigger -- 裝了等於沒裝。太窄，就漏掉合理的使用場景。

差的寫法：

description: Helps with code review.

「Helps with」毫無意義。Agent 無法判斷這 skill 什麼時候比內建的 code review 行為更適合。沒有觸發條件、沒有特異性、沒有訊號。

好的寫法：

description: >
  Performs comprehensive code review after writing or modifying code.
  Use when completing logical chunks of development work. Analyzes
  security vulnerabilities, correctness issues, performance problems,
  and maintainability concerns. Outputs structured findings with
  severity ratings. Activate for PR reviews, staged change reviews,
  and file-level audits.

告訴 agent 做什麼、什麼時候啟動、輸出長什麼樣。對任何 prompt 都能做明確的 yes/no 判斷。

「積極主動」技巧

Anthropic 自己的文件承認 Claude 傾向 undertrigger skill -- 該用的時候不用。解法：description 寫得稍微積極一點。

不要寫「Can be used for deployment tasks」，要寫「Use this skill whenever the user asks to deploy, push to staging, release, ship, or when you detect deployment-related file changes.」觸發條件一個個列出來。寧可觸發太頻繁。載入不相關 skill 的成本（幾百 token 的 context）遠低於沒載入相關 skill 的成本（agent 自己亂來然後搞砸）。

測試觸發準確率

Skill Creator 的 description 最佳化提供嚴謹方法：建 20 個 eval query -- 10 個該觸發、10 個不該觸發。每個 query 跑 3 次取可靠觸發率。系統拆成 60/40 的 train/test，評估當前 description，根據失敗提改進建議，然後迭代。

你不需要 Skill Creator 也能手動做。寫 20 個 prompt，對 agent 跑一遍，數幾個正確觸發、幾個正確沒觸發。準確率低於 80% 就重寫 description 再測。無聊，但最高槓桿的改進。

原則二：解釋為什麼，不只是什麼

LLM 不是需要死板指令的規則執行機器。它們是推理引擎，對解釋過的理由反應比命令式規定更好。

死板寫法：

## Rules
- ALWAYS use TDD. NEVER skip tests.
- ALWAYS validate input. NEVER trust user data.
- MUST use error boundaries around every async operation.

推理導向寫法：

## 測試哲學

測試在 regression 到達使用者之前就攔住它。先寫測試，
這樣你在寫實作之前就知道「成功」長什麼樣。
當測試一開始就失敗，你有了它確實在測正確行為的證據
-- 而不是碰巧通過。

## 輸入驗證

外部資料（使用者輸入、API 回應、檔案內容）到達時的
形狀你控制不了。在邊界處驗證，這樣內部程式碼就能信任
它的輸入。把錯誤處理移到 context 最豐富的邊緣，
讓核心邏輯保持乾淨。

兩種都說「做 TDD」和「驗證輸入」。第二種解釋了為什麼，讓 agent 在邊界情況有足夠 context 做好判斷。模型碰到 skill 作者沒預料到的狀況時，推理式指令能泛化。規則式指令讓模型只能猜。

MUST/ALWAYS/NEVER 陷阱

重磅規則感覺很權威，效果比解釋過的推理差。ETH Zurich 2026 年 2 月的研究發現，過度詳細和限制性的指令實際上降低了 agent 任務成功率。表現最好的 agent 搭配的是精簡原則式引導 -- 不是整面牆的全大寫命令。

什麼時候該用死板規則

安全約束和合規要求是例外。「絕不把 AWS credentials commit 到版控」不是需要細緻推理的地方。「絕不修改已存在的 migration 檔案」是硬性約束，違反會造成真實損害。二元的、不可商量的約束用死板規則。其餘一切用推理。

原則三：漸進式揭露

觸發時就把 500 行指令倒進 context window 的 SKILL.md，會拉低 agent 表現。ETH Zurich 研究證實：更多 context 不等於更好結果。Agent 出乎意料地擅長自己發現需要的東西。預載所有東西只增加 token 成本和認知負擔。

三層系統：

第一層：Metadata（約 100 字，永遠載入）。 Frontmatter 的 name 和 description。每個已安裝 skill 的 metadata 在 session 開始就載入。觸發機制，保持精簡。

第二層：SKILL.md body（< 500 行，觸發時載入）。 主要指令。Agent 決定 skill 相關時讀的內容。應包含流程、關鍵規則、指向 reference 檔案的指引。

第三層：Reference 檔案 + script（按需載入）。 詳細 API 規格、完整 checklist、模板庫、驗證 script。只在 agent 碰到需要的任務時載入。

經驗法則：段落只在 20% 使用案例中用到，就該放 reference 檔案而非 SKILL.md body。Code review skill 包含 200 行安全 checklist 的話，把 checklist 放 references/security-checklist.md，告訴 agent 只在 review auth 相關程式碼時才載。

關於 SKILL.md、CLAUDE.md、AGENTS.md 如何互動（以及漸進式揭露如何融入更廣泛的 context engineering 策略），詳見 SKILL.md vs CLAUDE.md vs AGENTS.md。

原則四：確定性工作交給 Script

能寫成 script 的就該寫成 script。LLM 在重複性、精確的任務上不可靠。計算行數、驗證結構化格式、跑特定命令序列、檢查檔案存在模式 -- 這些 LLM 偶爾會幻覺或每次跑法都不一樣。

適合 script 的任務：

• 檔案驗證（frontmatter 有所有必填欄位嗎？）
• 格式檢查（commit message 符合 Conventional Commits 嗎？）
• 資料擷取（從 codebase 拉出所有 TODO）
• API 呼叫（打 health endpoint 回報狀態）
• 起飛前檢查（dependency 都裝了嗎？資料庫跑起來了嗎？）

不適合的任務：

• 創意決策（哪種架構模式適合這個問題？）
• 依 context 而定的選擇（該新建元件還是擴充現有的？）
• 主觀評估（這段程式碼結構好嗎？）

具體範例 -- 驗證 SKILL.md frontmatter 的 script：

#!/bin/bash
# 驗證 SKILL.md frontmatter 欄位
SKILL_FILE="$1"

if [ ! -f "$SKILL_FILE" ]; then
  echo "Error: File not found: $SKILL_FILE"
  exit 1
fi

ERRORS=0

if ! grep -q '^name:' "$SKILL_FILE"; then
  echo "Missing required field: name"
  ERRORS=$((ERRORS + 1))
fi

if ! grep -q '^description:' "$SKILL_FILE"; then
  echo "Missing required field: description"
  ERRORS=$((ERRORS + 1))
fi

LINES=$(wc -l < "$SKILL_FILE")
if [ "$LINES" -gt 500 ]; then
  echo "Warning: SKILL.md is $LINES lines (recommended < 500)"
fi

if [ "$ERRORS" -gt 0 ]; then
  echo "$ERRORS error(s) found."
  exit 1
fi

echo "Validation passed."
exit 0

Agent 跑 script 拿到確定性 pass/fail 結果。沒有解讀差異、沒有幻覺欄位名、沒有跳過的檢查。Script 做什麼就是做什麼，每次都一樣。

SKILL.md 簡單引用：

## 驗證

發布前先驗證 skill：

```bash
bash scripts/validate-skill.sh SKILL.md

Script 原始碼不進 context window -- 只有輸出會。Agent 推理空間保持乾淨，機械性任務精確可重複。

原則五：為你沒見過的邊界情況設計

好 skill 能優雅處理非預期輸入。多數 skill 的失敗模式不是 happy path 壞掉，而是碰到稍微不同的專案結構、不同措辭、不同技術棧就輸出垃圾。

「心智理論」方法：

想想使用者可能用的 10 種不同措辭。 「Review this code」「check my PR」「audit the auth module」「is this safe to merge?」-- 只對「review code」觸發的 code review skill 會漏掉大部分真實使用。

想想 skill 可能跑在的 5 種不同專案類型。 假設用 Docker 的 deploy skill 在 serverless 專案會失敗。假設用 Jest 的測試 skill 在用 Vitest 的專案會失敗。寫引用專案實際工具的指令，不要寫死偏好的技術棧。

寫能泛化的指令，不要 overfit。 Jesse Vincent 的 Superpowers 示範得很好。Brainstorming skill 不是說「問剛好這 5 個問題」，它解釋原則（commit 之前探索多種方法），讓 agent 把原則適配到具體 context。所以 Superpowers 能跨完全不同的專案類型運作，而死板模板 skill 一碰到作者設定之外的東西就壞。

泛化測試：完全不同專案類型的開發者能不能從這 skill 的指令受益？不能的話就 overfit 了。把原則萃取出來，讓 agent 依 context 應用。

原則六：保持精簡

每一條沒在出力的指令都在浪費 context、混淆模型。最好的 skill 都很短。不是因為短本身就好，而是短的 skill 裡每一行都是承重的。

讀逐字稿，不只讀輸出。 對 skill 最有揭示力的 debug 技巧是讀完整 agent 逐字稿 -- 推理過程，不只最終輸出。你會發現：

• Agent 讀了但從沒用到的段落（刪掉）
• Agent 因措辭含糊而誤解的指令（重寫）
• Agent 花推理 token 把指令複述一遍給自己聽的地方（你的指令太囉嗦）

移除永遠被跳過的段落。 Skill 有個「Edge Cases」段落 agent 跑 10 次都沒引用過，就是死重量。要嘛邊界情況沒觸發，要嘛 agent 不需要指令就處理得好。

把全大寫規則改寫成推理。 在寫 ALWAYS 和 NEVER 的話，停下來。你在用音量補償不清楚的推理。「NEVER use default exports」比不上「Named exports enable tree-shaking and make refactoring safer because the import name is tied to the export site, not the consumer.」第二種解釋了為什麼，agent 在第一種沒覆蓋到的邊界情況也能正確應用。

Agent Skills 完全指南建議 SKILL.md 控制在 500 行以內。那是天花板，不是目標。很多有效 skill 不到 100 行。超過 200 行就審計一下：每個段落都在賺回它的 context 成本嗎？

Eval Loop：如何真正測試一個 Skill

寫 skill 不測試就像寫程式不跑一樣。Anthropic Skill Creator 2026 年 3 月更新加入 eval、improve、benchmark 模式，把這件事形式化成任何 skill 作者都能遵循的方法論。

四步驟流程

第一步：寫 2-3 個測試 prompt。 要寫實 -- 用真實使用者會打的措辭和 context。不是「test the skill」而是「我剛完成 auth 模組重構。Review 這個 branch 上的改動，告訴我是否可以安全 merge。」

第二步：跑有 skill vs 無 skill 對比。 Skill 有改善輸出嗎？這是唯一重要的問題。Agent 不用 skill 也能產出同等結果的話，skill 就是花 context 成本沒帶來價值。

第三步：讀完整逐字稿。 不只輸出 -- 推理過程。Agent 有載入 skill 嗎？有遵循指令嗎？在哪偏離？在哪浪費時間？

第四步：迭代。 根據發現修 skill，重跑，再檢視。Skill Creator 用四個可組合的子 agent（executor、grader、comparator、analyzer）自動化這個 loop -- 對 eval prompt 跑 skill、評分輸出、在版本之間做盲測 A/B 對比、挖出聚合統計可能藏住的模式。

Description 最佳化

Skill Creator 的 description 最佳化值得特別關注。用 train/test split：60% eval query 當訓練集，40% 留作測試。系統跑每個訓練 query 3 次來評估當前 description 的觸發率，根據失敗案例提改進 description，再評估，再迭代。

改善觸發準確率最系統化的方式。即使沒工具，原則一樣：量測、分析失敗、改進、再量測。多數 skill 作者寫一次 description 就再也不碰。所以多數 skill undertrigger。

多面板的優勢

迭代測試 loop（改 skill、跑 prompt、看逐字稿、再改）就是多終端面板並排的價值所在。SKILL.md 在一個面板、agent session 在另一個、逐字稿或輸出在第三個。不切 tab、不丟 context，就是緊湊的 feedback loop。

反模式：看起來不錯但會失敗的 Skill

「廚房水槽」Skill

試圖在一個 skill 裡處理 code review、deploy、測試、文件和 PR description。Description 變得太寬泛，什麼都觸發或什麼都不觸發。Body 800 行以上，agent 淹沒在指令裡。拆開。一個 skill，一個動詞。

「複製貼上」Skill

沒有結構的原始 prompt 傾倒。沒有明確觸發條件、沒有流程步驟，就是一堆段落文字。作者把 ChatGPT prompt 複製進 SKILL.md 就叫它 skill。Agent 無法從非結構化文字牆解析意圖。結構很重要：段落、標題、有序步驟。

「僵化模板」Skill

使用者措辭剛好跟作者預期一樣時完美運作，偏一點就壞。「When the user says 'create component X', do the following...」一旦有人說「build a new widget for the dashboard」就失敗。針對意圖寫，不要針對精確措辭。

「沒有文件」Skill

Description 或 body 裡都沒有明確觸發條件。仰賴使用者知道 slash command 存在。沒有明確「When to Activate」和「When NOT to Activate」段落，自動觸發就是擲銅板。只靠手動叫用的 skill，對 90% 使用者等於隱形。

「安全漏洞」Skill

不驗證就跑 shell 命令、從寫死 URL 下載檔案、叫 agent 讀敏感檔案把內容放進輸出。Snyk ToxicSkills 研究在掃描的 3,984 個 skill 中發現 534 個有 critical 安全問題。Skill 跑命令就驗證輸入。讀檔案就限制路徑。發 network request 就讓 URL 可設定且有文件。

發布前 Checklist

發布或分享 skill 之前，過一遍品質關卡：

• Description 具體、包含觸發條件、稍微「積極主動」
• Body 解釋規則背後的 WHY，不只 WHAT
• SKILL.md 500 行以內；詳細 reference 放獨立檔案
• 確定性任務用 script，不用自然語言指令
• 用 2-3 個寫實 prompt 測過，輸出對比過無 skill 基準線
• 觸發準確率測過：至少 10 個該觸發和 10 個不該觸發的 query
• 沒有寫死路徑、API key 或環境特定值
• 跨 Claude Code 和至少一個其他 agent（Codex CLI 或 Copilot）能運作
• 有明確「When to Activate」和「When NOT to Activate」段落
• Body 每個段落都是承重的 -- 沒有死重量

寫好 skill 和寫好程式碼是同一種紀律：對留下的東西毫不留情、對什麼有用保持誠實、永遠對現實做測試。Agent Skills 完全指南涵蓋完整生態系 -- marketplace、安全、跨 agent 相容性。這篇講的是手藝。兩者都重要。