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

> Author: Tony Lee
> Published: 2026-02-17
> URL: https://tonylee.im/zh-HK/blog/anthropic-skill-md-body-writing-rules/
> Reading time: 2 minutes
> Language: zh-HK
> Tags: ai, claude-code, developer-tools, skills, productivity

## Canonical

https://tonylee.im/zh-HK/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 官方文件同工程 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 就好似好嘅入職文件。預設讀者已經好叻嘅文件，先至係最有力量嘅。

## Related URLs

- Author: https://tonylee.im/en/author/
- Publication: https://tonylee.im/en/blog/about/
- Related article: https://tonylee.im/zh-HK/blog/eight-hooks-that-guarantee-ai-agent-reliability/
- Related article: https://tonylee.im/zh-HK/blog/medvi-two-person-430m-ai-compressed-funnel/
- Related article: https://tonylee.im/zh-HK/blog/claude-code-layers-over-tools-2026/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/zh-HK/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-HK/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.