前言¶

給 Cursor、Claude Code 或 Codex CLI 加一段可複用流程時，很多人會先把說明寫進項目規則文件。規則文件會長期佔用上下文；而 Agent Skills 把同一套說明拆成按需加載的文件夾：平時只暴露名稱和簡介，真正用到時纔讀完整指令。

2025 年 12 月 18 日，Anthropic 把這套格式做成開放標準，規範文檔放在 agentskills.io/specification。要自己寫一個 Skill，不必從空白文件猜字段。Anthropic 在官方倉庫 anthropics/skills 裏提供了起始骨架，目錄名是 template，Skill 名稱是 template-skill。

本文按該模板和開放規範，說明它是什麼、目錄怎麼放、frontmatter 怎麼填、正文怎麼寫，以及在 Cursor、Claude Code、Codex CLI 裏如何啓用。

這是什麼¶

template-skill 是 Anthropic 官方維護的 Skill 模板，位於 github.com/anthropics/skills/tree/main/template。倉庫 README 的「Creating a Basic Skill」一節明確寫了：寫自定義 Skill 時，可以用倉庫裏的 template-skill 作爲起點。

它本身不處理 PDF、不跑測試、也不封裝某個業務工作流。template 目錄裏目前只有一個 SKILL.md（約 140 字節），提供標準的 YAML frontmatter 和正文佔位。作用是告訴作者：一個合法 Skill 最少長什麼樣。

Agent Skills 的最小單位是一個文件夾，根目錄必須有 SKILL.md。文件分兩段：開頭的 YAML 元數據，以及後面的 Markdown 指令。Agent 啓動時只預加載 name 和 description；任務匹配上之後，再讀完整正文；scripts/、references/、assets/ 等附加文件只在指令裏引用到時才加載。Anthropic 工程博客把這套機制叫做 progressive disclosure（漸進披露）。

模板原文¶

官方 SKILL.md 全文如下，沒有省略：

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

需要改的只有三處：

• name：換成你的 Skill 標識，並與父目錄名保持一致。
• description：寫清這個 Skill 做什麼、以及什麼時候該啓用。Agent 主要靠這段文字判斷要不要加載它。
• 正文：把 # Insert instructions below 換成具體步驟、示例和邊界條件。

倉庫 README 給了一份稍完整的填寫示例，可以作爲正文骨架：

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

規範建議正文裏再補上逐步操作、輸入輸出樣例，以及常見邊界情況。這些不是強制章節名，但比只留一句「Insert instructions below」更容易被 Agent 執行對。

標準目錄與 frontmatter¶

按 Agent Skills 規範，一個 Skill 目錄至少包含 SKILL.md，其餘目錄可選：

skill-name/
├── SKILL.md          # 必需：元數據 + 指令
├── scripts/          # 可選：可執行腳本
├── references/       # 可選：按需閱讀的文檔
├── assets/           # 可選：模板、圖片、數據文件
└── ...

SKILL.md 必須先寫 YAML frontmatter，再寫 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"
---

name 的合法與非法對照可以直接照規範來：

# 合法
name: pdf-processing
name: data-analysis
name: code-review

# 非法
name: PDF-Processing    # 不能有大寫
name: -pdf              # 不能以連字符開頭
name: pdf--processing   # 不能連續連字符

description 要寫具體觸發詞。規範給的對比是：

# 較好：同時寫清能力和觸發場景
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.

# 較差：太短，Agent 很難判斷何時啓用
description: Helps with PDFs.

關於加載節奏，規範給出的建議是：全部已安裝 Skill 的元數據合計大約 100 tokens；激活後的 SKILL.md 正文建議控制在 5000 tokens 以內；主文件儘量不超過 500 行，細節放到獨立引用文件。引用時用相對於 Skill 根目錄的路徑，並且儘量只引用一層，避免連環嵌套：

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Anthropic 面向 Claude 的平臺文檔還額外寫了：name 和 description 不能包含 XML 標籤；name 不能使用保留詞 anthropic、claude。這是 Claude 產品側的約束，開放規範本身沒有這條。如果 Skill 主要給 Claude 用，按產品文檔避開這些詞即可。

安裝與啓用¶

template-skill 不是裝完就能幹活的業務 Skill，而是一份要複製後改寫的骨架。先拿到文件：

git clone https://github.com/anthropics/skills.git
cp -r skills/template my-skill-name

只取 SKILL.md 也可以：

mkdir -p my-skill-name
curl -o my-skill-name/SKILL.md \
  https://raw.githubusercontent.com/anthropics/skills/main/template/SKILL.md

然後把目錄名、name 字段改成同一個標識，再把目錄放到對應工具會掃描的位置。各工具官方文檔裏的路徑並不完全相同，需要分開看。

Cursor（cursor.com/docs/skills）會從下面這些位置自動發現 Skill：

爲了兼容，Cursor 還會讀取 .claude/skills/、.codex/skills/，以及用戶目錄下的 ~/.claude/skills/、~/.codex/skills/。項目級示例：

.cursor/skills/my-skill-name/SKILL.md

在 Agent 對話裏輸入 /，按 Skill 名稱搜索即可手動調用；Agent 也會根據 description 判斷是否自動啓用。

Claude Code（code.claude.com/docs/en/skills）的常用位置是：

個人 Skill 示例：

mkdir -p ~/.claude/skills/my-skill-name
# 把改好的 SKILL.md 放到該目錄

Claude Code 會按 description 自動匹配，也可以用 /skill-name 直接調用。同名時，個人目錄優先於項目目錄。

Codex CLI（developers.openai.com/codex/skills）掃描的倉庫位置是 .agents/skills（從當前工作目錄一直找到倉庫根），用戶級位置是 $HOME/.agents/skills。機器級還有 /etc/codex/skills。Codex 啓動時會帶上名稱、簡介和文件路徑；任務匹配後再讀完整 SKILL.md。手動調用可以在 CLI / IDE 擴展裏用 /skills，或用 $ 提到某個 Skill。

三個工具都能讀同一份符合開放規範的 SKILL.md。差異主要在掃描目錄和調用前綴（/ 或 $），不在模板格式本身。

如果只在 Claude Code 裏試用官方倉庫裏已經打好的示例插件，而不是自己改模板，可以用：

/plugin marketplace add anthropics/skills

隨後按文檔安裝 document-skills 或 example-skills。這套流程裝的是倉庫裏的示例 Skill，不會把 template-skill 變成一個可執行的業務能力。寫自己的 Skill，仍然是複製模板、改字段、放到掃描目錄。

從模板寫出一個可運行的例子¶

下面用 Claude Code 文檔裏的「彙總未提交改動」場景，演示如何把模板填實。先建目錄：

mkdir -p ~/.claude/skills/summarize-changes

把 SKILL.md 寫成類似下面這樣（description 來自 Claude Code 官方入門示例；動態注入 !git`` 是 Claude Code 的擴展語法，開放規範沒有這一條，換到 Cursor 或 Codex 時不要照抄這一行）：

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Instructions

Summarize the uncommitted changes in two or three bullet points, then list any risks such as missing error handling, hardcoded values, or tests that need updating. If there are no uncommitted changes, say so.

在 git 倉庫裏隨便改一個文件，啓動 Claude Code 後可以這樣測：

What did I change?

或直接：

/summarize-changes

放到 Cursor 時，目錄改成 .cursor/skills/summarize-changes/SKILL.md 或 ~/.cursor/skills/summarize-changes/SKILL.md，frontmatter 保持同樣的 name / description 即可。放到 Codex 時，用 .agents/skills/summarize-changes/ 或 ~/.agents/skills/summarize-changes/。

正文寫完之後怎麼擴展¶

模板只有一頁指令。任務變複雜時，規範建議把細節拆出去，而不是把 SKILL.md 寫成說明書全集。

• scripts/：給 Agent 直接執行的代碼。適合確定性步驟，例如校驗、格式轉換。腳本應自包含或寫清依賴，並帶上能看懂的錯誤信息。
• references/：按需閱讀的補充文檔，例如 REFERENCE.md、表單說明、領域手冊。單個文件儘量聚焦，避免一次塞進全部背景。
• assets/：模板、示意圖、查找表等靜態資源。

Anthropic 工程博客用官方 PDF Skill 說明了爲什麼要拆文件：表單填寫說明放到 forms.md 後，主 SKILL.md 可以保持精簡，Agent 只有在填表時纔去讀那份文件。代碼也可以當工具用：同一篇博客提到，PDF Skill 裏有一段提取表單字段的 Python 腳本，Claude 可以直接跑腳本，而不必把腳本和 PDF 都讀進上下文。

寫作原則上，Claude 平臺的 Skill authoring best practices 強調：默認假設模型已經具備通用知識，只寫它缺的流程、約定和易錯點。能用短指令說清的，就不要先解釋文件格式是什麼。

寫好後可以用規範提供的參考實現做校驗：

skills-ref validate ./my-skill-name

這個命令檢查 frontmatter 是否合法、命名是否符合約定。工具在 github.com/agentskills/agentskills。

適用場景與注意事項¶

適合用 template-skill 起步的情況很具體：你已經有一段反覆粘貼的操作說明，想把它變成可發現、可共享的 Skill，但還沒有腳本和長文檔。從官方骨架開始，可以避免漏掉必需的 YAML 分隔符，也避免 name 寫成大寫或和目錄名不一致。

它不適合當成「寫 Skill 的導師」。倉庫裏另有 skill-creator，那是帶評測腳本和參考文檔的完整 Skill，用來指導如何設計、測試和迭代。template-skill 只提供最小合法文件。兩者不要混用：一個是空白稿紙，一個是寫作指南。

寫的時候有幾處容易踩坑：

1. 目錄名和 name 必須一致。規範要求 name 匹配父目錄名，工具按目錄發現 Skill。
2. description 決定會不會被自動調用。只寫「幫助處理某某」通常不夠，要把用戶可能說的詞寫進去。
3. 先寫短指令，確認能觸發、能執行，再加 scripts/ 和 references/。官方幫助文檔的建議也是：從 Markdown 指令開始，需要確定性時再加代碼。
4. 各產品會在開放字段之外加自己的擴展。例如 Cursor 的 paths、disable-model-invocation，Claude Code 的動態上下文注入，Codex 的 agents/openai.yaml。這些字段不是 template-skill 裏的內容，跨工具共享時優先保證 name 和 description 符合 agentskills.io，擴展字段按目標產品文檔再加。
5. Skill 可以帶可執行腳本。Anthropic 建議只安裝可信來源，啓用前讀一遍捆綁的腳本和外部網絡請求。不要在指令或腳本里寫死密鑰。

倉庫 README 也寫明：這些 Skill 主要用於演示和教育，實際產品行爲可能和倉庫裏的實現不完全一樣。模板能保證格式起點正確，不能保證改完之後在每個 Agent 上表現一致，需要在目標工具裏用真實任務測觸發和執行。

小結¶

template-skill 是 Anthropic 官方 Skill 倉庫裏的起始骨架：一個帶 name、description 佔位的 SKILL.md。Agent Skills 已經是開放標準，同一份文件可以放到 Cursor、Claude Code、Codex CLI 各自的 skills 目錄裏使用。

從它寫出第一個 Skill 的步驟可以收成四句：複製模板；讓目錄名和 name 相同；把 description 寫成「做什麼 + 何時用」；在正文裏寫可執行的步驟和例子。需要校驗格式時，用 skills-ref validate。

官方模板：https://github.com/anthropics/skills/tree/main/template

格式規範：https://agentskills.io/specification

機制說明：Equipping agents for the real world with Agent Skills