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

多數 Skill 都很爛，原因在這

Agent skills 生態系在 2026 年 3 月突破 351,000 個。數字看起來很漂亮，直到你開始用才知道有多慘。多數 skill 是廢物——該觸發的時候不觸發，不該觸發的時候亂觸發，或是給的指令空泛到 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 這個 skill 做什麼、什麼時候該啟動、輸出長什麼樣。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 次取可靠的觸發率。系統將 eval set 拆成 60/40 的 train/test，評估當前 description，根據失敗案例提出改進建議，然後迭代。

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

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

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

死板的寫法：

## 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 表現的 SKILL.md。ETH Zurich 的研究證實了這點：更多 context 不等於更好的結果。Agent 出乎意料地擅長自己發現需要的東西；預載所有東西只會增加 token 成本和認知負擔。

三層系統：

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

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

第三層：Reference 檔案 + scripts（按需載入）。 詳細的 API 規格、完整的檢查清單、模板庫、驗證腳本。只在 agent 碰到需要它們的任務時才載入。

經驗法則：如果一個段落只在 20% 的使用案例中用得到，它就該放在 reference 檔案裡，而不是 SKILL.md body 中。一個 code review skill 如果包含 200 行安全專用檢查清單，應該把那份清單放在 references/security-checklist.md，然後告訴 agent 只在審查 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 的部署 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 行。如果你的 skill 超過 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 自動化了這個 loop——它用四個可組合的子 agent（executor、grader、comparator、analyzer）對 eval prompt 跑 skill、評分輸出、在 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、部署、測試、文件和 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 可設定且有文件說明。

發布前檢查清單

在發布或分享 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 相容性。這篇文章講的是手藝。兩者都重要。