Anthropic 公開的 SKILL.md Body 撰寫規則 5 條

Skill 只需要兩行 YAML frontmatter 就能建立。但 body 怎麼寫，直接決定了輸出品質的天花板。

交叉比對 Anthropic 官方文件和工程部落格後，我把運作機制和 body 撰寫原則整理成了五條規則。起因是我自己寫的 Skill 偶爾載入失敗，趁假期從頭做了一遍驗證。

不了解 Skill 執行順序，body 設計就會跑偏

Skill 不會像 prompt 那樣直接注入對話。啟動時載入系統提示詞的只有 name 和 description。

當使用者請求與 description 匹配時，Claude 會透過 Bash 工具讀取 SKILL.md 全文，接著在需要時才載入參考檔案和腳本。Anthropic 工程部落格把這個結構稱為「漸進式揭露（progressive disclosure）」。

• 第 1 階段：僅元資料（name + description）常駐載入，每個 Skill 約 100 token
• 第 2 階段：SKILL.md body 僅在匹配時進入上下文視窗
• 第 3 階段：scripts 和 references 資料夾中的檔案在實際參照時載入
• 腳本執行時，程式碼本身不進入上下文，只有輸出結果被消耗

不理解這個結構，body 裡就會塞滿多餘資訊，真正重要的內容反而被遺漏。

在 body 裡寫「什麼時候用」就是浪費 token

很多人在 body 裡加了「When to Use This Skill」章節。親手試過之後發現完全沒用, , body 是 Skill 已經被觸發之後才讀取的。

「什麼時候用」只能寫在 description 裡。Anthropic 官方 skill-creator 儲存庫也明確了這一點。

• description 是唯一的觸發入口（body 裡寫了 Claude 也不會參考）
• description 上限 1,024 字元，用第三人稱寫能提高被發現的準確率
• body 裡該放的是任務規則、操作流程和預期輸出格式
• 把「本 Skill 適用於……」這類句子從 body 中刪除

body 控制在 500 行以內，其餘內容拆分出去

Anthropic 指南的開頭就說：上下文視窗是共享資源。Skill 載入後，要和對話記錄、系統提示詞共享 token。

官方建議 body 控制在 500 行以下，詳細內容拆分到獨立檔案。SKILL.md 充當目錄，參考檔案充當各章節。

• body 500 行以下（Anthropic best practices 明確標註）
• 參考檔案從 SKILL.md 只連結一層深度
• 超過兩層巢狀參照時，Claude 可能只用 head -100 讀取部分內容
• 超過 100 行的參考檔案在開頭加目錄

假設 Claude 已經很聰明來寫

在 body 裡解釋 PDF 是什麼，純粹浪費 token。Anthropic 指南反覆強調一個原則：

「Claude 已經知道的東西就不要寫。」

50 token 的精簡程式碼範例比 150 token 的概念解釋效能更好。在同樣的 PDF 擷取任務中，精簡 body 比冗長 body 的準確率明顯更高。

• 每句話都問自己：「這段說明值不值這些 token？」
• 用程式碼範例 + 預期輸出格式取代概念說明
• 把任務自由度分成三級（高/中/低）來調節指令強度
• 資料庫遷移類任務自由度設低，程式碼審查設高

在 body 中嵌入驗證迴圈才能提升品質

執行 → 驗證 → 修復 → 再驗證。這是 Anthropic 推薦的 body 模式中最實用的部分。在 body 裡加入檢查清單後，Claude 跳步的情況明顯減少。

官方指南還指出，「MUST filter」這樣的強表達比「always filter」的遵循率更高。

• 複雜任務用檢查清單格式列出步驟
• 在 body 中包含腳本驗證 → 錯誤修復 → 再驗證迴圈
• 用「MUST」替代「always」能提高 Claude 的遵循率
• 錯誤訊息寫得越具體，Claude 自動修復的能力越強

核心要點

description 決定「何時觸發」，body 決定「如何執行」。兩者職責一旦混淆，Skill 既不會正常觸發，輸出品質也會下降。

好的 Skill 就像好的入職文件。預設讀者已經很聰明的文件，才是最有力量的。