一篇讲清 Agent Skills：把经验变成可调用的能力

本篇章节目录：

1. 为什么需要 Skill
2. Skill 是什么
3. Skill 的基本结构：SKILL.md 与可选目录
4. Skill 应该放在哪里
5. 什么内容适合做成 Skill
6. 如何创建一个 Skill
7. Skill 是如何被调用的
8. Skill 的两种内容类型：参考型内容与任务型内容
9. 如何组织复杂 Skill：让 SKILL.md 保持简洁
10. Skill、Prompt、MCP 和 AGENTS.md 如何选择
11. 如何判断一个 Skill 写得好不好
12. 小结：把经验变成可调用的能力

为什么需要 Skill

一个团队里会有很多规范、经验和文档：编程规范、接口规范、合规规范、文档模板、历史踩坑记录等。

如果希望 AI 了解这些信息，最直接的做法，是把它们写进 AGENTS.md（在 Claude Code 里，对应的是 CLAUDE.md，下文用 AGENTS.md 代表）。这类文件会在对话开始时进入上下文，用来放项目结构、编码风格、构建命令、长期约定这类全局规则。

相关的 CLAUDE.md，我之前在《Claude Code 进阶实践：CLAUDE.md 与自动记忆》里单独写过。

但如果什么都往里放，问题很快就会出现：慢是一方面，更麻烦的是，真正相关的规则可能会被一大堆无关信息淹没。

那么，这些文档应该怎么交给 AI 呢？

Skill 面向的是专项能力 ，让 Agent 在合适的时机调用。它把某个场景需要的流程、参考资料、模板和脚本打包成能力包：流程告诉 Agent 怎么做，参考资料和模板提供参照，脚本负责那些更适合自动化的步骤。

这样，一套经验就不再是一次性的提示，而是可以保存、复用、维护、纳入版本管理，甚至迁移到其他支持 Skill 的 Agent 里。遇到同类任务时，Agent 可以直接调用它，而不是每次都重新说明。

Skill 是什么

Skill 翻译过来就是"技能"。

人类做事时，也会有各种技能。比如财务会处理发票和报销，法务会审合同，运营会写活动方案，程序员会排查线上问题。

这些技能背后，不只是一句口诀，而是一套知识、规则、流程和经验。

一个会处理发票的人，不只是知道"要核对金额"这句话。他还知道发票有哪些类型、哪些字段必须存在、哪些报销规则要匹配、异常情况应该怎么处理。具体做事时，才会按照一套步骤去检查和整理。

它告诉 Agent：在什么时候 、用什么方式 、做什么事。

按官方说法，Agent Skills 是一种轻量的开放格式，用来把专业知识和工作流交给 Agent，从而扩展它的能力。

普通文档是给人查的，Skill 是给 Agent 调用的：它会说明什么时候用、怎么用，以及需要哪些模板、资料或脚本配合。

从形态上看，Skill 是一个文件夹，核心是一份 SKILL.md，需要时还可以带上脚本、参考资料和模板。下一节具体讲。

Skill 的关键在于把一类任务的知识、流程和工具，整理成 Agent 可以按需调用的能力单元。

Skill 的基本结构：SKILL.md 与可选目录

一个 Skill 长什么样

Skill 是一个文件夹。这个文件夹里只有一个文件是必需的：SKILL.md。其他目录都是可选的。

一个最简单的 Skill 可以长这样：

my-skill/
└── SKILL.md

复杂一点的 Skill，可能会带上脚本、参考资料和模板：

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── ...

SKILL.md 是整个 Skill 的入口。Agent 先通过它理解这个 Skill 的用途、适用场景和执行方法。

SKILL.md 的两部分

SKILL.md 分成两部分：Frontmatter 和 Markdown 正文。

Frontmatter

Frontmatter 写在文件最前面，用三条横线包起来，格式类似这样：

---
name: invoice-processing
description: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当用户需要处理发票或准备报销材料时，使用这个 Skill。
---

按照 Agent Skills 规范，Frontmatter 常见字段如下。其中，name 和 description 是必需字段；其他字段都是可选的。

字段	说明
name	Skill 的名字。1~64 个字符，只能用小写字母、数字和英文横杠 -；不能用 - 开头或结尾，不能出现连续的 --，并且必须和所在文件夹同名。
description	Skill 的适用说明，不能为空，最多 1024 个字符。它要说清这个 Skill 做什么、什么时候该用。
license	许可证信息。自己用可以先不管，准备分享或分发时再补。
compatibility	运行环境要求，比如适合哪个产品、依赖哪些系统包、是否需要网络访问。最多 500 个字符。
metadata	自定义信息，供平台或工具读取。
allowed-tools	预先允许这个 Skill 使用哪些工具。这个字段还属于实验性能力，不同客户端支持情况可能不同。

刚开始写 Skill 时，先把 name 和 description 写清楚就够了。

Markdown 正文

Frontmatter 下面，就是 Markdown 正文。正文没有固定格式，写什么取决于这个 Skill 要帮 Agent 完成什么任务。常见内容包括：

• 分步骤的操作说明
• 输入和输出要求（如有必要，提供输入和输出示例）
• 常见边界情况
• 注意事项或禁止事项
• 什么时候需要读取参考资料
• 什么时候应该调用脚本

可选目录：scripts/、references/、assets/

除了 SKILL.md，Skill 还可以带一些可选目录，最常用的是 scripts/、references/ 和 assets/。

scripts/ 适合放可执行代码，比如数据清洗、格式转换、结果校验。

references/ 适合放长参考资料，比如 API 文档、公司规范、字段说明、案例说明。

assets/ 适合放模板和静态资源，比如报告模板、表格样例、图片素材。

这些目录都不是强制的。一个 Skill 可以只有 SKILL.md，也可以根据任务复杂度逐步增加。

这些可选目录的作用，是把脚本、长资料和模板从主 SKILL.md 里拆出去。具体怎么拆，后面讲复杂 Skill 时再展开。

Skill 应该放在哪里

Skill 放在哪里，取决于你希望它在哪些地方生效。

先分两类：

• 项目级 Skill：只在当前项目里使用，适合本项目的接口规范检查、数据库字段说明、发布流程、业务规则校验等和项目强绑定的能力。
• 用户级 Skill：在多个项目里都能使用，适合发票整理、会议纪要整理、固定写作风格、CSV 数据清洗等可以跨项目复用的能力。

实践中，可以把 .agents/skills/ 当作共享源目录：支持这个路径的客户端直接扫描；不支持的客户端，通过软链接接到自己的目录。这样同一套 Skill 只需要维护一份。

项目级 Skill 放在：

<project>/.agents/skills/<skill-name>/SKILL.md

用户级 Skill 放在：

~/.agents/skills/<skill-name>/SKILL.md

但也有客户端使用自己的目录约定。比如 Claude Code 使用的是：

<project>/.claude/skills/<skill-name>/SKILL.md
~/.claude/skills/<skill-name>/SKILL.md

如果某个客户端有自己的目录，就把 .agents/skills/ 里的 Skill 用软链接接过去。

比如项目里真实维护的是：

.agents/skills/invoice-processing/

Claude Code 需要使用时，在 .claude/skills/ 里创建软链接：

mkdir -p .claude/skills
ln -s ../../.agents/skills/invoice-processing .claude/skills/invoice-processing

这样，invoice-processing 只需要维护一份；不同 Agent 按自己的扫描目录读取。

什么内容适合做成 Skill

不是所有内容都要做成 Skill。

判断一段内容适不适合做成 Skill，看它有没有下面这些特征。命中的越多，越值得沉淀：

• 反复出现：总是在不同对话里重复解释同一套规则、流程或格式。
• 场景明确：能说清楚它在什么情况下使用，比如处理发票、生成月报、做代码审查。
• 需要专门知识：涉及公司内部规范、行业术语、API 约定、数据库字段、品牌文案规则。
• 流程稳定：步骤相对固定，比如部署、数据清洗、报销处理、报告生成。
• 容易出错：Agent 经常在同类任务里犯同样的错，尤其是那些看起来合理、实际不对的地方。
• 输出固定：你希望 Agent 每次按固定结构输出，比如报告模板、审查清单、表格格式。
• 适合自动化：某些步骤每次都差不多，而且用脚本更稳定，比如校验字段、转换格式、提取数据。

反过来，有些内容不适合直接做成 Skill：

• 全局规则 ：所有任务都要遵守的规则，更适合放在 AGENTS.md。
• 一次性需求：只用一次的临时任务，直接在对话里说清楚就行。
• 宽泛目标：只有"写得更好""更专业一点"这种目标，但没有具体场景和判断标准。

反复用到、场景明确、但不需要每次常驻的知识或流程，更适合做成 Skill。

如何创建一个 Skill

写 Skill 不要一开始就追求完整。先做一个最小可用版本：围绕一个明确任务展开，只保留 Agent 完成这个任务必须知道的内容。

手动创建：先跑通一个最小版本

比如继续用前面的发票处理场景。这个 Skill 第一版不需要处理所有财务流程，只解决一件事：

当用户提供发票信息时，帮助整理关键信息、校验明显问题，并输出报销材料草稿。

第一步，给 Skill 起一个名字。

name: invoice-processing

name 能看出用途就好。

第二步，写清楚它做什么、什么时候该用。

description 会影响 Agent 是否能在合适的任务里调用这个 Skill。它不要写得太泛，比如：

description: 帮助处理财务问题。

这类描述范围太大，容易让 Agent 误触发；建议写清楚这个 Skill 的作用，以及什么时候应该使用它：

description: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当用户需要处理发票或准备报销材料时，使用这个 Skill。

description 至少要回答两个问题：

• 这个 Skill 做什么？
• 什么情况下应该使用它？

第三步，写正文。

正文写什么，取决于这个 Skill 要帮 Agent 完成什么。这里可以放处理步骤，也可以放规则、示例、注意事项和输出要求。

发票处理 Skill 的正文，可以先写清楚几类信息：

• 需要提取哪些字段
• 按哪些规则检查
• 遇到缺失或异常时怎么处理
• 最后按什么格式输出

把前面的内容拼起来，一个最小可用的 SKILL.md 大概是这样：

---
name: invoice-processing
description: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当用户需要处理发票或准备报销材料时，使用这个 Skill。
---

# 发票处理

1. 确认用户提供了哪些发票信息。
2. 提取发票号码、日期、金额、销售方、购买方等关键字段。
3. 检查金额、日期、发票类型是否缺失或明显异常。
4. 如果用户提供了报销规则，按规则检查是否符合要求。
5. 输出整理后的发票信息、发现的问题，以及需要用户补充的内容。

写完以后，找一个真实场景试一下，比如："帮我整理这几张发票，看看有没有报销问题。"如果 Agent 没有按预期使用这个 Skill，再回头调整 description 或正文说明。

等它在真实任务里跑过几次，再决定要不要补资源：

• 经常要校验金额，加脚本，放到 scripts/。
• 报销规则很多，放到 references/。
• 输出格式必须固定，加模板，放到 assets/。

用 skill-creator 辅助生成初始结构

也可以使用 skill-creator 这样的辅助 Skill，帮你生成 Skill 的初始目录和 SKILL.md。

安装方式如下：

npx skills add https://github.com/anthropics/skills --skill skill-creator

这个 Skill 来自 Anthropic 的公开 Skills 仓库。

skill-creator 只是帮你搭好初始结构。一个 Skill 是否好用，关键还是任务边界、适用场景和正文内容是否写清楚。

Skill 是如何被调用的

Skill 的调用方式有两类：自动触发和手动触发。

自动触发：发现、激活、执行

自动触发背后的机制，官方叫 progressive disclosure ，可以翻译成"渐进式披露"。

渐进式披露指的是：不在一开始加载全部内容，而是按需要一层层展开。

自动触发分三步：发现 → 激活 → 执行。

发现

新开启一个会话时，Agent 不会读取每个 Skill 的完整内容，而是先读取 name 和 description，形成一个很轻的 Skill 列表。

这一步是为了让 Agent 知道有哪些可用 Skill，以及每个 Skill 大概适合什么场景。Agent 最早看到的不是完整 SKILL.md，而是这几行元数据。

激活

当用户提出一个任务时，模型会基于当前任务和各个 Skill 的 description，判断是否需要使用某个 Skill。这个判断不是简单的关键词匹配，而是看用户真正想完成什么。

如果判断相关，客户端才会读取这个 Skill 的完整 SKILL.md，把正文说明加载进上下文。

description 很重要：它不是普通简介，而是影响 Skill 能否被正确选中的入口信息。

执行

Skill 被激活后，Agent 会按照 SKILL.md 里的说明执行任务。

如果正文里提到参考资料，Agent 会按需要读取 references/ 里的文件；需要模板或静态资源时，使用 assets/；某个步骤更适合自动化时，调用 scripts/ 里的脚本。

即使安装了很多 Skill，它们也不会一开始就占满上下文、消耗大量 token。

手动触发：直接指定 Skill

除了让 Agent 自动判断，有些客户端也支持手动指定要用哪个 Skill。

比如在 Claude Code 里，可以用 /skill-name 直接触发某个 Skill；在 Codex 里，可以用 $skill-name 的方式指定 Skill。

这种方式适合你已经明确知道要用哪个 Skill 的情况。手动触发属于客户端提供的交互方式，不是 Agent Skills 规范统一规定的语法。不同工具支持方式可能不同。

Skill 的两种内容类型：参考型内容与任务型内容

从内容性质看，Skill 里常见两类内容：参考型内容 和 任务型内容。

这个区分能帮我们判断：哪些内容给 Agent 提供背景知识，哪些内容让 Agent 按步骤执行。

参考型内容

参考型内容解决的是：Agent 需要知道什么。

它是一组可被 Agent 使用的背景知识，比如：API 设计规范、公司编码规范、品牌文案规范、报销规则、行业术语解释和领域知识。

以发票处理 Skill 为例，报销规则、发票字段说明，就属于参考型内容。

那它和普通文档、提示词、AGENTS.md 有什么区别？

区别在于，参考型 Skill 不是一份"等着被查看的资料"。它带着 description，能在合适任务里被 Agent 调用。

它也不是 AGENTS.md 的替代品。AGENTS.md 适合常驻规则，参考型 Skill 适合按需加载的知识。

任务型内容

任务型内容解决的是：Agent 应该怎么做。

它像操作手册，会写清楚步骤、检查项、输出格式和异常处理方式。

以发票处理 Skill 为例：

1. 提取发票号码、日期、金额等字段。
2. 检查字段是否缺失。
3. 根据报销规则判断是否符合要求。
4. 输出整理结果和需要补充的信息。

任务型内容和普通 Prompt 的区别也很明显：Prompt 服务当前这次对话；任务型 Skill 是把一套反复出现的做法沉淀下来，让 Agent 后面遇到同类任务时继续使用。

它也不适合长期塞进 AGENTS.md。AGENTS.md 适合全局规则，任务型 Skill 放那些只在特定任务里才需要的流程。

如何组织复杂 Skill：让 SKILL.md 保持简洁

SKILL.md 是入口，不是仓库。

Agent 激活某个 Skill 后，会读取整个 SKILL.md。主文件太长，不仅浪费上下文，也会让核心流程变得不清楚。

官方也建议把主 SKILL.md 控制在 500 行以内；接近这个长度时，就应该考虑拆文件。

原则：SKILL.md 放核心说明；长资料、模板和脚本，放到对应目录里，需要时再读取或调用。

SKILL.md 放什么

SKILL.md 只放核心说明，比如用途、核心执行流程、关键规则、什么时候读取参考资料、什么时候调用脚本。

不适合放完整 API 文档、大量案例、很长的背景资料、复杂模板。

长资料放到 references/

如果某些资料很长，但不是每次都要完整读取，就放到 references/。

比如：

invoice-processing/
├── SKILL.md
└── references/
    ├── reimbursement-rules.md
    ├── invoice-fields.md
    └── edge-cases.md

但不要只在 SKILL.md 里丢一个路径。引用外部文件时，最好同时说明三件事：

• 什么时候读取
• 读取哪个文件
• 读取后能得到什么

不建议只写：

参考 references/reimbursement-rules.md。

可以这样写：

当需要判断发票是否符合报销规则时，读取 [报销规则](references/reimbursement-rules.md)，里面包含报销限制、金额规则和常见异常处理方式。

这样 Agent 不只是知道"有这个文件"，也知道什么时候该读，以及读它是为了解决什么问题。

模板和样例放到 assets/

固定输出格式、表格样例、报告模板，放到 assets/。

比如：

invoice-processing/
└── assets/
    ├── reimbursement-template.xlsx
    └── report-template.md

把稳定步骤写成脚本

如果某个步骤每次都一样，而且用代码更可靠，放到 scripts/。

比如：

invoice-processing/
└── scripts/
    └── check_amount.py

脚本适合做校验、转换、提取这类稳定操作。不要把需要大量判断的事情硬写成脚本。

Skill、Prompt、MCP 和 AGENTS.md 如何选择

这里用 AGENTS.md 代表 Agent 的常驻配置文件；在 Claude Code 里，对应的是 CLAUDE.md。

这几个概念容易混在一起，先用一张表区分：

类型	解决什么问题	典型场景
Prompt	当前这一次任务的临时要求	"这次只输出 3 条建议，不展开解释"
AGENTS.md	每次都应该知道的全局规则	项目结构、构建命令、代码风格
Skill	某类任务才需要的专项技能	发票处理、代码审查
MCP	连接外部工具和数据源	查数据库、调 API

最容易混的是 AGENTS.md 和 Skill：每次都要知道的，放 AGENTS.md；只有某类任务才需要的，做成 Skill。

Prompt 适合一次性要求。MCP 解决的是连接问题，让 Agent 接上外部工具和数据源。

如何判断一个 Skill 写得好不好

Skill 写完以后，至少用 2-3 个真实任务试一下。

重点看四件事：

• 触发是否准确：该用时能用上，不该用时不乱用；用户换一种说法，也能判断出来。
• 结果是否变好：和不用 Skill 相比，输出是否更稳定、更完整，错误是否更少。
• 边界是否能处理：字段缺失、规则不明确、输入不完整时，是否能按预期处理，而不是自行假设。
• 成本是否值得：增加的上下文和 token，是否换来了足够明显的质量提升。

发现问题后，就按问题类型修改：

• 触发不准 ：改 description。
• 步骤不清 ：改 SKILL.md 正文。
• 资料太长 ：拆到 references/。
• 输出不稳定：补充示例、格式要求或边界条件。
• 重复操作太多 ：考虑放进 scripts/。

Skill 不是一次写完的，而是用真实任务慢慢打磨出来的。

小结：把经验变成可调用的能力

Agent Skills 最初由 Anthropic 提出，后来以开放标准的方式发布。现在，越来越多 Agent 产品开始支持这个格式，Agent Skills 官网也有 Client Showcase，列出了已知支持的产品。

Skill 的价值，是把一类任务的知识、流程和工具整理成能力单元，让 Agent 不必把所有内容常驻在上下文里，而是在合适的时候找到并使用对应能力。

AGENTS.md 放常驻规则，Prompt 处理当前这一次请求，MCP 连接外部工具和数据源。Skill 则用来沉淀那些反复出现、但不需要每次常驻的专项技能。

如果你总是在同类任务里反复解释同一套做法，就说明这套经验已经值得被保存下来。把它做成 Skill，就是把一次性的说明，变成可复用、可维护、可迁移的能力。

本篇说的是通用 Agent Skills。后面会聊 Claude Code 里的 Skill：它在这个通用标准之上，扩展了哪些额外功能。

公众号：澄旭