最近圈子里聊 agent 的时候几乎绕不开一个词agent-skills。有人把它当成 prompt 工程的下一个形态有人把它理解成 tool 的增强版也有人干脆说它是 agent 的“插件市场”。这些说法都不算错但都不够准。我做了几轮真实项目之后对它的定义是agent-skills 是把某一类任务所需的指令、示例、脚本和参考资料打成一个独立、可复用、可测试的最小能力包。这篇东西会把我在实战里摸出来的设计、开发、测试一整条链路拆开讲清楚适合正在做 agent 应用、或者觉得 system prompt 越来越臃肿的朋友也适合刚接触 agent 编排、想弄明白“skills 到底是个啥”的新手。1. agent-skills 到底对症什么病从提示词膨胀说起1.1 一条 system prompt 从 2K 膨胀到 20K 的完整过程先讲一个我真实遇到的场景。最初我给一个客服 agent 写系统提示词只有 2000 token 左右角色设定、回复语气、几条规则。跑了两周需求方开始往里加业务规则、产品知识、话术模板、敏感词清单系统提示词一路膨胀到了 20K token 以上。问题开始成串出现每次请求都要背上 20K 的上下文推理成本直线上升首字响应时间肉眼可见地变慢内容一多模型对“哪条规则优先级更高”的判断开始漂移。同样的用户问题上午和下午能给出完全不同的回答改一条规则可能波及另外五处行为回归测试基本靠祈祷团队新同学接手这套提示词光通读一遍就要半小时更别说改。这就是最典型的“提示词膨胀”病。它的本质是你试图用一段线性的文本去承载一个非线性、会分叉、要按场景选择的能力体系。agent-skills 的出现本质上就是把原来塞在 system prompt 里的东西拆成一个一个独立模块让 agent 在需要的时候才加载对应的那一个。这和写代码的思路一模一样——你永远不会把一个两万行的文件 import 进所有函数那为什么要让 agent 每次干活都背着一整套百科全书呢1.2 skill、tool、workflow 的边界到底在哪很多人分不清 skill 和 tool我之前也糊里糊涂过。现在我用一张表把它讲清楚维度ToolSkillWorkflow粒度单次原子操作多步能力编排端到端业务过程示例调用搜索 API、执行 SQL写周报、做数据分析从喂数据到出报告全流程对外形态函数/接口指令包脚本资料状态机/流程定义上下文消耗少仅参数拼接按需加载可大可小通常常驻在流程里复用难度低中高这么一看就清晰了tool 解决“单次动作怎么做”skill 解决“一类任务怎么完成”workflow 解决“整条业务怎么串起来”。skill 在中间这层最灵活它可以调用多个 tool也可以内嵌脚本和静态资料。我现在的习惯是当一个功能既需要知识说明、又需要步骤编排、还可能用到脚本时就默认往 skill 方向想。1.3 不是所有任务都值得做成 skill这一点我得先泼冷水。不是所有功能都适合封装成 skill。适合做成 skill 的任务通常有三个特征有稳定的输入输出结构比如“给我一段原始数据还你一份可视化报告”会被反复执行一次性任务封装成本收不回来需要独立的领域知识或判断规则值得把这些知识固化进包里。反过来如果只是想让 agent 多一个调用天气接口的能力那是 tool 的事如果要管的是跨三天、跨系统、带审批状态流转的复杂流程那是 workflow 的事。把中间这层 skill 用错位置后面会非常难受——做得太简单浪费做得太重又管不住。2. 一个合格 skill 的内部构造不只是写一份 Markdown2.1 元信息里的 description决定 agent 会不会想起你一个 skill 在绝大多数 agent 框架里就是独立目录核心文件叫 SKILL.md开头是 YAML frontmatter。先看一个示例--- name: weekly-report-generator description: 根据本周的工作日志生成结构化周报适用于周报周期结束、需要汇总员工产出时的场景当用户提到“周报”“本周汇总”时优先考虑使用。 version: 1.2.0 author: ops-team tags: [report, weekly] ---这个 description 里有三个关键要素做什么事、什么时候该用、什么词会触发。除了这几个字段我还会根据团队情况补上 maintainer、compatible_models、last_reviewed 这类信息。它们平时不参与推理但等 skill 数量过 20 个之后你会发现这些元数据是维护和审计的重要抓手。写 description 时要用第三只眼来写假装自己是一个根本不知道这个 skill 存在的 agent面对用户的新请求只看这段描述能判断出“该我上场了吗”如果判断不出来说明描述写得太虚。我不止一次吃过这个亏后面在 4.1 里细说。2.2 指令、示例、资源三层结构怎么配一个完整 skill 的内容可以拆成三层指令层告诉 agent 按什么步骤完成任务。要写得足够程序化明确先后顺序、判断条件、失败时的降级路径示例层给 1-3 个 input/output 的完整范式。对 LLM 来说一个具体的例子顶过十句抽象描述资源层领域词典、参考模板、脚本、历史数据等静态材料。有人把这三层全塞进一个 SKILL.md文件写到 500 行。不算错但我建议SKILL.md 只保留指令和必要示例静态资料全部丢到同目录的 resources 里让 agent 按需读取。推荐目录结构skills/ └── weekly-report-generator/ ├── SKILL.md ├── resources/ │ ├── template.md │ ├── metric_dict.md │ └── git_log_parser.py └── tests/ ├── case1_input.txt ├── case1_expected.md └── ...这套结构的收益在后期特别明显。我在团队里推行这个约定之后新同事上手维护别人写的 skill最多半天就能完成一次修改之前那种一个 Markdown 塞到底的结构光理解就得一两天。2.3 渐进式披露管住 token就管住了成本和质量“渐进式披露”听起来复杂其实特别朴素agent 先只读到 SKILL.md 这个说明书等它判断确实需要更细的信息时再打开 resources 里的具体文件。这样一个 skill 平时只占几百 token而不是几千。我自己会把 SKILL.md 的体量压到 2K token 以内如果指令确实复杂就写“详细规则见 resources/rules.md”并注明什么时候才需要读。具体操作上我会在 SKILL.md 里给每个资源文件加一行“使用条件”比如## 参考 - resources/metrics_definition.md 仅当需要核对指标口径时读取 - resources/template.md 仅在最终输出前读取别小看这一行声明。它相当于告诉 agent 什么时候该打开抽屉、什么时候不该碰。实测中这个“仅当……时读取”的措辞能显著减少 agent 无意义地翻资源文件。这就像做菜看菜谱主菜谱只写步骤概要火候细节在备注里新手才需要一次性全读完。agent 也一样把不必要的东西提前倒进上下文只会稀释它对当前任务的注意力。3. 从 0 到 1 搭一个可用的 skill一次完整实操3.1 先定能力边界再写第一行字我拿一个真实例子走完全程生成“数据分析日报”。目标设定为agent 拿到 CSV/Excel 数据文件输出一份包含业务摘要、关键指标、异常提醒三部分的 Markdown 日报。动手前先回答三个问题输入是什么答分析师上传的 CSV 或 Excel。输出是什么答固定格式的 Markdown 日报。边界在哪答不做预测建模不生成图表文件不做多日趋势预测。这个边界必须在 SKILL.md 的 description 里写明避免 agent 越界发挥。我写的是“本 skill 不负责预测模型与可视化图表生成”后面实测中这句话至少阻止了两次 agent 自作主张去做线性回归。别觉得这是多余agent 一旦进入“自由发挥”状态输出质量就很难稳定。3.2 SKILL.md 正文的写法要点下面是我实际用的一个简化版本可以直接参考--- name:>