本文根據 Agent Skills 開放規範（agentskills.io）的《Specification》《Best practices for skill creators》和 Claude Code 官方文檔整理，資料核對於 2026-10-11。Skill 是什麼、在各產品裏怎麼裝，見本站《Claude Skills 是什麼、怎麼裝》和《ChatGPT Skills 怎麼用》。
適用於誰
- 搜「skill.md 怎麼寫」「skill.md 格式」「skill.md 規範」「skill.md 範例」的人；
- 想把一套固定做法寫成 Skill，但不清楚 frontmatter 裏哪些字段必填、有什麼限制的人；
- 寫好的 Skill 在一個工具裏能用、換一個工具就報錯的人。
結論先說
- SKILL.md = YAML frontmatter + Markdown 正文。frontmatter 裏只有
name和description兩個字段是必填的。 name有硬性規則：最多 64 個字符，只能用小寫字母、數字和連字符，不能以連字符開頭或結尾，不能有連續連字符，並且要和所在文件夾同名。description最多 1024 個字符，要同時寫清「做什麼」和「什麼時候用」。智能體平時只看得到它，Skill 會不會被用上基本取決於這一段。- 正文沒有格式限制，但官方建議控制在 500 行以內、約 5000 token 以內，細節挪到單獨的參考文件裏。
- 想跨工具通用，frontmatter 只用規範裏的六個字段。各工具自己加的字段換個地方可能直接報錯。
一、最小的 SKILL.md
一個 Skill 是一個文件夾，裏面至少有一個 SKILL.md。規範給的最小寫法：
markdown
---
name: skill-name
description: A description of what this skill does and when to use it.
---frontmatter 後面接 Markdown 正文，也就是給智能體看的操作說明。Claude Code 的文檔還補了一條容易踩的細節：開頭的 --- 必須是文件的第一行。
二、frontmatter 的六個字段
| 字段 | 必填 | 限制與用途 |
|---|---|---|
name | 是 | 最多 64 字符；小寫字母、數字、連字符 |
description | 是 | 1–1024 字符；說明做什麼、什麼時候用 |
license | 否 | 許可證名稱，或指向隨 Skill 附帶的許可證文件 |
compatibility | 否 | 最多 500 字符；說明環境要求（面向哪個產品、需要哪些系統包、是否要聯網） |
metadata | 否 | 字符串到字符串的鍵值表，放規範之外的附加資訊，如作者、版本 |
allowed-tools | 否 | 用空格分隔的、預先批准可用的工具列表（實驗性，各工具支持不一） |
帶可選字段的官方示例：
markdown
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---規範特別說明：大多數 Skill 不需要 compatibility，只有確實對環境有要求時才寫，例如「Requires git, docker, jq, and access to the internet」。
三、name 的規則
規範列出的全部要求：
- 1–64 個字符；
- 只能包含小寫字母
a-z、數字0-9和連字符-； - 不能以連字符開頭或結尾；
- 不能出現連續的連字符
--； - 必須和上級目錄名一致。
所以 PDF-Processing（有大寫）、-pdf（連字符開頭）、pdf--processing（連續連字符）都不合規。中文名、帶空格或下劃線的名字同樣不符合字符要求，起名時直接用英文短語加連字符，如 weekly-report、code-review。
四、description 怎麼寫
規範的要求是三條：1–1024 字符、同時描述做什麼和什麼時候用、包含能幫智能體識別相關任務的具體關鍵詞。
官方給的一好一壞：
yaml
# 好
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
# 差
description: Helps with PDFs.《Optimizing skill descriptions》裏還有四條寫法建議：
- 用祈使句，寫成「Use this skill when...」而不是「This skill does...」；
- 寫用戶想達成什麼，而不是 Skill 內部怎麼實現；
- 寧可寫得主動一點，把用戶沒有直接說出領域名稱的場景也列進去；
- 保持簡短，幾句話到一小段，裝了很多 Skill 時描述太長會擠佔上下文。
description 寫不好導致 Skill 不被調用，是最常見的問題，排查辦法見《Skill 不觸發怎麼辦》。
五、正文寫什麼
規範對正文沒有格式要求，推薦包含三類內容：分步驟的說明、輸入輸出的例子、常見的邊界情況。要注意的是，智能體一旦決定啟用某個 Skill，就會把整份 SKILL.md 讀進上下文，所以寫多了是有代價的。
官方最佳實踐裏幾條最實用的原則：
只寫智能體不知道的。 不需要解釋 PDF 是什麼、HTTP 怎麼工作。對每一段內容問一句：沒有這條說明，智能體會做錯嗎？不會就刪掉。該寫的是項目特有的約定、領域流程、不明顯的坑、指定要用的工具或接口。
給預設做法，不要給選單。 「可以用 pypdf、pdfplumber、PyMuPDF 或 pdf2image」不如「用 pdfplumber 提取文本；掃描件需要 OCR 時改用 pdf2image 加 pytesseract」。
教方法，不要給某一次的答案。 「把 orders 表和 customers 表按 customer_id 關聯，篩選 EMEA 區域」只對這一次有用；「先讀 schema 文件找到相關的表，再按外鍵約定關聯，再把用戶的條件寫成篩選」才可以複用。
按任務的脆弱程度決定寫多死。 多種做法都行的地方，說明目的、讓智能體自己判斷；順序不能錯、命令不能改的地方（比如數據庫遷移），就寫「嚴格按以下命令執行，不要增刪參數」。
專門留一節「注意事項」（Gotchas）。 官方認為這往往是一個 Skill 裏價值最高的部分：那些違反直覺的環境事實，例如「users 表是軟刪除，查詢必須帶 WHERE deleted_at IS NULL」。智能體每犯一次需要你糾正的錯，就往這裏加一條。
要固定輸出格式就給模板。 比起用文字描述格式，直接給一份帶佔位符的模板更可靠。
多步驟流程用清單，關鍵步驟後做校驗。 讓智能體做完之後跑一遍校驗腳本或對照檢查表，不通過就修到通過為止。
六、一份可以照着改的範例
下面是按規範寫的一個示例（內容為演示）：
markdown
---
name: weekly-report
description: Write the team's weekly report in the fixed four-section format. Use when the user asks for a weekly report, a week summary, or wants to turn notes or commit logs into a status update, even if they do not say "weekly report".
metadata:
author: your-team
version: "1.0"
---
# 週報
## 步驟
1. 向用戶確認本週的起止日期；用戶已提供材料時不要重複詢問。
2. 把材料歸入下面四個部分，每部分不超過 5 條。
3. 每一條以結果開頭，寫清數字或交付物，不寫過程。
## 輸出模板
### 本週完成
### 進行中
### 風險與需要的支持
### 下週計劃
## 注意事項
- 沒有材料支撐的內容不要編寫，標註「待補充」。
- 涉及客戶名稱時使用內部代號，見 references/customers.md。description 用英文還是中文，規範沒有限制；寫哪種語言，以你平時提需求的語言為準。
七、各工具額外支持的字段
規範只定義了上面六個字段，各工具會在此基礎上擴展。例如 Claude Code 額外支持 disable-model-invocation、user-invocable、context、paths 等十幾個字段，用來控制誰能調用、是否放到子代理裏運行。
這些擴展字段換個地方不一定認。Claude Code 文檔寫明：在 Claude Code 之外（上載到 claude.ai、Skills API 等），frontmatter 只接受 name、description、license、compatibility、metadata、allowed-tools，出現其他鍵會直接報錯，形如 Unexpected key(s) in SKILL.md frontmatter: argument-hint.。
所以要分發給別人或者跨工具使用的 Skill，frontmatter 只留規範字段；工具專屬的字段只寫在自己用的那一份裏。
八、寫完之後校驗
規範頁給出了參考校驗工具 skills-ref 的用法：
bash
skills-ref validate ./my-skill它檢查 frontmatter 是否合法、命名是否符合約定。安裝方式見其倉庫說明。
常見問題
Q：提示 frontmatter 缺少 name 或 description 怎麼辦？
先看三處：--- 是不是文件第一行、YAML 縮進和冒號後的空格是否正確、description 裏有沒有未加引號的冒號。Claude Code 文檔說明，YAML 寫錯時 Skill 仍會加載，但所有字段都是空的，表現為可以手動調用、卻不會被自動選中。
Q：description 太長寫不下怎麼辦？
1024 字符是硬上限。把「什麼時候用」放在最前面，細節放正文。
Q：正文超過 500 行了？
把詳細的參考資料挪到 references/ 下的單獨文件，並在 SKILL.md 裏寫明什麼情況下去讀哪個文件。目錄怎麼組織見《Skill 目錄結構怎麼組織》。
Q：可以讓 AI 幫我寫 Skill 嗎？
可以，但官方提醒不要讓模型憑通用知識憑空生成，那樣只會得到「妥善處理錯誤」「遵循最佳實踐」這類空話。更好的做法是先和智能體把一個真實任務做完，再把過程中有效的步驟、你做過的糾正、輸入輸出格式提煉成 Skill。
參考資料
- Specification（Agent Skills 官方規範）：https://agentskills.io/specification
- Best practices for skill creators：https://agentskills.io/skill-creation/best-practices
- Optimizing skill descriptions：https://agentskills.io/skill-creation/optimizing-descriptions
- Extend Claude with skills（Claude Code 官方文檔）：https://code.claude.com/docs/en/skills
0 條評論
還沒有評論，來搶沙發～