本文由 莫潇羽@源码七号站(www.fuyuan7.com)撰写,转载请注明出处。

快速摘要

Agent Skills 是 Anthropic 在 2025 年底推向主流视野的智能体能力扩展机制。一句话说清楚:它把一个领域的标准作业流程(SOP)、参考资料、可执行脚本打包成一个"技能文件夹",智能体在真正用得到的时候才会逐层加载。 它解决的是过去我们写超长提示词带来的三个老毛病——上下文窗口被撑爆、注意力涣散、工具调用混乱。本文按"原理拆解—结构剖析—编写规范—六条铁律—端到端实战—多平台适配—踩坑提示"的顺序一次说透,核心实战部分会落到一个真实可跑的"会议总结助手"案例:用户丢进去一段开会的对话记录,Skill 自动产出标准化纪要、按需引用公司财务手册做合规提醒,再调用脚本把纪要同步到云端。同一份 Skill 不改一行代码,在 Claude Code、Trae、CodeBuddy、Codex、OpenCode 上都能跑起来,这也是 Skills 比 MCP、比 Function Calling 更值得投入时间的根本原因。如果你最近在折腾智能体却始终卡在"能跑但不稳"那一步,这篇就是为你写的。想看完整拆解,往下翻。

一、提示词工程到了天花板,Skills 才是下一站

我最初做智能体的时候踩过一个特别经典的坑。给一个对话助手写系统提示词,洋洋洒洒堆了快两千字,角色、口吻、知识范围、不允许做什么、要遵循的格式、调用工具的判断条件,通通塞进去。本地跑几个简单测试,效果看着不错。真把它放到一个稍微复杂点的业务流里——客户问了一个跨场景的问题,要先查订单,再判断状态,再决定推什么话术——它当场就懵了,要么忽略掉某个关键判断,要么把不该调的工具叫了一遍,要么输出格式跑偏。

折腾几轮我才意识到一个事:这不是提示词写得不够好,而是单靠一段长文本去控制多维度、非线性的复杂工程逻辑,本身就是个错配。

1.1 长提示词的三个固有缺陷

把这个错配拆开看,有三个非常具体的问题。

第一个是注意力稀释。 大模型底层是 Transformer 的注意力机制,这一点接触过原理的朋友都熟悉。注意力是一种有限资源,上下文越长,模型对每一段信息分配到的"心思"就越少。你可能感觉它读完了你那两千字的提示词,但真到推理的时候,中间那部分的细节经常被吃掉。这就是大家在长对话里偶尔看到模型突然"忘了之前的设定"的根因。

第二个是步骤失控。 你试图用一段线性的文字去描述一套有分支、有循环、有条件判断的流程,结果就是模型把它当成"参考建议"而不是"严格步骤"。它会自作主张地跳过某一步,或者把第三步先做了再回头补第一步。任务越复杂,这种失控就越明显。

第三个是工具调用混乱。 Function Calling 这个机制本身没问题,但是当你的智能体可以调用的工具达到十几二十个,每个工具的命名又占用大量 token,模型很容易选错工具,或者把同一个工具反复叫好几次。这里头还有个更隐蔽的成本问题——就算有些工具这次根本用不到,只要它们的定义被注入到上下文里,就要持续消耗 token。 这一笔账很多人没算过。

1.2 Skills 是怎么对症下药的

Anthropic 在 2025 年 10 月那篇 Equipping Agents for the Real World with Agent Skills 工程博客里提出的解法,本质就是把"线性的、笼统的提示词"拆成"结构化的、可按需加载的能力包"。

具体的对症点有这么几条。把 SOP 单独写成一份 Markdown 说明书,流程要素清清楚楚,而不是混在闲聊的提示词里。把外部知识下沉到 reference 目录,只有任务真正用到的时候才读进上下文,这样既保留专业深度,又不浪费 token。把确定性的逻辑写成可执行脚本(Python、Bash 等),让脚本去跑那些"每次都要重复做、必须可靠"的活,而不是每次都让大模型重新生成代码。

这三件事合起来,就是 Skills 这个机制的核心价值——它让智能体既能像专家一样"懂规矩",又能像工程师一样"能复用",还能在不污染上下文的前提下"按需扩展"。 把这套机制理解透了,你后面写出来的智能体应用,稳定性和成本都会比纯提示词方案上一个台阶,这点我自己在源码七号站做几个内部项目时反复验证过。

再多说一句,提示词工程并没有过时,它只是有了边界。面对简短的、单轮的、灵活的任务,一段写得好的提示词依然是最优解;但面对那些需要稳定输出、需要复用、需要团队多人共维的智能体应用,Skills 把"工程化"这件事真正落了地。理解这层差异,才能避免一个常见误区:看到新工具就想着替代老工具。在莫潇羽的实践里,提示词、Function Calling、MCP、Skills 经常在同一个智能体里同时存在,各自负责最适合自己的那一部分工作。

二、Agent Skills 究竟是什么:一份给智能体看的"专业说明书"

理论铺垫到这,该把 Skills 的定义讲清楚了。我尽量不用官方那种学术化的说法,换成接地气的解释。

2.1 一句话定义

一个 Skill 就是一个文件夹,文件夹里放着一份给智能体看的说明书(SKILL.md)、一些可执行的脚本(scripts/),以及一些供它查阅的参考资料(reference/)。 智能体启动时只会扫到文件夹的"门牌号",真要干活的时候才会推门进来翻具体内容。

打个生活化的比方。想象你家厨房里有一台微波炉,微波炉面板上有"一键解冻"这种快捷指令——这就像传统的 Function Calling,功能单一、按一下就响应。厨房里还放着各种刀具——这是 MCP,通用性强,但你得自己拿、自己用、自己指挥它怎么切。Skills 则像贴在冰箱上的菜谱:它把一道菜从备料、火候、刀工到摆盘的每一步都写清楚,你只要按谱子走,新手也能做出大致不离谱的成品。

这个类比里有几个关键点要再强调一下。Function Calling 是"按钮",MCP 是"工具",Skills 是"流程"。三者不是替代关系,而是配合关系。 一个成熟的智能体应用里,菜谱(Skill)告诉智能体先干什么后干什么,菜谱里某一步说"切丝"的时候,智能体会去拿厨房的刀(MCP)。这个组合拳才是工业级智能体的常态。

2.2 Skills 与 MCP 的边界划分

这是个高频问题,我专门拆开讲。

理解了这张表,你就明白为什么 Skills 推出后社区里有"Skills 比 MCP 更值得投入"的声音了。不是 MCP 不好,而是 Skills 解决了一个 MCP 没解决好的问题——专业流程的封装与复用。莫潇羽@源码七号站这边的实践经验是:有内部数据要访问就上 MCP,有标准流程要复用就上 Skills,二者经常同时存在于一个智能体里。

举一个 Skills 和 MCP 联手干活的真实例子。我们做过一个"销售订单异常处理助手",流程是这样的:Skill 里写明 SOP——先核对订单状态、再检查物流信息、最后判断要不要触发售后流程。但订单数据、物流接口、售后系统都在公司内网,智能体没法直接访问。这时候 MCP 就上场了:订单数据库通过 MCP 暴露查询接口,物流系统通过 MCP 提供查询能力,售后工单系统通过 MCP 接受创建请求。智能体执行 SOP 的每一步时,通过 MCP 拿到所需的数据,再按 Skill 的规则做判断。这种 Skills + MCP 的组合形态,在企业级智能体里非常常见,也是莫潇羽强烈推荐的工程范式。两套机制各司其职,谁也不抢谁的活。

2.3 Skills 的三大组成

每一个 Skill 在物理结构上是这样的:

my-skill/
├── SKILL.md          ← 必需,说明书 + YAML 元数据
├── scripts/          ← 可选,可执行的脚本
│   └── upload.py
├── reference/        ← 可选,知识库 / 参考资料
│   └── company-finance-manual.md
├── templates/        ← 可选,模板文件
│   └── report-template.md
└── examples/         ← 可选,示例输入输出
    └── sample.md

SKILL.md 是唯一必须存在的文件,其余目录都按需选用。这里面有几个细节要注意。

文件夹的名字会成为 Skill 的命名标识,智能体在加载列表里看到的就是这个名字。scripts/ 里的文件优先放可执行代码,这部分内容默认不会进上下文,只有智能体决定要跑它的时候才会执行,这一点跟把代码塞进 SKILL.md 是本质区别。reference/ 里放的是"模型需要查阅的资料",注意,不是塞给用户看的,是塞给模型在干活时查阅的,所以语气和组织方式要往"工具书"的方向写。

graph TD
    A[智能体收到任务] --> B{扫描可用 Skills}
    B -->|读取 YAML 元数据| C[L1 元数据层]
    C --> D{当前任务匹配吗?}
    D -->|不匹配| E[跳过该 Skill]
    D -->|匹配| F[L2 主体说明加载]
    F --> G{需要参考资料吗?}
    G -->|不需要| H[直接执行]
    G -->|需要| I[L3 资源按需加载]
    I --> J{需要跑脚本吗?}
    J -->|否| K[输出结果]
    J -->|是| L[沙箱执行脚本]
    L --> K
    H --> K

这张流程图就是 Skills 工作机制的全貌,后面几章我们会把每一层都拆开来讲。

三、拆解一个标准 Skill 的内部结构

光看目录树不够直观,我们直接看 SKILL.md 的真实模样,然后逐字段说清楚每一处的写法。

3.1 YAML Frontmatter 的写法规范

每一个 SKILL.md 的开头都有一段 YAML 元数据,被两组三个减号包起来,这段就是 L1 加载层的全部内容。

---
name: meeting-summarizer
description: >-
  This skill should be used when the user provides raw meeting
  transcripts and asks for structured meeting minutes, action
  items, or wants to sync the summary to a server. Also triggers
  on words like "总结会议"、"会议纪要"、"同步到云端".
---

# 会议总结助手

## 总结规则
...

这里有几条规范是经过踩坑得到的硬经验,莫潇羽建议你照抄。

name 字段只能用小写字母、数字和短横线,不能有空格,长度不超过 64 个字符。命名要有动名词感,比如 meeting-summarizer、pdf-extractor,直接告诉智能体这个技能"是做什么的"。

description 字段是整个 Skill 里最重要的一行字,这话不夸张。因为智能体决定"要不要加载这个 Skill"完全是基于这个字段的描述。 Anthropic 给出的字符上限是 200 个字符以内,但写得越精准越好。三个原则:用第三人称(写"This skill should be used when..."而不是"Use this skill when...")、写清楚"做什么"和"什么时候用"、包含关键的触发词。

举几个反面例子让你对照感受一下。

# 反面案例 1:太笼统
descrip