Agent Skills 實作課：一份 SKILL.md，寫一次、到處跑

前言

給 Agent「能力」有三種方式，解決的是三個不同的問題（如圖二下半）：

System prompt：每次對話都載入，管的是行為、語氣、人設。
MCP：呼叫外部程式，解決的是「連接外部系統與資料」。
Skill：按需載入，解決的是「怎麼做某件事」的 know-how。

MCP 讓 Agent 摸得到工具，Skill 告訴它拿起工具時該照什麼手順做。Anthropic 在 2025 年 10 月於 Claude 產品線推出 Agent Skills，同年 12 月把格式釋出為開放標準（agentskills.io），規範並捐給 Linux 基金會旗下的 Agentic AI Foundation，避免被單一廠商鎖定。同一份 SKILL.md，如今可在 Claude Code、OpenAI Codex、Cursor、Gemini CLI、GitHub Copilot 等 40 多種工具上直接使用（如圖二右半）——寫一次，到處跑。

為什麼是現在？因為 context 變成了 Agent 時代最貴的資源。模型視窗越來越大，但「塞滿」不等於「好用」：注意力會稀釋，帳單會膨脹。Skill 把「能力」從 prompt 裡抽出來，變成可版本控制、可審查、可共用的檔案——這正是它從一個產品功能長成開放標準的原因。

一、Skill 到底是什麼：一個資料夾（如圖二）

一個 skill 就是一個資料夾。唯一必填的是 SKILL.md（name＋description＋做法說明），其餘都是選填、按需載入（如圖二左半）：

my-skill/
├── SKILL.md        ← 必填：name + description + 做法說明
├── examples/       ← 選填：參考輸出範例
├── references/     ← 選填：長文件（規範、風格指南）
├── scripts/       ← 選填：可執行的小腳本
└── assets/         ← 選填：模板、圖片等素材

沒有 SDK、沒有註冊中心、沒有廠商鎖定——就是一個模型讀得懂的資料夾。

二、漸進揭露：context 按需付費（如圖一）

Skill 的核心設計原則是 progressive disclosure（漸進揭露）：context 分三層載入（如圖一）：

Level 1——元資料：每個 skill 的 name＋description，一開機就載入。一個 skill 約 30–50 個 token，數百個也只佔一小塊。這是 Agent 決定「要不要用這個 skill」的唯一依據。
Level 2——SKILL.md 全文：任務命中 description 才讀進來。沒被觸發的 skill，一個字都不佔。官方建議全文控制在 500 行、5,000 token 以內。
Level 3——參考檔／腳本：references/、scripts/、examples/ 裡的檔案，需要時才按路徑讀。執行到哪一步，才付那一段的 context 錢。腳本甚至可以直接執行，原始碼不必進 context。

對比很殘酷：100 個 skill 全塞進去，視窗直接少一半；漸進揭露下，只付 Level 1 清單加上命中的那一個。實測數字：50 個 skill 在啟動時只花約 1,500–2,500 token，而一個 5 伺服器、58 工具的 MCP 配置就要吃掉約 55,000 token。2026 年 2 月一份分析 40,285 個公開 skill 的學術研究發現，中位數 skill 本體只有 1,414 token，90% 不到 3,935 token——skill 天生就是小而專的知識單元。

三、寫一份好的 SKILL.md：description 是觸發器

SKILL.md 的 frontmatter 只有兩個必填欄位：name（1–64 字元，小寫加連字號，必須跟資料夾同名）和 description（最多 1,024 字元）。選填的有 license、compatibility、metadata，以及實驗性的 allowed-tools（可限制 skill 啟用時的可用工具，適合唯讀或安全敏感流程）。

description 是整份 skill 最重要的幾行——它是 Agent 決定要不要載入的觸發器。好寫法要回答兩個問題：這個 skill 做什麼？什麼時候該用它？並且用使用者實際會講的關鍵字來寫。對比一下：

壞寫法：description: 處理發票相關任務——太籠統，Agent 無從判斷何時觸發。
好寫法：description: Reconcile vendor invoices against purchase orders… Use when the user asks to match, audit, or explain invoice discrepancies, or mentions PO numbers and invoice totals.——做了什麼、什麼關鍵字會觸發，一目了然。

例如：

---
name: invoice-reconciliation
description: Reconcile vendor invoices against purchase orders in the
  Northwind ERP export. Use when the user asks to match, audit, or explain
  invoice discrepancies, or mentions PO numbers and invoice totals.
---

三個實作要點：

1. SKILL.md 保持苗條：超過 500 行就該拆。長文件搬到 references/，模板搬到 assets/，helper 搬到 scripts/。一份 200 行的 SKILL.md 加上按需載入的 1,500 行參考文件，遠勝一份每次都被全載入的 2,000 行 SKILL.md。 2. 告訴 Agent「何時」載入檔案，而不只是「有」檔案：寫「API 回傳非 2xx 時讀 references/error-codes.md，裡面有每種錯誤碼的恢復流程」，不要只寫「詳見 references/」——太模糊，觸發不了。 3. 一個 skill 只解決一件事：55% 的公開 skill 集中在軟體工程工作流，但規範鼓勵一個 skill 一個關注點。另一個冷知識：46% 的公開 skill 跟別人撞名，命名時值得多想一下。

四、最小可運行範例

---
name: csv-to-table
description: Turn comma-separated text into a Markdown table. Use when the
  input looks like CSV and the user asks for a table.
---

# CSV to Table

## Instructions
Split the input on newlines into rows, then on commas into columns. Render
the first row as the header, add a `---` separator row, and format every
row as `| a | b | c |`.

存成 csv-to-table/SKILL.md，丟進任一支援的工具的 skills 目錄，就能用。更進階的玩法：讓 Agent 自己寫 skill——先硬幹解一次任務，把手順存成真正的 SKILL.md，下次直接重用；有實測把後續同類任務的工作量砍掉近一半。

五、生態與提醒：開放標準不代表零風險

開放標準的威力在生態：2026 年 1 月中到 2 月初短短 20 天，公開 skill 數量從 2,179 暴增到 4 萬以上（18.5 倍）；到 2026 年 5 月，同一份 SKILL.md 已可在 26 個以上平台不經修改直接運行。Anthropic 把規範捐給 Linux 基金會旗下的 Agentic AI Foundation（AAIF）是關鍵一步：標準的中立治理讓各家工具敢投入，避免「今天相容、明天分叉」的平台風險。但同一份研究也提醒：約 40% 的公開 skill 會接觸敏感上下文或執行寫入操作，9% 屬於高風險類別。skill 是「可執行的知識」，裝第三方 skill 之前先讀過 SKILL.md 全文，是基本衛生。

結論

System prompt 管人設、MCP 接資料、Skill 教手順——三層各司其職。Skill 的殺手鐧不是格式簡單，而是漸進揭露讓「裝一百個能力」變得便宜：啟動時只付一份清單的錢，用到哪個才展開哪個。寫 skill 時記住一句話：description 寫給觸發器看，SKILL.md 寫給執行者看，references 寫給疑難排解看——三層各就各位，context 自然不浪費。

來源

Anthropic 工程部落格：〈Equipping agents for the real world with Agent Skills〉（漸進揭露設計原則）
agentskills.io：Agent Skills 開放標準規範（frontmatter 欄位、500 行／5,000 token 建議）
Agent Engineering Curriculum：〈Context Engineering II — Retrieval, Isolation, Progressive Disclosure〉（三層揭露規格表）
insights-trail 2026-05-19 briefing：40,285 個公開 skill 的生態統計（18.5 倍成長、中位數 1,414 token、40% 接觸敏感上下文）
aiwiki.ai：Claude Skills 條目（2025-10-16 發佈、2025-12-18 開放標準、Simon Willison 評論）
dev.to：〈Agents Are Learning to Write Their Own SKILL.md Files〉（Agent 自寫 skill 實測）

Dylan House