如何寫出工業級的 Agent Skill？漸進式披露與嚴格測試 (Industrial-Grade Skills)

原始來源與檔名：20260512_2026-05-05T094014+0800-如何写出工业级 Skill.md

來源：[[@FakeMaidenMaker]] / X (Twitter) — 2026-05-04 原始檔名：2026-05-05T094014+0800-如何写出工业级 Skill.md

NAPKIN | 餐巾紙

餐巾紙公式

Bad Skill = Huge MD File (Rules + Context + Examples combined). Good Skill = Trigger Optimization + Principle of Least Privilege + Model Matching + Progressive Disclosure + Evals. Progressive Disclosure = SKILL.md (Index) + references/ (Docs) + scripts/ (Code) + assets/ (Templates).

很多人把 Agent Skill 當成一個巨大的 Prompt 檔案，把背景、規則、案例全塞進去，結果 Agent 載入緩慢且常常出錯。這篇文章定義了什麼是「工業級的 Skill」。核心理念在於「按需加載 (On-demand)」與「漸進式披露 (Progressive Disclosure)」：SKILL.md 只做路由入口，長篇參考資料和確定性的程式碼腳本應該拆分到獨立的目錄中。更重要的是，一個好的 Skill 必須經歷嚴格的 Evals (測試資料打分驗證)，才能保證它在真實工作流中穩定運作。

一句話

如果你只把 Prompt 寫長，那不叫 Skill。這是一篇 Agent Skill 的架構設計指南。作者指出，Skill 真正的價值在於固化經驗，確保 Agent 能在特定場景下穩定觸發並執行標準流程。文章提出了五大原則：1) 優化 Description 以確保正確觸發；2) 嚴格限制工具權限 (最小權限原則)；3) 依任務難度匹配不同模型；4) 採用目錄結構將長文件拆離 SKILL.md；5) 建立測試資料集 (Evals)，進行 A/B 對比評分，用數據證明 Skill 真的有效。

餐巾紙草圖

[ Progressive Disclosure in Skills ]

WRONG:
.claude/skills/cover_image.md (3000 lines of rules, examples, and python code) -> Crash / Slow.

RIGHT:
.claude/skills/cover_image/
  ├── SKILL.md      (Entry point, < 500 lines)
  ├── references/   (Design rules, platform sizes) -> Read only when needed
  ├── scripts/      (resize.py) -> Executed deterministically
  └── assets/       (Templates, fonts)

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

• 定義: Skill 介於全域的 CLAUDE.md 與手動的 Slash Command 之間。它的靈魂是「按需加載 (On-demand loading)」。
• 原則一：觸發器設計: description 決定了 Skill 會不會被呼叫。不能只寫 “Create an image”，必須寫滿使用者真實的情境關鍵字（長推、海報、配圖）。低頻 Skill 應設為 disable，改為手動呼叫以節省 Context。
• 原則二：權限邊界: 遵循最小權限原則 (allowed-tools)。讀取分析用的 Skill 就不該有 Edit 或 Bash 權限。
• 原則三：匹配模型: 不同任務用不同模型。寫文檔用高階寫作模型，資料爬取用便宜快速的模型。不要全預設用同一個。
• 原則四：漸進式披露 (Progressive Disclosure): SKILL.md 應少於 500 行，只放觸發時機、原則和步驟。細節必須分拆：
  • references/: 長文檔、風格案例。
  • scripts/: 確定性的邏輯（如尺寸檢查）寫成 Python 腳本讓 Agent 跑，不要讓 LLM 每次重新思考。
  • assets/: 模板、Schema。
• 原則五：Evals (驗證與迭代):
  • 跑通測試 (路徑對不對？)
  • 觸發測試 (說人話時會觸發嗎？)
  • 結果打分 (0-10 分，準備 Test Data 進行 Baseline 對比)。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

1. 確定性邏輯不該交給 LLM: 文章中提到把尺寸檢查等操作放入 scripts/ 目錄。這是非常深刻的架構洞見。LLM 的本質是機率模型，讓機率模型去處理 100% 確定性的邏輯（如裁切圖片、正規表達式替換）是浪費且危險的。工業級 Agent 必須是「大腦 (LLM) + 肌肉 (Scripts)」的結合。
2. 沒有 Eval 就沒有工程化: 作者嚴厲批評了「憑感覺發布 Skill」的行為。就像傳統軟體沒有單元測試不能上線一樣，Skill 如果不能在 10 個測試案例中穩定拿到 7 分以上，並且證明比 Baseline (不開 Skill) 更優秀，那它就只是一段虛榮的字串，沒有提供真實價值。

關鍵證據

• 提供了一套完整的目錄結構範例 (cover_image/)，清晰展示了如何將龐大的 Prompt 拆解為 Markdown 導覽頁與具體資源檔。
• 提供了一套 0-10 分的評估標準與 A/B 基準測試流程，讓 Agent 的「玄學」開發轉變為可量化的科學流程。

邊界條件

• 對於極度靈活、探索性質極強的任務（例如頭腦風暴、開放式架構設計），強行套用這套嚴格的 Eval 與腳本約束，可能會扼殺 LLM 本身的發散創造力。這套方法論最適用於「流程明確但過程繁瑣」的流水線任務。

ROUND 3: SOUL | 靈魂提取

“還能怎么用”

• 知識連結: 本文完美收束了前兩篇的痛點：《Claude Skills 實戰指南》教你怎麼建 Skill，《優化 7 個 Token 陷阱》告訴你亂建 Skill 會爆炸。這篇則給出了解藥：透過「漸進式披露」架構，讓 Skill 既具備強大的知識庫，又不會在初次載入時把 Token 撐爆。
• 深層洞見: “Skill 并不只是单纯把提示词写长保存下来。它是把经验固化成一个可触发、可执行、可测试、可维护的工作流。” 這是所有 Prompt Engineer 必須跨越的門檻：從寫提示詞，升級為設計工作流引擎。
• 行動呼籲: 檢視你最常用的一個 Prompt 或 Skill。試著把裡面「超過 10 行的案例或模板」抽離出來，存成同目錄下的一個文字檔。然後在你的 Skill 裡寫上：「執行前，請先讀取 assets/template.txt」。你的 Agent 將會瞬間變得更輕快、更穩定。