Agent Skills核心解读 一文掌握所有要点

什么是Agent Skills？

如今，几乎打开任何一个Agent框架，你都会看到“Skills”这个词。那么它究竟代表着什么？坦白来说，这个概念最近确实备受关注，其背后的推动者是Anthropic，目标是让智能体真正进入工程化阶段。

传统方法面临的问题

在Agent Skills出现之前，为Agent添加能力通常采用以下方式：

• 将每种工具的使用方法和示例全部塞进Prompt中，然后包装成Tool（通过Function call或MCP协议）交给大模型
• 封装成标准工具调用逻辑
• 或者直接固化在workflow流程里

这些方法在简单场景下确实够用，效果也不错。但一旦任务变得复杂、Agent数量增多，问题就会暴露出来：

• MCP和Function call会消耗大量上下文，Prompt迅速膨胀，token成本随之上升。更麻烦的是，大模型的注意力机制天生难以应对超长上下文，表现反而会下降。
• 能力难以复用——开发一个新Agent时，需要重新构建能力。
• 执行逻辑分散在各处，系统维护十分繁琐。
• 最关键的是，很多能力在当前任务中根本用不上，但它们占据的上下文却是实实在在的成本。

归根结底，这些问题的根源在于传统方法缺乏统一的能力抽象方式。而MCP的流行更加剧了上下文暴涨——每次集成多个MCP，都会同时引入大量工具。尤其是当多个MCP中包含相似工具时，Agent在选择工具时就会变得困惑。

Agent Skills的解决方案

Agent Skills正是为了解决这些问题而诞生的。它本质上是对Agent能力的一种统一抽象——将那些已经被验证有效的执行方式抽取出来，封装成独立的能力模块，让Agent在需要时直接调用，而不是每次都从头构建。

用做菜来比喻：传统方法就像把几十种食材和调料全摆在你面前，做一道菜需要从眼花缭乱的物料中自行挑选。而Skills就像菜谱，当你确定要做什么菜时，照着菜谱精确取用材料即可，省时省力且不易出错。

Skills的核心思想其实很朴素：将已被验证有效的做事方法抽象成独立的能力模块，让Agent在需要时自动加载并执行。这些模块具有几个显著优势：

• 可重复使用
• 可自由组合
• 可按需加载
• 便于持续维护

Agent Skills的构成

简单来说，一个Agent Skill就是一个标准化的目录结构。没错，就是文件夹。Skill的所有操作，都围绕着在该文件夹内新增文件和修改内容展开。

来看一个结构示例：

my-skill/		  # 技能名称
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

这是我在codex中安装的一个Skill的实际结构：

一个完整的Skill，至少包含一个核心文件——SKILL.md。其他所有文件都围绕它展开。这样设计的目的是明确的：让Agent在运行时能够分层、有选择地加载信息，而不是一口气把所有内容都塞进上下文。

SKILL.md详解

前面提到，一个完整的Skill至少需要有一个SKILL.md文件。这个文件的写法直接决定了Agent能否正确理解和使用该Skill。SKILL.md由两大部分组成：Frontmatter（元数据）和Instruction（指令正文）。

以上面名为doc的Skill为例，它的SKILL.md大致如下：

---
name: "doc"
description: "Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks."
---



# DOCX Skill

## When to use
- Read or review DOCX content where layout matters (tables, diagrams, pagination).
- Create or edit DOCX files with professional formatting.
- Validate visual layout before delivery.

## Workflow
1. Prefer visual review (layout, tables, diagrams).
   - If `soffice` and `pdftoppm` are a vailable, convert DOCX -> PDF -> PNGs.
   - Or use `scripts/render_docx.py` (requires `pdf2image` and Poppler).
   - If these tools are missing, install them or ask the user to review rendered pages locally.
2. Use `python-docx` for edits and structured creation (headings, styles, tables, lists).
3. After each meaningful change, re-render and inspect the pages.
4. If visual review is not possible, extract text with `python-docx` as a fallback and call out layout risk.
5. Keep intermediate outputs organized and clean up after final approval.
......

可以看到，最上面被---包围的部分就是元数据。Agent在加载Skill之前，只能看到这一小块数据。剩下的都是指令正文，仅当Skill被正式加载后，Agent才能看到。

元数据（Frontmatter）

元数据的格式有明确规范，必须写在文件顶部，并且必须包含两个属性：

• name：Skill的唯一标识，Agent依靠它来识别技能
• description：简要说明该技能的用途以及适用场景

---
name: "doc"
description: "Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks."
---

这段描述表明：该Skill的唯一标识是doc，当任务涉及读取、创建或编辑.docx文档时（尤其是对格式或布局有较高要求时），就应该调用它。同时还提到了可以使用scripts中的脚本进行检查。

这种设计的核心目标非常清晰：在不确定是否需要调用该技能时，最大程度地压缩上下文尺寸。而且description写得越精准，大模型判断何时该使用这个技能就越准确。等到确认需要后，再加载完整的指令正文。可以说，元数据是Agent Skills实现工程化运作的基石。

它把“能力识别”和“实际执行”这两件事解耦了。这样一来，Skill就不再是一次性的Prompt，而是一个可以被检索、匹配、延迟加载的能力单元。

指令正文（Instruction）

---后面的部分就是完整的指令正文。元数据解决的是“要不要用这个Skill”以及“这个Skill是做什么的”问题，而指令正文解决的是“这个Skill具体该如何使用”的问题。

回看前面的例子，指令正文中会写明适用的具体场景、详细的操作步骤、对Agent行为的显式约束等。当Agent确认当前任务需要该Skill后，才会将这部分内容加载进上下文。

指令正文主要承担以下几项职责：

• 明确使用时机和适用边界，防止Skill被误用
• 将复杂任务拆解成稳定、可复现的执行步骤
• 显式约束Agent的行为方式，减少自由发挥和幻觉
• 为后续的Script、Reference提供清晰的使用说明和调用指引

因此，Instruction本质上是一份面向专业领域、特定功能的高质量Prompt。不过需要注意：像详细示例、字段定义、复杂规则这类长上下文的内容，官方并不建议全部堆在SKILL.md里。它们更适合通过Reference按需补充、按需加载，再配合Script来承载可执行的逻辑。

References

在前面展示的文件夹结构中，有一个References文件夹。它是可选的，但往往很重要。它所解决的问题是：当Skill本身比较复杂时，为Agent提供必要的补充信息。这些数据同样不会在Skill发现阶段加载，而是按需加载。只有指令正文中明确指示，或者执行过程中需要查询某些细节时，Agent才会主动读取其中的文件。

因此，References天然适合存放以下内容：传递参数的详细示例、字段和结构定义、复杂的规则说明。换句话说，指令正文负责告诉Agent这个Skill应该怎么做，而References负责在Agent需要时补充Skill的细节。这种拆分方式，让Skill在执行时具备“渐进式披露”的能力——既保证了执行准确性，又最大限度减少了无用信息对上下文的占用。

Script

Script也是可选组件，用于承载那些不适合交给大模型自由生成的确定性逻辑。里面通常放置Python脚本。例如前面那个doc skill中，就有一个render_docx.py脚本。

执行流程上，Agent会先根据SKILL.md中的指令做出决策，然后在合适的步骤里调用Script来完成具体操作。Script本质上就是一个工具执行脚本，专门处理特定任务。其主要目的是：让大模型不必考虑具体的实现细节，只需调用执行并获取结果即可。

总结

Agent Skills这套体系，其核心价值在于将“为Agent添加能力”这件事，从“一次性、硬编码、高消耗”的方式，转变为“模块化、可复用、按需加载”的标准工程范式。它不仅解决了上下文膨胀的问题，更重要的是让Agent的能力能够像积木一样自由组合并持续迭代。对于任何一个希望将Agent真正投入生产环境的团队来说，这都是一条值得认真研究的路径。