# Anthropic 公開的 SKILL.md Body 撰寫規則 5 條 > Author: Tony Lee > Published: 2026-02-17 > URL: https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/ > Reading time: 2 minutes > Language: zh-TW > Tags: ai, claude-code, developer-tools, skills, productivity ## Canonical https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/ ## Rollout Alternates en: https://tonylee.im/en/blog/anthropic-skill-md-body-writing-rules/ ko: https://tonylee.im/ko/blog/anthropic-skill-md-body-writing-rules/ ja: https://tonylee.im/ja/blog/anthropic-skill-md-body-writing-rules/ zh-CN: https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/ zh-TW: https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/ ## Description 藏在 Anthropic 官方文件裡的 SKILL.md body 撰寫原則 5 條。從 description 與 body 的職責分離到驗證迴圈。 ## Summary Anthropic 公開的 SKILL.md Body 撰寫規則 5 條 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - 不了解 Skill 執行順序，body 設計就會跑偏 - 在 body 裡寫「什麼時候用」就是浪費 token - body 控制在 500 行以內，其餘內容拆分出去 - 假設 Claude 已經很聰明來寫 - 在 body 中嵌入驗證迴圈才能提升品質 - 核心要點 ## Content 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 就像好的入職文件。預設讀者已經很聰明的文件，才是最有力量的。 ## Related URLs - Author: https://tonylee.im/zh-TW/author/ - Publication: https://tonylee.im/zh-TW/blog/about/ - Related article: https://tonylee.im/zh-TW/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-TW/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/zh-TW/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/zh-TW/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.