用 Progressive Disclosure 設計 Agent Skills：skill.md Best Practices 與可落地的 Eval 方法

用 progressive disclosure 設計 Agent Skills，把 SKILL.md 的 description 寫到能唯一對應 user intent，再用聚焦在「挑選」的 eval 驗證選對率。

Agent Skills（由 Anthropic 在 2025 年為 Claude Code 與 Claude 應用推出）與 OpenAI Assistants 的「tools」、Semantic Kernel 的「skills」並不相同。Anthropic 在 2025 年 10 月 16 日正式發表 Agent Skills，SKILL.md 就是模型最先讀到的檔案。(Anthropic)

做 agent skills（或 tools/commands）時，多數人把重點放在「功能能跑」。實際上決定體感與穩定度的，通常是：

agent 會不會選到正確的 skill（selection accuracy）
被選中後 能不能照規則執行（execution reliability）
skills 變多後 誤選/誤觸是否快速上升（confusability）

這裡分享一套工程化做法：用 progressive disclosure（漸進式揭露） 設計 skill 結構（特別是 SKILL.md），並用簡單但有效的 eval 驗證「哪個版本更準」。想看 skills 在整個 agent 架構中的位置，可參考我們的 Agent 設計概述。

1) Progressive Disclosure：為什麼它是 skill 設計的核心原則？

Progressive disclosure 的精神是： 先顯示必要資訊，把進階或較少用的資訊延後到需要時再揭露。這能降低學習成本與錯誤率。(Nielsen Norman Group)

把它套到 agent skills，會自然形成三層載入：

Discovery：只讀 name + description（判斷「可能相關」）
Activation：決定用這個 skill 才讀 SKILL.md（載入規則、限制、流程）
Execution：照 SKILL.md 指示跑腳本/工具，必要時讀更多檔案

這種「像手冊一樣」的分層載入，就是 skills 系統用來擴展、節省 token 的設計原則。Anthropic 工程團隊直接點明：「Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable.」(Anthropic)

2) Discovery 階段的真相：它更像 pattern matching，而不是完整理解

很多人以為 agent 選 skill 時會細讀全文、深度理解；但實際上不少 agent 框架的設計裡，skill 的「入口訊號」就是 description，它應該像目錄或索引：先幫模型判斷要不要深入讀。(Claude)

所以 description 的目標很單純：提高「選對」的機率，不是把執行細節塞進去。Anthropic 工程文也把「只在需要時載入更多上下文」當作 skills 能擴展的關鍵。(Anthropic)

3) skill.md Best Practices：把 SKILL.md 當作「Agent 可執行的 API 文件」

3.1 Description（Discovery）寫法：一句話要同時回答三件事

一行好的 description 要能回答：

我做什麼（清楚動詞 + 明確物件）
什麼情境用（常見 user intent）
有沒有硬限制（例如 read-only）

推薦模板：

<Verb> <object>. Use when <specific user intent>. <critical constraint>.

這也呼應 Anthropic 把 SKILL.md 定位成 overview、像 table of contents 引導模型讀詳細材料的做法：入口先準，細節後載入。(Claude)

3.2 SKILL.md 結構（Activation）建議：先行為邊界，再執行路徑

一個對 agent 友善、降低誤觸的 SKILL.md，建議章節順序如下：

Role definition（你是什麼、你的任務是什麼；1–2 句）
Capabilities（能做什麼）
Safety & Constraints（不能做什麼；用強語氣）
Execution method（怎麼跑：腳本/命令入口）
Usage examples（典型命令）
Arguments & defaults（參數解析與預設）
Workflow（Parse → Resolve defaults → Execute → Present output）

官方文件也建議用「progressive disclosure patterns」把 overview 跟詳細材料拆開，並給出 SKILL.md 的實作建議（內容變大就拆檔、保持 overview 精簡）。(Claude)

3.3 Constraints 的寫法：用「絕對語氣」避免模型把它當建議

如果是安全邊界或操作邊界，請用：

✅ You may only ...
✅ Never ...

而不是：

❌ You should not ...
❌ Please avoid ...

agent 多半是「掃描式」讀 instruction，強語氣更能形成穩定的行為約束（尤其是 read-only、no secrets 這類）。(Claude)

4) Eval：怎麼知道哪個版本更準？

沒有理論答案，只能用 eval 驗證。 而且你要分清楚你在驗證的「準」是哪一種：

Selection accuracy：該不該選到這個 skill？
Execution correctness：選到了之後是否照規則執行且結果正確？

OpenAI 的 eval 指南把 tool selection 本身就當成一類需要測的能力，不是只測輸出文字。(OpenAI Platform)

4.1 最便宜、最有效：Activation test（小測試集）

做法：

準備 10–30 條 user intents
每條標註「預期要選哪個 skill」（或預期不該選任何 skill）
用同一個 agent 設定，比較不同版本 description 的 precision/recall

這跟 OpenAI eval 指南講的一樣：把你在意的行為變成可重複的測試，避免升級或改 prompt 後悄悄退化。(OpenAI Platform)

4.2 Confusable skills 測試（技能一多就必做）

當你有多個相近技能（例如都跟 ADO 有關），測試集要刻意放入容易混淆的句子，例如：

“status / latest / monitor / details / history”
“find a run id”
“show last failed run”

目標是把「容易撞詞」的 intent 拆開驗證：是不是能穩定選到你預期的那個 skill。

OpenAI 的 eval 文件與 cookbook 範例把這類測試歸在 deterministic / behavior-oriented 的檢查（例如工具選擇、參數有效性）。(OpenAI Developers)

5) 建議的迭代流程：用 eval 驅動 skill 文檔演進

你可以把 skill 文檔當成「產品介面」，用一個很工程化的 loop：

寫 description + SKILL.md
跑 activation test（selection eval）
對照誤選案例，調整用詞與限制條款（讓 skills 互斥更清楚）
每次新增 skill、或大改 description，都回歸跑一次

OpenAI 的 eval 指南把這種「為了升級與迭代而做的回歸測試」當成建置可靠 LLM 應用的核心。(OpenAI Platform)

結語

Skill 功能很容易做出來，難的是長期維護時 能不能被正確選中、以及 被選中後能不能穩定遵守規則。

用 progressive disclosure 把入口訊號（description）跟執行規格（SKILL.md）分層，再用 selection-focused 的 eval 把「選 skill」這件事測起來，skill 庫就能越長越穩，不會因為新增功能而整體誤觸率飆升。(Anthropic)