昨日回顧

Day 1 談了為什麼 agent 需要 skill：把「怎麼做好一件事」的知識打包，寫一次、重複用、可驗證。今天打開 skill 的核心檔案 SKILL.md，一行一行看它怎麼運作。

一支 skill 的目錄結構

一支 skill 最小的樣子只有一個檔案：

my-skill/
  SKILL.md

實務上會長成這樣：

ticket-guard/
  SKILL.md          # 核心：frontmatter + 指令本文
  references/
    sources.md      # 官方售票來源清單（需要時才讀）
    fraud-patterns.md
  scripts/
    check_domain.py # 確定性檢查腳本

原則很簡單：SKILL.md 是永遠會被讀的部分，其他檔案是「用到的時候」才被讀的部分。

Frontmatter：skill 的門面

SKILL.md 開頭是一段 YAML frontmatter：

---
name: ticket-guard
description: 檢查演唱會售票連結是否來自官方管道。當使用者貼上售票網址、詢問購票連結真偽、或提到票務詐騙時使用。
---

兩個必填欄位：

1. name：skill 的唯一識別。小寫、連字號、一眼看得懂。
2. description：這是最重要的三行。agent 判斷「現在要不要用這支 skill」的唯一依據就是這段文字。

寫 description 的三個訣竅：

1. 寫「做什麼」也寫「什麼時候用」：上面例子的前半句是功能，後半句是觸發時機。只寫功能，agent 不知道何時該啟動；只寫時機，agent 不知道它能幹嘛。
2. 放關鍵字：使用者會怎麼講這件事，就把那些詞放進去（「售票連結」、「票務詐騙」）。觸發是語意比對，詞彙覆蓋越貼近真實問法越準。
3. 別貪心：description 什麼都包，等於什麼都觸發。邊界清楚的 skill 才不會在不該出現的時候跳出來。

指令分層：漸進式揭露的實作

昨天提到 progressive disclosure，今天看它在檔案層面怎麼實現。一支 skill 的資訊分三層：

第一層：metadata（永遠在 context）

就是 frontmatter 那幾行。不管你裝了 5 支還 50 支 skill，常駐成本都只有這些。

第二層：SKILL.md 本文（觸發時載入）

使用者意圖命中 description，agent 才把整份 SKILL.md 讀進來。這裡寫執行流程、護欄、輸出格式：

# 演唱會購票安全檢查

## 流程
1. 取出使用者提供的網址域名
2. 執行 scripts/check_domain.py 比對官方清單
3. 命中：回報官方管道；未命中：查 references/fraud-patterns.md 比對常見詐騙特徵
4. 都不確定：明確說「無法確認」，不要猜

## 護欄
- 域名比對只用腳本，不靠印象
- 不推薦任何非官方購票管道

第三層：references/ 與 scripts/（按需載入）

清單會更新、詐騙話術會演化，這些厚重又常變的內容放在獨立檔案。SKILL.md 只告訴 agent「什麼情況去讀哪個檔案」，agent 真的走到那一步才打開。

為什麼要分層？因為 context 是最貴的資源。全部塞一層，每次觸發都載入幾千字，token 成本和干擾都上去；分層之後，簡單問題在第二層就解決，只有複雜案例才碰到第三層。

新手最常見的三個錯

1. description 寫成文案：「一個很棒的購票小幫手！」agent 看完還是不知道什麼時候該用它。
2. 本文寫成百科：把所有知識倒進 SKILL.md，忘了第三層的存在。
3. 指令給感受不給判斷：「要小心詐騙」是感受；「命中官方清單以外的域名就標記為未確認」才是判斷。

明天預告

Day 3 回答一個每個人都會卡住的問題：同樣一件事，該寫成 prompt、skill、subagent 還是接 MCP？給你一張可以直接套用的選型表。