前言¶

给 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