Agent Skills 實戰課程

Appearance

秘笈 S2：什麼是好的 Skill？SKILL.md 結構一次看懂 ​

上一章看完，你大概知道 Skill 是什麼了。

但你打開一個開源 Skill 來看，還是會冒出一個問題：為什麼有些 Skill 超好用，有些裝了等於沒裝？

我拿 S1 提到的那批開源技能來翻，翻了幾十個之後發現，差別不在功能多強，在寫法。

爛的 Skill 都長一個樣：描述含糊，步驟跳躍，還假設你什麼都會。好的 Skill 剛好相反。

這篇把好的 Skill 長什麼樣子，一次講完。看到最後有一個完整範本，直接複製就能開工。

先看一個爛例子 ​

我隨手改一個真實看過的爛寫法（有美化過，但毛病都保留）：

md
---
name: post-helper
description: 幫助發布貼文
---

# 發文小幫手

幫我發文。先準備內容，然後發布。

你看出問題了嗎？

Agent 看到這個，跟你看到「幫我發文」四個字是一樣的反應：然後呢？發去哪？格式是什麼？要不要先確認？

爛 Skill 的共同點：把最需要講清楚的地方全部跳過。

[IMAGE: 左右對比圖，左邊是含糊的 Skill 範例，右邊是具體的 Skill 範例，標出差異處]

好的 Skill 有三個味道 ​

我翻完幾十個 Skill 之後，好的都有這三個味道：

第一，一看就知道什麼時候用。不是寫給人看的心情小語，是寫給 Agent 掃描用的觸發條件。

第二，步驟具體到不用猜。每一步說做什麼、用什麼、做完長什麼樣。

第三，把坑先寫出來。哪些地方一定會錯，先寫。不要等 Agent 錯了再說。

記住這三個，後面看結構就很好懂。

SKILL.md 的長相：一個資料夾，一份檔案 ​

my-skill/
├── SKILL.md          # 唯一必要檔案
├── scripts/          # 選用：可執行程式碼
├── references/       # 選用：參考文件
└── assets/           # 選用：靜態資源

真正決定成敗的，是 SKILL.md 裡面的三塊：開頭的身分證（frontmatter）、中間的做事流程（Instructions）、用到的目錄。

一塊一塊看。

身分證怎麼寫？五個欄位，兩個必填 ​

frontmatter 夾在上下兩條 --- 之間，YAML 格式。總共五個欄位，必填的只有兩個：

欄位必填？在幹嘛限制
name要技能名稱，Agent 拿來當 ID最長 64 字元
description要什麼時候觸發這個技能最長 1024 字元
license不用授權條款無
compatibility不用環境需求無
metadata不用作者、版本等自訂資訊無

另外有一個實驗性的 allowed-tools（工具白名單），目前只有少數平台支援，先不用管它。

順帶一提 license。很多人想說我的技能又不賣錢，寫這個幹嘛。但開源社群會直接複製你的技能，你沒寫 license，法律上就是保留所有權利，反而擋了散佈。寫個 MIT 就好，一行字的事。

[IMAGE: 五個欄位的視覺化比較圖，必填跟選填分兩區，像行李箱只裝必需品]

name 怎麼取才對？ ​

規則一句話講完：只准小寫字母、數字、連字號，不能連續兩個連字號，不能開頭或結尾放連字號。

對的長這樣：

  • pdf-processing
  • data-analysis-v2
  • code-review

錯的長這樣：

  • PDF-Processing（大寫不行）
  • -pdf（開頭連字號不行）
  • pdf--processing（連續連字號不行）
  • data_analysis（底線不行）

為什麼管這麼嚴？因為 name 會被拿去當檔案路徑、當唯一識別碼、當跨平台的技能 ID。大寫在某些檔案系統會出事，底線在 URL 會被編碼，連續連字號會讓解析器 confused。

取 name 的心態：把它當身分證字號，不是當標題。取完就別改了。

description 是整份檔案最重要的欄位 ​

不是因為它最長，是因為只有它能決定 Agent 會不會載入你的技能。

機制是這樣：Agent 自己判斷當下情境符不符合某個技能的 description。符合才載入。不符合，你寫得再好它也不看。

這裡有個實務上的麻煩：Agent 偏向不觸發。它會低估自己需不需要幫忙。

你寫「Helps with PDFs」，Agent 心裡想的是「PDF 而已，我自己來就行」。然後它就自己硬幹，幹錯了你還不知道為什麼。

所以 description 要寫得具體，而且要 pushy一點。看個對比：

yaml
# 爛的
description: Helps with PDF files.
yaml
# 好的
description: |
  Extract text and tables from PDF files. Use when the user
  provides a PDF document or asks you to read/analyze a PDF.
  This skill handles page parsing, table detection, and
  text extraction with proper encoding.

好的版本做了三件事：講清楚什麼時候用（user provides a PDF），講清楚做什麼（extract text and tables），還暗示不用就虧了（parsing、detection、encoding 這些 Agent 自己做不來）。

我寫 description 用的句型，跟前面三個味道是同一套：做什麼事，加上哪幾個步驟，加上什麼時候觸發。動詞開頭，場景結尾。

20 筆測試法 ​

寫完不要憑感覺。官方建議的做法是準備 20 筆測試：

  • 10 筆應該觸發的，比如「幫我讀這個 PDF」
  • 10 筆不該觸發的，比如「幫我找餐廳」

每筆跑 3 次算觸發率，超過一半才算過。用六成當訓練、四成當驗證，避免自己騙自己。

聽起來麻煩，其實十分鐘就做完了。做完你對這份 description 的信心完全不一樣。

目錄：什麼東西放哪裡 ​

最低需求就一個檔案，SKILL.md 自己就能跑。但實戰通常會長成四個角色：

my-skill/
├── SKILL.md          # 唯一必要
├── scripts/          # 可執行的程式，比如 Python、Shell
├── references/       # 查資料用的參考文件
└── assets/           # 靜態資源，比如圖片跟模板

什麼時候用哪個，看情境：

做 CSV 分析的技能，附一支 Python 畫圖腳本，放 scripts/。寫 API 文件的技能，附一份 OpenAPI 範例，放 references/。生成圖表的技能，附空白模板，放 assets/。

重點只有一個：這些都是需要時才載入。Agent 讀完 SKILL.md，發現裡面說要跑腳本，才去拿。平常不佔 context。SKILL.md 只寫流程，重的東西全部丟目錄。

本文怎麼寫，Agent 才會照做？ ​

frontmatter 只是身分證，真正的專業在 --- 之後。這裡沒有強制格式，但社群踩坑踩出幾條鐵律：

步驟化，不要描述化 ​

爛的寫法是宣告：

markdown
This skill handles PDF extraction. It uses PyMuPDF for text
extraction and Camelot for table detection.

好的寫法是程序：

markdown
## Steps

1. Check if the file is a valid PDF by reading its header
2. Use PyMuPDF to extract text page by page
3. If the user asked for tables, use Camelot to detect them
4. Return structured output with text and tables separate

Agent 本質上是逐步推理的機器。你給步驟，它照走。你給描述，它要自己拆，拆錯的機率很高。

清單比段落可靠 ​

一串發布前檢查事項，用 checklist 寫：

markdown
## Release Checklist

- [ ] Version bumped in pyproject.toml
- [ ] CHANGELOG.md updated
- [ ] All tests pass
- [ ] Security audit complete

Agent 看到格子會一格一格打勾。寫成段落，它看完就忘了。

Gotchas 是整份文件最值錢的部分 ​

gotchas 就是那些藏在文件角落、新手一定踩、老手懶得講的事：

markdown
## Gotchas

- 使用者 ID 在 production DB 叫 `user_id`，
  但在 analytics DB 叫 `uid`。查資料兩個都要試。
- `/health` 只檢查 DB 連線，不代表服務正常。
  要完整健檢請 call `/ready`。

Agent 不會問，因為它不知道自己不知道。你先寫進去，它直接避開。這種資訊外面找不到，是你獨家的價值。

要模板，不要只給範例 ​

希望 Agent 照固定格式輸出，直接給它空模板：

markdown
## Output Format

Return a JSON object with this structure:

```json
{
  "title": "...",
  "confidence": 0.0-1.0,
  "sources": ["..."],
  "summary": "..."
}

看到模板，Agent 照填。看到範例，它用模仿的，結構容易跑掉。

我有個檢查法：遮住標題只看內文，還知道在教什麼嗎？不知道就是寫太鬆了。

---

## 三層揭露：為什麼這樣設計剛好

S1 提過 Progressive Disclosure，這裡複習一次，因為你現在看得懂它為什麼長這樣了：

你下一句話 ↓ Agent 掃描所有 Skill 的 description（Level 1） 找到符合的 ↓ 載入完整 SKILL.md（Level 2） 照步驟執行 ↓ 需要範本或腳本時 去 assets/、scripts/ 拿（Level 3）


| 層級 | 什麼時候載入 | 內容 | 花多少 tokens |
|------|--------------|------|---------------|
| Level 1 | 永遠載入 | `name` 加 `description` | 約 100 |
| Level 2 | 觸發才載入 | SKILL.md 本文 | 5000 以內 |
| Level 3 | 需要才載入 | 腳本、參考文件、資源 | 看檔案大小 |

為什麼這樣設計很聰明？因為 Agent 的記憶體有限。一百個技能全載入直接塞爆，但只載入目錄卡的話，幾百個也沒感覺。像圖書館的目錄卡跟書的差別：卡可以排幾萬張，但你一次只借一兩本。

[IMAGE: 三層金字塔圖，Level 1 小圓在外層，Level 3 大圓在內層，標出 token 成本]

---

## 完整範本：直接複製開工

前面講的全壓在這一個範本裡。開新 Skill 就從這裡改：

```markdown
---
name: your-skill-name
description: |
  One paragraph describing what this skill does.
  A second paragraph describing when to trigger it.
  Be specific. Be pushy.
license: MIT
compatibility:
  - platform: opencode
  - platform: claude-code
metadata:
  author: your-name
  version: 1.0.0
---

## Overview

Brief one-sentence summary of what this skill achieves.

## Prerequisites

- [ ] Dependency A installed
- [ ] Environment variable B set
- [ ] User has access to C

## Steps

1. First step, be specific
2. Second step, include commands if applicable
3. Third step, check for success criteria

## Output

Description of what the result looks like.
Include a template if output has a fixed format.

## Gotchas

- Thing that will go wrong if you don't handle it
- Edge case that the agent wouldn't think to check

## Verification

- [ ] Run this command to verify success
- [ ] Check that output contains expected value

不要一開始就寫很長。先讓它能跑，跑一次看 Agent 在哪一步用猜的，猜錯的地方就是你要補坑的地方。

說說我的感受 ​

我剛碰 SKILL.md 的時候，第一反應是就這樣？一個 markdown 檔案，沒有 DSL，沒有 SDK，沒有 registry。

我已經習慣寫東西要學一堆工具。寫 React 要學 JSX 跟一堆周邊，寫 VS Code 套件要學一堆 API。然後 Agent Skills 跟你說寫個 markdown 就好。

後來想通了，這不是技術創新，是認知翻轉。以前是讓電腦懂人意，所以要嚴格語法。現在是讓 AI 懂人意，而 AI 最會讀的就是 markdown。最強的格式，就是 AI 本來就懂的東西。

反過來說，大部分人寫爛也不是技術問題，是寫的時候假設讀的人什麼都懂。Agent 剛好什麼都不懂，還很會裝懂。你寫得鬆，它就用猜的，猜十次錯七次，你就覺得 Agent 很笨。

你寫得越囉嗦具體，它越穩。這跟帶新人一模一樣。你踩過的坑，變成它的步驟。這才剛開始。

今天就試 ​

  1. 找一個你每週都在做的重複任務
  2. 用上面的範本開一個 SKILL.md，先寫 20 行就好
  3. 丟給 Agent 跑一次，看它在哪一步猜錯
  4. 猜錯的地方，就是你要補坑的地方

下一篇：S3 — description 怎麼寫才會被觸發

下一篇把 description 觸發機制單獨拉出來深挖。同一份 Skill，換一句描述，觸發率可以差三倍。我拿幾個真實例子給你看。

這篇文章是「Agent Skills 極速學習秘笈」系列的一部分。全部內容免費公開。

← 上一篇: S1: Agent Skills 是什麼？ | 下一篇: S3: Description 觸發優化 →

免費公開教學資源 · 繁體中文 Agent Skills 課程

Copyright © 2026 Leo Laboratory