Agent Skill 智能体技能完全拆解：从渐进式加载原理到多工具实战落地

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

快速摘要

一句话先给结论：Agent Skill（智能体技能）= 一份 SKILL.md 说明书 + 可执行脚本 + 按需加载的参考资料，它靠"渐进式加载"在不撑爆上下文的前提下，把零散提示词升级成一套可复用、可分发、可串联的标准作业流程。 它和 MCP 不是替代关系——MCP 解决"工具怎么连"，技能解决"流程怎么走"，两者组合起来才是完整闭环。技能最核心的省钱机制是三层加载：L1 只读名称描述（几十 token）、L2 用到时才读主体说明（几百 token）、L3 真正触发时才拉参考文档和脚本，没用到的内容一律不进上下文。本文会把"为什么需要技能、技能由什么组成、底层怎么加载、怎么写出能用的技能、怎么在 CLI/IDE 里跑通、怎么打包部署、怎么做安全审查"一条线讲透，并配上目录结构、流程图和示例代码。想看完整拆解，往下翻。

一、先把问题摆上桌：长提示词为什么总在复杂任务上翻车

我自己刚开始折腾智能体那会儿，干过一件特别费劲的事：为了让一个 AI 助手"既能整理会议、又能写文档、还能查规范、顺便把结果发出去"，我吭哧吭哧写了几百行系统提示词，把所有规则、所有边界、所有格式要求一股脑塞进去。简单任务跑得挺漂亮，一进到真实的复杂业务流程，它就开始抽风——解决了第一个问题，第二个问题又冒出来；好不容易第二个对了，第一个又跑偏了。相信不少人都有过这种"按下葫芦浮起瓢"的体验。

后来我才想明白，这背后其实是一个本质矛盾：自然语言天生是模糊的，而工程交付要求的是严谨的。你用一长段话去描述一套多维度、非线性的复杂逻辑，模型在执行时很难每一步都精准对齐你的意图，偏差几乎是必然的。

把翻车的原因摊开看，主要是三类。

第一类是注意力被稀释。大模型底层是 Transformer 的注意力机制，说白了它在"读"上下文的时候，精力是有限且会分配的。提示词越长、对话轮次越多，上下文窗口被填得越满，模型对其中某些细节的"关注度"就越低。结果就是——它看起来好像理解了你所有要求，真到执行时却把一些关键细节给"忘"了。你跟它聊得越久，越容易出现幻觉、越容易蹦出莫名其妙的回答，根子就在这儿。

第二类是流程失控。一个庞大的任务如果没拆开，模型在多步推理里很难维持逻辑一致性。步骤一多、彼此一耦合，它就容易乱套。这跟我们人做事是一个道理：一个大项目甩给你，你也得先拆成阶段、再拆成任务、排好优先级，一步步推进；指望一口气从头干到尾不出错，不现实。

第三类是工具调用混乱。一旦任务涉及外部能力——查天气、查地理位置、调第三方接口——如果这些工具没在提示词里说明白，模型经常会"找不到工具"或者识别错。更要命的是，工具定义本身就很吃 token，没有清晰的触发场景描述，调用出错的概率会进一步放大。

我把这三点画成一张图，方便你建立整体印象：

flowchart TD
    A[一坨超长系统提示词] --> B[上下文越来越长]
    B --> C1[注意力稀释<br/>细节被忽略 / 幻觉]
    B --> C2[流程失控<br/>多步推理逻辑不一致]
    B --> C3[工具混乱<br/>找不到工具 / token 浪费]
    C1 & C2 & C3 --> D[复杂任务翻车]
    D --> E[需要一种新组织方式：Agent Skill]

这就引出了技能（Skill）这个东西。它的思路不是"把规则写得更长更全"，而是反过来——把一个大能力拆成边界清晰的小模块，每个模块只负责一件事，用到哪个才加载哪个。这跟我们做事时"大任务拆小任务、各自完成再汇总"的逻辑完全一致。接下来我就从最基础的概念开始，一层层讲清楚它到底是什么、怎么运转、怎么落地。

二、Agent Skill 到底是什么：一句话讲清"技能三件套"

技能这个词，翻译过来就是"技能"，理解起来其实不绕。你打游戏的时候，一个英雄有很多技能，每个技能负责打出某种效果、某段伤害。智能体的技能也是一个意思：它就是要去实现某一个特定的功能、某一种特定的能力。 你完全可以把它当成一份"能力使用说明书"来理解。

这里要先和一个老概念划清界限——函数调用（function calling）。很多人会问，函数调用不是早就能让模型调代码、调接口了吗，技能跟它有啥区别？区别还真不小。函数调用本质上只是"一次 Python 函数执行"或者"一次 API 调用"，它是个点状的动作。而技能是个组合体，它不光能调函数，还能携带提示词约束、参考资料、触发规则，是一套"打包好的工作方式"。

用我自己的话总结：函数调用是"一把锤子"，技能是"一份带锤子的施工说明书"。

再往深里说一层。函数调用解决的是"模型怎么把一个动作执行出去"——它本质是把模型的意图翻译成一次确定的程序调用，调完拿到返回值就结束了，模型并不知道这个动作前面该铺垫什么、后面该收尾什么。技能不一样，它把"什么时候该调、调之前要先准备什么、调完拿到结果怎么处理、出错了走什么兜底"这些上下文一并打包进去了。换句话说，函数调用是"招式"，技能是"招式 + 心法 + 出招时机"。我自己的体会是，当一个任务只有一两步、且边界很清楚时，裸函数调用就够了；可一旦任务有了"先后顺序、条件分支、要参考资料"这些复杂度，光靠函数调用拼起来会很脆，这时候就该上技能了。

一个标准技能，由三部分组成，我习惯叫它"技能三件套"。

第一件：SKILL.md（核心说明书，必选）。 这是整个技能唯一不能少的文件。它说明这个技能是干什么用的、用在什么场景、有哪些步骤、有哪些注意事项。还拿游戏技能打比方——这个技能造成多少伤害、攻击范围多大、什么时候放——这些最基本的信息，你得先在说明书里写清楚。文件开头有一段 YAML 格式的元数据（frontmatter），最关键的就是 name 和 description 两个字段，它俩决定了模型"什么时候想起来用这个技能"。

第二件：脚本（scripts，可选）。 技能不光能调大模型生成内容，还能执行真实的程序逻辑。这正是它被叫做"Agent Skill"的原因——单个技能本身是"死"的，它需要一个智能体（Agent）来驱动执行。比如你要调用本地的一段 Python 脚本去上传文件、压缩数据、访问某个内网服务，光靠大模型生成文字是办不到的，必须落到脚本上跑。完成复杂任务时，脚本往往是绕不开的一环。

第三件：reference（参考资料，可选）。 这相当于技能自带的一个小知识库。举个我常用的例子：让 AI 帮你做"周报汇总"，它得按公司的规范来写吧？如果你们公司有一套报告格式规范、有一套术语标准，那 AI 在汇总时就应该参考这些文档，而不是自由发挥。这跟新人进公司干活要先翻规章制度是一个道理——reference 就是给智能体"翻"的那本制度。

这时候很多人会冒出一个疑问：我把参考文档直接写进提示词里不就行了，为啥还要单独搞个 reference？ 这个问题问到点子上了，答案恰恰是技能最大的优化所在，我放到第四章的"渐进式加载"里专门讲——简单说就是为了省 token、省成本，用到哪份文档才加载哪份，而不是一上来把几十上百个文档全塞进上下文。

整套技能的目录结构长这样（这是一个我虚构的"周报助手"示例，方便你看清层级）：

.（你的项目根目录）
└── <工具规范目录>/            # 比如 .claude / .codebuddy / .codex 等
    └── skills/                # 技能总目录，下面可以放多个技能
        ├── weekly-report/      # 技能一：周报助手
        │   ├── SKILL.md        # 必选：说明书 + 元数据
        │   ├── references/     # 可选：参考资料（知识库）
        │   │   └── report-style.md
        │   └── scripts/        # 可选：可执行脚本
        │       └── upload.py
        └── data-clean/         # 技能二：数据清洗（同样的三件套结构）
            └── SKILL.md

我把"三件套"各自的职责、是否必选、可以放什么，整理成一张表，新手对着看一眼就清楚：

所以技能从来不是一段简单的脚本，它是一套 SOP（标准作业程序）+ 工具 + 知识库 的组合概念。这个认知打底了，后面理解它的运行原理才不会绕。我自己带人时，第一件事就是先把这张表讲明白——莫潇羽@源码七号站这边踩过的弯路告诉我，概念没立住，后面调试再卖力也是事倍功半。

三、和提示词、MCP 比，技能到底解决哪一层问题

要把技能讲透，绕不开它和"提示词"以及"MCP"的关系。这三个东西经常被混着说，但它们解决的根本不是同一层问题。

先说 MCP（Model Context Protoco