Agent Skills教程：把经验变成可调用能力

文章导航目录：

1. 为何需要 Skill——痛点与价值
2. Skill 到底是什么
3. Skill 的核心结构：SKILL.md 与可选目录
4. Skill 应该存放在哪里
5. 哪些内容适合封装为 Skill
6. 如何从零创建一个 Skill
7. Skill 的调用机制详解
8. 两种内容形态：参考型 vs. 任务型
9. 复杂 Skill 的组织策略：保持 SKILL.md 精简
10. Skill、Prompt、MCP 与 AGENTS.md 的选型指南
11. 如何评估一个 Skill 的质量
12. 总结：将经验转化为可复用的能力单元

任何一个持续运转的团队，都会不断积累各种规范、经验和文档：编码规范、接口契约、合规条款、文档模板、历史踩坑记录……这些都是极具价值的组织资产。

要让 AI 理解这些信息，最直接的办法就是一股脑塞进 AGENTS.md（在 Claude Code 中对应 CLAUDE.md，下文统一使用 AGENTS.md）。这类文件在对话启动时即被加载进上下文，天然适合存放项目结构、编码风格、构建命令、长期约定等全局性规则。

但把所有内容都塞进去并不现实。文件过长不仅拉慢响应速度，更致命的是，真正相关的规则容易被大量无关信息淹没，导致 Agent 无法聚焦关键指令。

那么，这些文档到底应该如何传递给 AI？这就引出了今天的核心概念——Skill。

Skill 面向“专项能力”，核心思路是让 Agent 在恰当的时机按需调用。想象一个技能包，它将某个场景所需的流程、参考资料、模板和脚本打包在一起：流程指引 Agent 具体怎么做，参考资料和模板提供参照，脚本负责那些更适合自动化的步骤。这样一来，一套经验就不再是某次对话中用完即弃的提示词，而是可以保存、复用、维护、纳入版本管理，甚至可以迁移到其他支持 Skill 的 Agent 中。下次遇到同类任务，Agent 直接调用即可，无需每次都从头解释一遍。

为何需要 Skill

一个团队里充斥着大量规范、经验和文档：编码规范、接口规范、合规要求、文档模板、历史踩坑记录等。

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

但如果什么内容都往里塞，问题会迅速暴露：响应变慢只是一方面，更麻烦的是，真正关键的规则可能被一大堆无关信息淹没。

那么，这些文档到底该如何交给 AI 呢？

Skill 专为专项能力而生，让 Agent 在合适的场景按需调用。它将某个场景所需的流程、参考资料、模板和脚本封装成能力包：流程告诉 Agent 如何执行，参考资料和模板提供依据，脚本负责那些更适合自动化的步骤。

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

Skill 到底是什么

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-processingdescription: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当用户需要处理发票或准备报销材料时，使用此 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 放置在：

/.agents/skills//SKILL.md

用户级 Skill 放置在：

~/.agents/skills//SKILL.md

不过也有客户端使用自己的目录约定。例如 Claude Code 使用：

/.claude/skills//SKILL.md~/.claude/skills//SKILL.md

如果某个客户端有自己的目录，就将 .agents/skills/ 中的 Skill 通过软链接接入。

例如项目实际维护的是：

.agents/skills/invoice-processing/

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

mkdir -p .claude/skillsln -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-processingdescription: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当用户需要处理发票或准备报销材料时，使用此 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 的场景。手动触发属于客户端提供的交互方式，并非 Agent Skills 规范统一规定的语法。不同工具的支持方式可能不同。

两种内容形态：参考型 vs. 任务型

从内容性质来看，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 的选型指南

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

类型	解决什么问题	典型场景
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：它在这个通用标准之上，扩展了哪些额外功能。

来源：互联网