Agent 技能

它是什么

Agent 技能是一种把程序性知识打包的开放格式：它回答「这件事该怎么做」，而不是「能访问什么」。

它的核心定义很朴素——一个技能就是一个文件夹，里面至少有一个 SKILL.md：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
├── assets/           # 可选：模板与资源
└── ...               # 任意其它文件或目录

SKILL.md 由 YAML frontmatter 加一段 Markdown 正文组成。frontmatter 里必填两项：name（最多 64 字符，只允许小写字母、数字与连字符，且必须与父目录同名）和 description（最多 1024 字符，要同时说清「它做什么」和「什么时候用它」）。可选项包括 license、compatibility（环境要求，最多 500 字符）、metadata，以及实验性的 allowed-tools。

它是一个文件夹，不是一个提示词，也不是一项模型能力。

为什么需要它

团队里那些「每次都要重新交代一遍」的事——周报的格式、代码评审的口径、财务表格的填法——过去只能活在三种地方：某个人的脑子里、一份没人读的文档里、或者每次对话开头粘贴的一大段提示词里。

前两种会流失，第三种有硬成本：它占掉每一次对话的上下文预算，而且改一次要改所有用过的地方。

Skill 把这笔账换了算法：元数据常驻、正文按需加载。未激活时，模型只看得到每个 Skill 的名字和描述（规范给出的量级是约 100 token）；只有任务与描述匹配时才读全文。这就是「为什么能装几十个 Skill 而不撑爆上下文」的答案——也是它和「长提示词」最本质的分界。

它如何工作

机制叫渐进式披露（progressive disclosure），规范把它分成三级：

1. 元数据（约 100 token）：所有 Skill 的 name 与 description 在启动时加载——够判断它可能相关就行。
2. 指令（建议少于 5000 token）：命中任务后，整份 SKILL.md 正文被读进上下文。
3. 资源（按需）：scripts/、references/、assets/ 里的文件只在需要时才被读。

对应的写法约束也是硬性的：规范建议 SKILL.md 正文控制在 500 行以内，更细的参考资料移到 references/；引用文件保持从 SKILL.md 出发一层深度，不要做深层嵌套。

被激活之后，SKILL.md 的正文会和对话历史、系统上下文、其它已激活的 Skill 一起挤在同一个上下文窗口里——所以「省着花上下文」不是风格建议，而是这个格式的运作前提。官方的最佳实践给了一条很实用的删减标准：逐条自问「要是没有这句，模型会不会做错？」答案是「不会」就删掉。

必须澄清的误会

Skill ≠ Prompt。 提示词是单次对话里的一次性指令，说完就没了；Skill 是跨会话存在的文件夹，有元数据、有激活条件、可以携带脚本与模板。两者最容易被忽略的差别是加载时机：提示词是「你每次都得贴」，Skill 是「条件命中才加载」。如果你发现自己在不同的会话里反复粘贴同一段说明，那正是应该做成 Skill 的信号。

Skill 与 MCP 互补，不是竞争。 两者管的是不同的事：MCP 解决「模型能碰到哪些工具与数据」——那是访问权限；Skill 解决「碰到之后该按什么做法用」——那是做法。所以决策规则很简单：缺访问权限就加工具，缺做法就加 Skill。真要同时用，最直观的组合是——一个 MCP Server 把内部数据库的工具暴露出来，一个 Skill 告诉模型「查我们的订单表要先看 schema、金额字段是分不是元、软删除的行要过滤掉」。少了前者什么都查不到，少了后者每次都查错。

还有一句要单独说：Skill 不给你任何新的安全边界。它能做的事，取决于它被放进哪个 Agent 运行、那个 Agent 手里有什么工具。

真实例子

一个可复制的做法来自官方最佳实践的建议：从一次真实任务里把模式抽出来，而不是凭空设计。

具体操作是——先和 Agent 完整做完一件真实的事，过程中该给的上下文给、该纠正的纠正（「这个项目用 X 不用 Y」「记得检查 Z 这种边界」）；做完之后回看这次对话，把四类东西抽出来写成 Skill：走通的步骤顺序、你做过的纠正、输入输出的格式、你补充的项目特有约定。

这样抽出来的 Skill 有一个可验证的好处：它的每一条内容都是「模型不知道、而你知道」的东西，天然符合上面那条删减标准。反过来，如果抽出来的内容是「PDF 是一种常见的文件格式」这类模型本来就知道的话，那说明抽取时抄错了对象。

同时建议对 description 单独花时间：规范说它应该同时描述「做什么」与「什么时候用」，并包含能让模型识别相关任务的关键词。Skill 被触发得准不准，几乎全押在这一段上。

什么时候适合与不适合

适合：一类任务你会重复做，而且做法里有「不说就一定会做错」的项目特有约定。也适合把某个人的隐性经验变成团队资产——这是它相比「写一份文档」最大的优势：文档没人读，Skill 会被模型在需要时主动读。

不适合：只做一次的事，写 Skill 的成本收不回来。以及，如果 Agent 本来就能把这件事做好，这个 Skill 可能根本不增加价值——最佳实践里明确提到过这一点，值得在动手前先测一次。

颗粒度是更要紧的判断。官方给的类比是「像决定一个函数该做什么」：scope 太窄会让一个任务要加载好几个 Skill，既有开销又有互相冲突的指令；scope 太宽则很难被精确触发。一条可用的界是「查数据库并格式化结果」算一个完整单元，而「顺带还管数据库运维」就过宽了。

安全边界要单独说：Skill 会携带可执行脚本，也可以指示模型调用工具，所以它在事实上等同于可执行代码。第三方 Skill 应该按不可信代码对待——行为可能与它声称的用途不符，描述也可能不准确。装之前通读它的 SKILL.md 与 scripts/，必要时先在隔离环境里跑一次。这跟 提示词注入 是同一类风险面：内容一旦进入上下文，就可能影响模型的下一步动作。

亲自试一下

挑一件你真的反复交代的事（最容易上手的是「本团队周报的固定格式」），写一个 20 行左右的 SKILL.md：name 用目录名，description 里写清做什么和什么时候用，正文给出步骤与一个输出模板。

然后做对照测试——这一步比写本身更值得花时间：

1. 在同一次会话里先问一个与它明显无关的问题，观察它有没有被加载。
2. 再问一个正好落在描述范围内的问题，观察它是否被读进来。

全程约 20 分钟。观察点是「触发条件」，不是「输出质量」——你要确认的是「它什么时候进来」，而不是「它答得好不好」。如果两次都进来了，说明 description 写得太宽；如果该进来时没进来，就把描述里缺的关键词补上。调这一个字段，通常比改正文更能提升实际效果。

接下来学什么

Skill 是这一站（给流程）的入口概念——它和 提示词模板、提示链 一起回答「怎么把做法沉淀下来」。

如果你还没搞清楚「工具是怎么被接进来的」，那是上一站的事，先读 模型上下文协议（给接口）。如果你的 Skill 要指示模型自动执行多步动作，下一站是 给判断——先有评测集，才谈得上「它变好了」。

来源与修订

格式细节（目录结构、frontmatter 字段与字符限制、渐进式披露的三级 token 量、500 行建议）全部来自 Agent Skills Specification；写法建议（从真实任务抽取、删减标准、按函数思考颗粒度、description 决定触发）来自官方 Best practices for skill creators。两份都是讲这个格式本身的规范与官方指引。

需要说明的一处边界：「第三方 Skill 视为不可信代码」这段是本站的操作性建议，不是规范原文——规范文档里没有安全章节。我们把它写在这里，是因为这个格式允许携带可执行脚本，而这个风险在没有提醒的情况下不会自己浮现。

新增日期 2026-09-19（本词条为新建）。Agent Skills 格式由 Anthropic 提出并作为开放标准发布，现已被一批 Agent 产品采纳；若格式版本更新，应先核对上述两份来源再修订。