一文带你了解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写得越好，大模型判断何时该用这个技能就越准确。等到确认需要了，再加载完整的指令正文。可以说，

。

它把“能力识别”和“实际执行”这两件事解耦了。这样一来，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天然适合存放这些东西：传递参数的详细示例、字段和结构定义、复杂的规则说明。换句话说，

。这种拆分方式，让Skill在执行时具备了“渐进式披露”的能力——既保证了执行准确性，又最大限度减少了无用信息对上下文的占用。

Script

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

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

总结

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