Anthropic 公開嘅 SKILL.md Body 寫法規則 5 條

Skill 淨係需要兩行 YAML frontmatter 就建立到。但 body 點寫，直接決定咗輸出質素嘅上限。

交叉比對 Anthropic 官方文件同工程 blog 之後，我將運作機制同 body 寫法原則整理成五條規則。起因係我自己寫嘅 Skill 間中載入失敗，趁假期由頭做咗一次驗證。

唔了解 Skill 執行順序，body 設計就會出事

Skill 唔會好似 prompt 咁直接注入對話。啟動嗰陣載入系統提示詞嘅只有 name 同 description。

當用戶請求同 description 匹配嗰時，Claude 會透過 Bash 工具讀取 SKILL.md 全文，之後先至喺需要嗰時載入參考檔案同腳本。Anthropic 工程 blog 將呢個結構叫做「漸進式揭露（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 就好似好嘅入職文件。預設讀者已經好叻嘅文件，先至係最有力量嘅。