TL;DR
寫好 SKILL.md，讓 Agent 在一次示範中順利完成工作，是個不錯的開始。若希望這套方法能長期使用，還需要確認它會在正確時機被載入、能否改善實際任務，以及換了模型或專案版本之後是否仍可靠。
Agent Skill Eval（技能評估）可以從少量真實任務開始：先記錄觸發情況，再以相同的任務比較「使用 Skill」和「未使用 Skill／使用舊版本」的結果。除了輸出品質，也要觀察驗證證據、時間、Token 與失敗處理方式。本文以一個虛構的 Selenium 除錯情境，示範如何建立可延伸的評估起點；文中的範例尚未執行 Agent 或 Selenium 實測，沒有作者宣稱的改善幅度。
Takeaways｜重點整理
- 載入成功需要另外驗證。 Skill 名稱或描述出現在候選清單，尚不足以證明 Agent 真的讀過
SKILL.md。 - 兩組執行條件要盡量一致。 同一題分別使用 Skill 和對照組，才看得出新增指引可能帶來的差異。
- 先驗收結果，再檢查重要路徑。 成功訊息不能取代產物與測試證據；遇到存取權限、禁止修改等限制，還要確認執行過程。
- 評分器也需要受檢查。 程式檢查適合驗證 JSON、檔案與客觀條件；模糊判斷可補人工審閱，避免只看漂亮分數。
- 成本與退化應一起比較。 多讀一份 Skill 可能增加 Token；模型、工具和專案版本變動後，舊有建議也可能失準。
一輪示範成功還不足以證明 Skill 有幫助
想像你寫了一個協助判讀 Selenium 測試失敗的 Skill。第一次試用，Agent 讀取一段 TimeoutException 訊息，列出可能原因，還提醒你檢查網路和元素定位。文字清楚，似乎已經能交付。
換一段記錄，Agent 卻直接斷言「系統有 Bug」，沒有提出重現證據。另一次，它根本沒讀取那份 Skill，照樣生成一段像模像樣的分析。這兩次失敗，一次出在判斷品質，一次出在觸發流程；單憑第一輪成功很難發現。
2026 年的 SWE-Skills-Bench 研究提出一個警訊。研究者以固定版本的 GitHub 專案及約 565 個軟體工程任務，比較 49 個公開 Skill 的使用效果。39 個 Skill 未改善測試通過率，整體平均增益僅 +1.2%；少數專門 Skill 有明顯幫助，也有 Skill 因建議與專案版本不相容而降低表現。研究同時觀察到，部分情況下 Token 額外消耗可達 451%，卻沒有改善通過率。
這些數字只描述該論文的實驗條件，無法套用為所有 Agent、Skill 或企業流程的預測。它提出的問題倒很實用：如果沒有對照組，我們怎麼知道效果來自 Skill，還是原本的模型就能完成？
觸發測試能找出 Skill 沒有被正確使用的情況
Agent Skills 的 官方觸發優化指南指出，Agent 往往先依 SKILL.md 的名稱和 description 判斷要不要載入完整內容。描述太寬，容易處理不屬於它的任務；描述太窄，真正需要它的請求可能被略過。
對「Selenium 失敗分析」Skill，可以先寫幾則接近真實工作的使用者請求：
| 使用者請求（示意） | 預期載入 | 驗證目的 |
|---|---|---|
| 「登入測試一直等待逾時，幫我依 log 分析可能原因與還缺哪些證據」 | 是 | 使用者沒點名 Skill，仍能辨識需要失敗分析 |
| 「同一支 Selenium 測試隔天又失敗，先比較兩次錯誤訊息」 | 是 | 測試相近的調查意圖 |
| 「請翻譯這段 TimeoutException 英文訊息」 | 否 | 同樣出現例外名稱，但只有翻譯需求 |
| 「幫我重構 Python Selenium 的 Page Object 類別」 | 否 | 涉及 Selenium，工作卻是程式重構 |
表中的預期僅適用於這個示範 Skill 的假定職責。真實系統必須依 Skill 的正式 description、可用工具及其他競爭 Skill，重新定義哪些情境應觸發。
記錄每次請求中 Agent 實際讀取 Skill 檔案的證據，再計算觸發率；不要只看回覆是否提到 Skill 名稱。官方建議起步可準備約 20 題、正反例各約 8～10 題，並將容易混淆的請求納入；每題重跑 3 次是可行的初始設定。資料累積後再拆分調整用題目與保留驗證題目，避免把描述寫成只會應付固定題型。
可觀察的驗收條件讓評估結果具有可比性
Skill 是否正確載入，只驗證了入口。下一步，是替任務定義可觀察的結果。
以 Selenium 逾時為例，看到 TimeoutException 只能確定「等待條件在期限內沒有成立」。產品缺陷、測試腳本、測試資料及環境問題，都仍需要額外證據。若 Agent 只根據單筆逾時訊息便宣布產品有缺陷，分析就越過了現有證據。
這個示範的合理要求可以寫得具體一些：輸出必須分清觀察事實、可能原因與下一步查證；單筆逾時證據不足時，結論應保留未知；在取得授權前不得擅自修改檔案或重跑測試。
Agent Skills 官方評估指南建議從少量真實提示詞與預期結果開始，再依第一輪執行產物補上可以檢查的斷言。品質評估最忌諱把「回答得很專業」當成通過條件；它聽起來肯定，實際上無法重現或駁斥。
對不同任務，需要檢查的事情也不同：
| 評估面向 | 可以查驗的證據 | 檢查時要留意 |
|---|---|---|
| 觸發（Routing） | 執行紀錄顯示是否讀取正確的 SKILL.md | 別把輸出提及 Skill 當成已載入 |
| 成果（Outcome） | JSON、報告、測試結果或其他實際產物 | Agent 說「完成」不代表檔案存在 |
| 執行軌跡（Trajectory） | 工具呼叫、參考資料、驗證步驟與修改紀錄 | 重要權限限制要查，但不要限制所有合法解題路徑 |
| 成本與穩定性 | Token、耗時、重試次數、跨次結果 | 必須連同模型、環境和工作範圍一起記錄 |
這張表是依官方指引整理的實務分類，並非 Agent Skills 規格強制要求的四個欄位。
一個 Selenium 失敗分析案例可以如何建立最小對照
下面的例子僅使用虛構事件：測試等待網頁上的 #order-status 元素，最後收到逾時訊息；沒有 DOM、截圖、伺服器日誌與產品版本差異等輔助資料。
先在私人實驗工作區替同一則使用者請求建立測試案例。官方 creator 流程使用 evals/evals.json 保存任務、預期輸出與選用的輸入檔案。以下是簡化版內容，讀者可依自己的 Skill 名稱及 Agent 工具調整：
{
"skill_name": "selenium-failure-triage",
"evals": [
{
"id": 1,
"prompt": "測試等待 #order-status 元素時發生 TimeoutException。除此之外沒有截圖、DOM 或伺服器日誌。請只依現有證據回覆 JSON：observations、possible_causes、next_checks 均為至少含一項非空白字串的陣列，分別列出等待逾時的觀察、尚待查證的可能原因與可取得的下一步證據（可用中文描述逾時）；conclusion_status 為 unknown 或 supported，缺少佐證時請填 unknown。不要修改任何檔案，也不要自行重跑測試。",
"expected_output": "observations 正確描述 #order-status 的等待逾時（可用 TimeoutException 或中文），possible_causes 將原因保留為待驗證假設，next_checks 提出可取得的證據；三個陣列皆有至少一項非空白文字。僅憑此筆訊息時 conclusion_status 應為 unknown；不得修改檔案或自行重跑測試。文字判斷與權限遵守情形仍須另外查證。"
}
]
}這份 JSON 是評估案例的示意素材，還需要 Agent 執行器、實際產物保存方式與評分邏輯，才能變成可跑的測試系統。expected_output 是給人閱讀的成功條件描述，其中的語意品質與「不得修改檔案」都無法單靠輸出 JSON 證明。evals/ 也是官方建議的創作者評估目錄，並非每個 Skill 執行時都強制必備的規格目錄。
接著安排兩種條件：一組允許載入待測 Skill，另一組不提供該 Skill；如果目的是比較改版，就讓對照組使用上一個固定版本。兩組應看到相同的提示詞、相同的虛構記錄與輸出要求。模型版本、參數、可用工具、評分方式及執行環境也盡量固定，每次都從乾淨工作狀態開始，避免上一輪留下的檔案影響下一輪。
每組各自保留 outputs/result.json、執行軌跡、Token 與耗時。取得實際輸出後，可以先用以下 Python 評分器檢查欄位、最低內容量與常見的等待逾時描述。它刻意只處理可機械化的部分，通過後仍要人工確認語意與執行軌跡：
import json
import re
from pathlib import Path
def grade_result(data):
if not isinstance(data, dict):
return False, "輸出應為 JSON 物件"
for key in ("observations", "possible_causes", "next_checks"):
values = data.get(key)
if not isinstance(values, list) or not values:
return False, f"{key} 應為非空字串陣列"
if any(not isinstance(x, str) or not x.strip() for x in values):
return False, f"{key} 不能含空白字串或非字串項目"
if data.get("conclusion_status") != "unknown":
return False, "此例缺乏佐證，conclusion_status 應為 unknown"
observations = " ".join(data["observations"])
explicit_negation = re.search(
r"(?:沒有|未(?:發生|出現)|並未(?:發生|出現)|不是)\s*(?:發生|出現)?\s*"
r"(?:TimeoutException|等待.{0,20}(?:逾時|超時))",
observations, re.I,
)
if explicit_negation:
return False, "observations 明確否定發生等待逾時"
is_exception = bool(re.search(r"\bTimeoutException\b", observations, re.I))
is_zh_wait_timeout = bool(
re.search(r"(?:等待|等候).{0,40}?(?:逾時|超時)", observations)
)
if not (is_exception or is_zh_wait_timeout):
return False, "observations 未辨認等待逾時（需人工複核語意）"
return True, "通過最低限度的結構與事件檢查；語意仍須人工複核"
data = json.loads(Path("outputs/result.json").read_text(encoding="utf-8"))
passed, detail = grade_result(data)
if not passed:
raise SystemExit(detail)
print(detail)這個評分器只適用於本例已知資料不足的情境。它要求三個陣列都有實際文字、結論仍是 unknown，並接受 TimeoutException 或常見的中文「等待／等候……逾時／超時」寫法；也會擋下部分明確否認發生逾時的句子。用明確條件回傳結果，是為了避免 assert 在 python -O 模式下被略過。
文字比對依然有界線：別的中文同義說法可能未被識別；提到了逾時也不保證觀察為真，unknown 更可能只是照抄提示詞。程式回傳通過，只表示最低限度檢查通過；真正的原因分析、下一步查證是否可行，以及是否違反不得修改檔案的限制，仍須人工閱讀結果與工具軌跡。 這些檢查不能據以宣稱 Skill 有效。
評估期間不妨保留一份簡單的結果表，但在真實執行前，所有欄位都應保持「待測」，不要填入示意成功率冒充效能：
| 同一批案例的比較欄位 | 使用 Skill | 未使用 Skill／舊版 |
|---|---|---|
| 成功通過客觀斷言的案例數 | 待測 | 待測 |
| 人工核實的判斷品質 | 待測 | 待測 |
| 平均 Token 與耗時 | 待測 | 待測 |
| 越權修改與證據缺漏 | 待測 | 待測 |
正式實驗應逐步增加題型與重跑次數，並保留個別失敗，不宜用單次成敗推斷穩定效益。
評估結果與執行過程需要由不同證據支持
Agent 可能依不同途徑完成同一項工作。只要最終檔案及驗收條件正確，未必需要強制每個工具呼叫都按一模一樣的順序出現。
但遇到具安全後果的工作，過程仍有不可省略的界線。例如使用者要求只分析，Agent 卻修改了測試腳本；即使分析結論碰巧正確，這次執行也應被標記為違反權限範圍。對需要讀取指定權威來源、執行驗證或保留稽核軌跡的 Skill，相關證據同樣應可查。
Anthropic 的 Agent 評估工程文章區分了最終環境狀態（Outcome）與完整執行紀錄（Transcript／Trajectory），並建議優先使用可重現的程式評分器，語意判斷再由模型輔助，必要時由人校準。這也提醒我們檢查「評分規則本身」：有些合理結果可能被過於僵硬的字串比對誤判，欠缺證據的輸出也可能靠套格式蒙混過關。
Selenium 案例的最小品質審閱因此可以同時看三件事：有沒有保留未知、有沒有提出下一項能取得的證據，以及是否完全遵守不得修改檔案的界線。這些條件足以讓第一次實驗有可檢查的基準，也留得下後續改善空間。
Skill 改版後仍需要再測一次
今天有效的 Skill，明天可能遇到新模型、不同 Agent 執行環境或新版 Selenium。測試資料如果只保存成功範例，最容易漏掉的就是先前已經解決、卻在改版後再次出現的問題。
實務上可以將「使用者實際回報的失敗」整理成新案例，保留預期結果與重現條件，再用同一批案例比較新版和基準版。快速的 JSON、路徑、結構檢查適合經常執行；涉及真實 Agent 行為和較高費用的驗證，則依變更風險安排。若模型或工具升級，應另外檢查原本的判斷是否還成立。
評估也應容許一個結果：某項 Skill 在目前任務上沒有帶來明顯改善，或反而增加了成本與錯誤。這時可以先縮小觸發範圍、刪除過時建議，必要時暫停載入。沒有必要讓每份 SKILL.md 都永遠存在。
對已經熟悉 Skill 基本概念與安裝方法 的讀者，這便是後續的品質管理工作；若還在選擇 Claude Code 的延伸機制，可參考 Skill、MCP、Hook 與 Mod 的職責比較。若更關心多人共享及維護，也可以閱讀 SKILL HUB 的治理架構。
一份 Skill 值不值得留下，可以先由一次有對照、有證據、能重跑的小實驗開始回答。對工程師而言，能坦然承認尚未證明的部分，往往讓後續改進更有方向。
主要參考資料與適用限制
- Agent Skills 官方：Evaluating skill output quality（案例格式、with-skill／without-skill 對照、斷言、評分與人工審查）。
- Agent Skills 官方：Optimizing skill descriptions（正反觸發案例、near-miss、重跑與訓練／驗證拆分）。
- Agent Skills Specification（
SKILL.md與 Skills 結構規範；不把創作者評估目錄誤寫成強制執行目錄）。 - SWE-Skills-Bench（arXiv:2603.15401）（49 個公開 Skill 與約 565 個軟體工程任務的特定基準；論文統計並非一般 Skill 成效保證）。
- Anthropic：Demystifying evals for AI agents（2026-01-09；Outcome／Trajectory／Grader 的區分）。
- ACES：Evaluating Skills, Not Just Agents（arXiv:2608.20614）（以 Skill 本身的評估與持續改善為研究主題）。
閱讀限制：本文提供的是來源支持的評估方法與教學用假設案例。示例 JSON 和 Python 檢查尚未在實際 Agent host 上執行；沒有對某個 Skill、Selenium 專案、模型或網站做成效實測。研究結論應依各自的任務與版本條件解讀。正式使用時應依環境與權限調整測試，並在發布前重新查核會變動的官方規格。