构建智能体技能：从文件夹结构到测试·共享

技能是什么，为什么需要

Anthropic 工程博客文章（w1）这样指出问题：模型再聪明，实际工作也需要“在这家公司按这个顺序做”之类的流程知识和组织背景。为填补这一点而设计的就是技能（Agent Skills）。技能是整理好指令·脚本·资料的文件夹，由智能体自行查找并在需要时加载。该文章把编写技能比作为新员工编写入职指南。

它与平常使用的提示词用途不同。Claude 官方文档（w4）把提示词界定为用于一次性任务的对话级指令，把技能界定为按需加载的可复用资源。写好技能后，就不必在每次对话中反复粘贴同样的说明。Anthropic 提供了适用于 PowerPoint·Excel·Word·PDF 的内置技能，并表示自建技能可在 Claude Code、API 和 claude.ai 设置中使用（w4）。

技能也不是绑定在某个产品上的格式。Anthropic 于 2025 年 12 月将 Agent Skills 作为可在多个平台使用的开放标准发布（w1），公开规范（w3）规定了文件夹结构和字段规则。Simon Willison 的文章（w6）也指出，没有任何机制阻止其他模型使用技能。

技能文件夹的组成部分

根据 Agent Skills 规范（w3），技能至少是一个包含 SKILL.md 文件的文件夹。在此基础上，可选择性地加入存放可执行代码的 scripts/、存放参考文档的 references/，以及存放模板·图片·数据文件等静态资源的 assets/。这三者都只是推荐惯例，需要时也可以放入其他文件或文件夹。

SKILL.md 必须以 YAML frontmatter（文件最顶部的配置块）开头，必填字段是 name 和 description 两个（w1, w3）。规范（w3）还规定了可选字段：写明许可证的 license、用 500 字符以内说明所需运行环境的 compatibility、存放任意键值对的 metadata，以及列出预先允许的工具的 allowed-tools（实验性功能）。规范补充说，大多数技能不需要 compatibility。

frontmatter 下面的正文是 Markdown，没有格式限制。规范（w3）建议写入分步指令、输入·输出示例和常见的边界情况。scripts/ 中的代码应能独立运行或明确列出所需的库，并给出易于理解的错误信息。references/ 中的文件应聚焦单一主题、保持小巧，因为智能体会在每次需要时读取这些文件。

渐进式披露：分三个阶段读取

技能设计的核心是渐进式披露（progressive disclosure）。第 1 阶段是元数据。智能体启动时把所有已安装技能的名称和描述预先放入系统提示词（w1），每个技能约占 100 token（w3, w4）。Simon Willison（w6）的说法是每个技能只多占几十个 token。第 2 阶段是 SKILL.md 正文。用户请求与描述匹配时才读取，官方文档建议少于 5,000 token（w3, w4）。

第 3 阶段是文件夹中的参考文件和脚本。在 Anthropic 工程博客文章（w1）的 PDF 技能示例中，SKILL.md 只按名称指向 reference.md 和 forms.md。由于表单填写方法单独放在 forms.md 中，Claude 只在填写表单时才读取该文件。脚本则更轻量。根据 Claude 官方文档（w4），脚本通过 bash 执行，代码本身不进入上下文，只有其输出进入。

因此即使安装了很多技能，在实际使用之前，占用上下文窗口的也只有名称和描述（w4）。工程博客文章（w1）据此说明，技能可打包的资料量实际上没有限制。不过，这种方式需要智能体能够读取文件系统并执行命令的环境才能运作（w4, w6）。

设计原则：名称·描述·篇幅·自由度

先确定名称。按规范（w3），name 不超过 64 个字符，只能使用小写字母·数字·连字符。不能以连字符开头或结尾，不能连续使用连字符，并且必须与文件夹名称相同。Claude 编写指南（w2）在此基础上还禁止使用“anthropic”“claude”等保留词。名称建议采用 processing-pdfs 这样的动词-ing 形式，避免 helper·utils·data 这类笼统的名称。

描述（description）决定技能是否会被实际使用。编写指南（w2）指出，Claude 会根据这段描述从可能超过 100 个的技能中选出一个。因此建议同时写明做什么和何时使用，并加入用户可能提到的关键词。描述会原样进入系统提示词，所以必须用第三人称，而不是“I can help you…”这样的第一人称。规范（w3）把“Helps with PDFs.”作为反例，把写明 PDF 文本·表格提取和表单填写、并注明“当用户提到 PDF 或表单时使用”的句子作为正例。

篇幅越短越好。编写指南（w2）把上下文窗口称为与系统提示词、对话记录和其他技能共用的公共资源，并要求以“Claude 已经很聪明”为基本前提。它认为，只保留库名和代码的约 50 token 示例，优于连 PDF 是什么都要解释的约 150 token 示例。规范（w3）建议把 SKILL.md 控制在 500 行以下，把详细内容移到单独文件中，并且从 SKILL.md 只经一层引用。工程博客文章（w1）补充说，把不会同时用到的内容拆到不同文件里，可以节省 token。

指令写得多具体，取决于任务有多容易出错。编写指南（w2）把自由度分为三级。像代码审查这样多种做法都可能正确的，只用文字给出大方向。有偏好的模式时，给出伪代码或带参数的脚本。像数据库迁移这样必须严格遵守顺序的，就给到“原样执行这条命令”的程度。该文档把这比作两侧都是悬崖的窄桥和开阔的田野。是否加入脚本的标准也类似。工程博客文章（w1）解释说，像列表排序这样靠生成 token 来做代价高昂的事，以及必须始终得到相同结果的事，用代码更好。它还建议写清 Claude 应该直接执行脚本，还是作为参考阅读。Simon Willison（w6）也写道，只有在脚本更可靠或更高效时才加入。

首次构建的步骤

第一，从评估开始。工程博客文章（w1）建议用代表性任务运行智能体，查看它在哪里卡住或需要更多背景，然后逐步编写技能来填补这些缺口。不要从笼统觉得“有了会不错”的技能做起。

第二，先写 name 和 description。这两行决定技能是否会被使用。第三，正文只简短写入模型不知道的公司特有流程、固定命令和常见错误。第四，正文变长或出现只在特定情况下才需要的内容时，移到 references/。必须按规定执行的任务放进 scripts/。第五，用规范（w3）介绍的 skills-ref validate 命令检查 frontmatter 格式和命名规则。

第六，在所有要使用的模型上测试。编写指南（w2）指出，技能的效果因底层模型而异，建议确认对 Haiku 说明是否足够、对 Opus 解释是否过度。第七，观察实际使用情况。工程博客文章（w1）建议留意出乎意料的轨迹（智能体所走的工作路径），或过度依赖某个特定文件的情况。并建议让 Claude 把成功的方法和常见错误整理进技能，任务偏离时让它反思哪里出了问题。这样就能实际找出所需的背景，而不是事先猜测。

检查清单

先检查格式。SKILL.md 是否以 YAML frontmatter 开头？name 是否与文件夹名称相同，且只使用小写字母·数字·连字符（w3）？description 是否非空、不超过 1,024 个字符，并用第三人称写明做什么和何时使用（w2, w3）？

检查篇幅和结构。正文是否在 500 行以下（w3）？是否去掉了模型已知的通用说明，并推敲过“这一段是否值得占用这些 token”（w2）？是否从 SKILL.md 以一层、相对路径指向参考文件（w3）？不会同时用到的内容是否拆分到不同文件（w1）？

检查脚本和行为。每个脚本是否注明用于执行还是供参考（w1）？所需的库和错误信息是否清晰（w3）？是否在实际要用的各个模型上测试过（w2）？如果是来源陌生的技能，安装前是否检查过文件内容、代码依赖，以及是否有连接外部网络的指令（w1）？

常见错误、安全，以及与 MCP·子智能体的区别

常见错误可归为几类。描述像“Helps with documents”那样含糊，导致技能不被调用（w2, w3）。用第一人称或第二人称写描述，造成技能查找混乱（w2）。冗长地铺陈模型已知的内容，浪费 token（w2）。参考文件再指向其他文件，形成很深的链条（w3）。只在一个模型上测试（w2）。

安全需要单独重视。工程博客文章（w1）警告，恶意技能可能向环境引入漏洞、窃取数据，或诱导 Claude 做出非预期的行为。因此建议只安装来自可信来源的技能，其他技能要仔细审计文件内容后再使用。Simon Willison（w6）指出，技能依赖执行代码的环境，因此能减轻提示注入等攻击危害的沙箱很重要。团队共享技能时，把这一审计流程定为共同规则也更安全。

它与 MCP 的作用不同。MCP 是连接外部工具和数据的协议。工程博客文章（w1）表示，将探索让技能教授使用外部工具的复杂工作流程、以此补充 MCP 服务器的方向。Simon Willison（w6）认为，技能依赖文件系统和命令执行环境，这是与 MCP 最大的区别。他还举例说，仅 GitHub 官方 MCP 一项就占用数万 token 的上下文，而技能只在需要时读取详细内容，这一负担较小。这是他的个人观点。

本次输入资料没有直接讨论子智能体，因此只写一般性的区分。子智能体是主智能体委派工作的独立智能体，在自己的上下文中完成工作后返回结果。技能不会新建智能体，而是当前工作的智能体在需要时读取的知识和工具包。因此，要划分“谁来做”就考虑子智能体，要教授“怎么做”就考虑技能。

延伸学习

先读 Anthropic 工程博客文章（w1），可以一次性了解技能为何出现、渐进式披露如何运作，以及构建和评估的要点。接着看 Claude 官方概述文档（w4）中的分阶段加载表和 PDF 技能加载示例，就能体会到实际进入上下文的是什么。

动手构建时，把 Claude 技能编写指南（w2）和 Agent Skills 规范（w3）放在手边。编写指南提供简洁性、自由度、名称·描述写法等判断标准。规范提供字段规则、文件夹惯例和验证工具。最后，Simon Willison 的文章（w6）从开发者视角展示了技能与 MCP 有何不同，以及真实的技能是什么样子。