Anthropic 在工程文章《Equipping agents for the real world with Agent Skills》里，把 Agent Skills 讲成一种很朴素但很有扩展性的设计模式：用文件和文件夹，把程序性知识、参考资料和可执行工具打包给 Agent。
这套设计的重点不是“多一个插件市场”，而是解决一个更底层的问题：通用 Agent 如何在不被上下文淹没的前提下，获得特定领域的专业能力。
一、真实工作需要的不只是模型能力
Anthropic 开篇提到，随着模型能力提升，我们已经可以构建能操作完整计算环境的通用 Agent。Claude Code 就是一个例子：它能使用本地代码执行和文件系统，完成跨领域的复杂任务。
但问题也随之出现：Agent 越通用，越需要一种可组合、可扩展、可迁移的方式来获得领域知识。
真实工作通常依赖大量程序性知识：
- 这个 PDF 表单应该怎么识别字段；
- 这类 Excel 报表应该怎么生成公式；
- 这个团队的代码审查清单是什么；
- 公司品牌规范要求什么字体、颜色和语气；
- 发布流程里哪些步骤必须先做。
这些知识不是模型预训练里天然就有的。即使模型知道大概方法，也不知道你所在组织的具体流程和标准。
Agent Skills 的目标，就是把这些知识打包成 Agent 可以发现、加载和执行的能力。
二、Skill 的最小结构：一个目录和一个 SKILL.md
Anthropic 给出的最小 Skill 结构很简单：一个目录，里面有一个 SKILL.md 文件。
SKILL.md 必须从 YAML frontmatter 开始，包含至少两个关键信息：
---
name: pdf
description: Work with PDF files, including reading, extracting fields, and filling forms.
---name 和 description 的作用非常重要。Agent 启动时，会把所有已安装 Skill 的名称和描述预加载到系统提示里。
这意味着：Claude 一开始并不会读取所有 Skill 的完整内容，它只知道“有哪些 Skill”以及“它们大概适合什么任务”。
当用户请求和某个 Skill 匹配时，Claude 才会读取对应 Skill 的完整 SKILL.md。
所以，description 不是给人随便看的简介，而是 Agent 判断是否调用 Skill 的触发条件。一个模糊的 description，会直接影响 Skill 是否被正确触发。
三、核心设计原则：渐进式披露
Anthropic 明确说，Progressive disclosure 是 Agent Skills 灵活和可扩展的核心设计原则。
可以把它理解成三层结构。
第一层：Skill 的名称和描述。
这一层在启动时进入上下文，让 Agent 知道有哪些能力可用。
第二层：SKILL.md 正文。
当 Agent 判断某个 Skill 与任务相关时，读取完整的 SKILL.md，获得操作流程、注意事项、资源索引和执行要求。
第三层：Skill 目录里的其他文件。
当 SKILL.md 指向更详细的文件时，Agent 可以按需继续读取，例如 reference.md、forms.md、examples.md，或者执行 scripts/ 里的脚本。
用一个简单结构表示就是：
启动时加载：name + description
任务匹配后：SKILL.md
需要细节时：reference.md / examples.md / scripts/*这个设计看起来简单，但非常关键。它让 Skill 可以携带大量上下文，却不必一次性把所有内容塞进模型窗口。
四、为什么渐进式披露适合 Agent
Agent 做真实任务时，经常需要在多个能力之间切换。如果每个能力都把全部文档预先加载，系统很快就会遇到三个问题。
第一，上下文窗口被占满。大量不相关材料会挤掉真正重要的任务上下文。
第二，模型更容易分心。上下文越杂，模型越可能把无关规则误用到当前任务。
第三，维护成本上升。所有规则都挤在一个大文件里，更新和审查都会变困难。
渐进式披露的好处是：Skill 可以很大，但进入当前任务上下文的内容可以很小。
这也是为什么 Anthropic 把 Skill 比作一本组织良好的手册：先有目录，再有章节，最后才是附录。Agent 不需要每次读完整本手册，只需要在任务需要时翻到相关章节。
五、文件夹为什么是一个好抽象
Agent Skills 选择“文件夹”作为能力边界，这个决定很朴素，但工程上很稳。
文件夹天然适合组织多种材料：
my-skill/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
└── helper.py这种结构有几个好处。
第一，容易阅读。人可以直接打开目录看清楚这个 Skill 包含什么。
第二，容易版本管理。Skill 可以跟代码一样进入 Git，做 review、diff 和回滚。
第三，容易迁移。整个目录可以复制、发布、安装到不同环境。
第四，容易扩展。开始时只有一个 SKILL.md，复杂后再拆出参考文档、示例和脚本。
这比把所有能力藏在数据库配置、产品 UI 表单或一段超长 Prompt 里更透明。
六、脚本让 Skill 从“会说”变成“会做”
Anthropic 在工程文章中专门讲了 Skills and code execution。
大模型适合理解意图、拆解任务、选择路径，但有些操作更适合传统代码。比如排序、解析文件、提取表单字段、校验结构、生成图片或批量处理数据。
如果让模型用自然语言“猜”这些结果，成本高且不稳定。如果把它们写成脚本，Agent 就可以在合适的时候运行脚本，得到确定性结果。
以 PDF Skill 为例，Anthropic 提到可以在 Skill 中包含一个预写好的 Python 脚本，用来读取 PDF 并提取所有表单字段。Claude 可以运行这个脚本，而不需要把脚本源码或整个 PDF 都加载进上下文。
这带来两个价值：
- 效率更高：大文件和复杂计算不必全部进入模型窗口；
- 结果更稳：确定性任务由代码处理，模型负责决策和编排。
这也是 Agent 系统设计中的一个重要分工：模型负责判断该做什么，代码负责把确定性的部分做准。
七、Skill 和 MCP 的关系
Anthropic 在未来规划里提到，Skills 可以和 MCP 互补。
简单理解，MCP 更像是把外部工具、数据源、服务能力接进 Agent；Skills 更像是教 Agent 如何使用某类工具、遵循某套流程、执行某种工作方法。
举个例子：
- MCP 提供“访问工单系统”的工具；
- Skill 提供“处理线上事故工单的流程、字段规范、升级规则和复盘模板”。
两者不是替代关系。MCP 解决“能连上什么”，Skills 解决“连上以后怎么做”。
这对企业 Agent 很重要。很多失败的 Agent 并不是没有工具，而是不知道如何按组织流程正确使用工具。
八、一个 Skill 应该解决什么问题
不是所有提示词都值得做成 Skill。
Claude Code 文档给了一个很实用的判断标准：当你反复粘贴同一段说明、清单或多步骤流程，或者 CLAUDE.md 里的某一段已经从事实说明变成了操作流程，就适合把它做成 Skill。
也就是说，Skill 特别适合沉淀这些内容：
- 重复出现的多步骤流程；
- 容易遗漏的检查清单；
- 需要配套脚本的文件处理任务；
- 团队独有的工作规范；
- 需要按场景加载的大段参考资料。
反过来，如果某个信息很短、全局都需要、几乎不会变化，放在项目说明或系统规则里可能更合适。
九、设计模式小结
Agent Skills 的设计模式可以概括成一句话：
用文件夹封装能力，用
description触发能力，用SKILL.md导航能力，用补充文件承载细节，用脚本执行确定性操作。
这个模式的厉害之处，不在于格式复杂，而在于边界清晰。
它把 Agent 能力拆成几个可维护的部分：
- 触发层：名称和描述；
- 指令层：
SKILL.md； - 知识层：参考资料、示例、模板；
- 执行层：脚本和工具；
- 分发层：目录、Git、插件或组织级管理。
当这些部分组合起来，Agent 就不再只是“临场发挥”，而是能带着团队沉淀下来的工作方法去完成任务。
下一篇，我们继续整理 Anthropic 给出的最佳实践：如何从评测开始，如何拆分 Skill 文件，如何从 Claude 的视角写描述，以及如何审查安全风险。