03 · 一個 Skill 的解剖
一個 Skill 分三層：① 觸發描述（很小，一直在）、② 正文說明書（被觸發時才讀）、③ 附件（用到才讀）。這個"用多少讀多少"的設計有個名字叫漸進式披露，它是 Skill 能存在的前提。
為什麼必須分層
回到上下文視窗那張桌子：桌面就那麼大。
如果每個 Skill 的全文都常駐，你裝五個就把桌子佔滿了，正事沒地方擺。所以設計成這樣：
| 層 | 什麼時候進上下文 | 大小 | 裝什麼 |
|---|---|---|---|
| ① 觸發描述 | 一直在（開機就載入） | 極小，一兩句話 | 名字 + 一句"我是幹嘛的、什麼時候用我" |
| ② 正文 | 被觸發時才讀 | 建議控制在幾頁之內 | 流程、規矩、模板、示例 |
| ③ 附件 | 正文提到、且真的需要時才讀 | 不限 | 參考資料、長模板、腳本 |
結果就是：你可以裝幾十個 Skill，平時的代價只是幾十行說明文字。
這個設計對你寫作的直接影響
每一層的"讀者"不同，寫法也不同：
- 第 ① 層是寫給"要不要用你"這個判斷看的 → 關鍵詞要全，要說清適用場景。
- 第 ② 層是寫給"已經決定用你了，接下來怎麼做"看的 → 只寫它不知道的，別科普。
- 第 ③ 層是寫給"需要查某個細節"看的 → 可以長，但要好檢索。
第 ① 層：觸發描述
以最標準化的那種形式為例，它是檔案開頭 --- 之間的兩個欄位：
---
name: meeting-notes
description: 把零散的会议记录整理成结构化纪要，输出结论、带责任人的待办、
遗留问题三块。当用户提供会议记录、会议纪要草稿、会议录音转写稿，
或要求整理纪要、提取会议待办时使用。
---name 是標識，description 是判斷依據。這一格最關鍵，也最多人寫壞，下一章整章講它。
常見的欄位約束（以這套標準為例，其他平臺大同小異）：
| 欄位 | 約束 |
|---|---|
name | 最長 64 個字元；只能用小寫字母、數字和連字元；不能帶 XML 標籤；不能含保留詞 |
description | 不能為空；最長 1024 個字元；不能帶 XML 標籤 |
具體數字會變
這些限制以你所用平臺的官方文件為準。要記的不是數字，是形狀：一個短標識 + 一段說明"是什麼 + 什麼時候用"。這個形狀在各家都一樣。
第 ② 層：正文
觸發之後才被讀進來的部分。一份好正文通常有這幾節：
# 會議紀要整理
## 什麼時候用
（簡單情況可省略，複雜 Skill 建議寫清適用與不適用）
## 流程
1. 通讀材料，標出已定事項、待辦、未定事項三類
2. 按下面的模板輸出
3. 輸出後對照"檢查清單"自查一遍
## 輸出模板
（直接給模子讓它填空）
## 規則
- 只用使用者給的材料
- 人名沿用原文稱呼，不要補全
- 負責人或時間不明確的寫「待確認」
- 前後矛盾的兩個都列出來並標「原文衝突」
## 示例
輸入：……（一段髒材料）
輸出：……（對應的成品，含一處「待確認」）
## 檢查清單
- [ ] 三個章節齊全
- [ ] 無原文之外的人名 / 日期 / 金額
- [ ] 每條待辦有負責人與截止（或「待確認」）三條寫作原則：
一、只寫它不知道的。 別在 Skill 里科普"會議紀要是一種記錄會議內容的文件"。它知道。你要寫的是"我們這兒的紀要跟別人的不一樣在哪"。
二、鬆緊要配得上任務。 這一條很實用：
| 任務性質 | 怎麼寫 |
|---|---|
| 多種做法都對，看情況判斷 | 給方向："審閱時重點看邏輯矛盾和缺失資訊" |
| 有偏好做法，但允許變通 | 給模板 + 說明可調："預設按這個結構，內容差異大時可增減章節" |
| 順序不能錯、錯了代價大 | 寫死步驟："嚴格按以下順序，每步完成後確認再進入下一步" |
打個比方：獨木橋兩邊是懸崖，就得給護欄；空地上怎麼走都行，就別畫格子。 該松的地方寫太死，它會僵；該緊的地方寫太鬆，它會飄。
三、控制長度。 正文太長會擠掉真正的材料。常見建議是把正文控制在幾百行以內（一套標準裡的說法是 500 行以下）；再長就該往第 ③ 層拆。
第 ③ 層：附件
正文放不下的東西，拆成同目錄下的獨立檔案，正文裡指過去：
meeting-notes/
├── SKILL.md 主說明（觸發描述 + 流程 + 規則）
├── TEMPLATES.md 三種會議類型的完整模板
├── EXAMPLES.md 五組輸入輸出示例
└── STYLE.md 我們公司的措辭禁忌正文裡這麼引：
## 模板
常規專案會用下面的預設模板。
客戶會 / 評審會 / 復盤會的專用模板見 [TEMPLATES.md](TEMPLATES.md)。
## 措辭
對外文件的措辭禁忌見 [STYLE.md](STYLE.md)。兩條硬規矩：
引用只能一層深。 SKILL.md → TEMPLATES.md 可以；SKILL.md → A.md → B.md 不行——巢狀太深時它可能只掃一眼就走了，拿到的是殘缺資訊。所有附件都從主檔案直接指過去。
長附件在開頭放個目錄。 超過一百行的參考檔案，開頭列一份小目錄，這樣它即使只掃開頭，也知道里面有什麼、值不值得讀完。
附件可以是腳本（可選，不會程式設計可跳過）
有些平臺允許 Skill 帶可執行腳本。好處是：腳本的程式碼不進上下文，只有執行結果進——又省錢又比讓它現寫程式碼可靠。
適合固定的、容易出錯的操作：格式校驗、批次轉換、資料核對。不會程式設計完全不影響前面所有內容。
一張圖收口
漸進式披露：用多少讀多少
- name
- description
- 幾十個字
- 流程
- 輸出模板
- 規則
- 示例 / 檢查清單
- TEMPLATES.md
- EXAMPLES.md
- scripts/
你寫 Skill 的功夫，應該按這個順序分配：第 ① 層花的時間不比第 ② 層少。 因為第 ② 層寫得再好，第 ① 層沒寫對，它一次都不會被用上。