如果你手上有一个大模型，每天要替你做各种乱七八糟的事——整理报表、分析日志、写代码、抓网页信息——你一定有过这种体验：同一个任务，上午问它答得挺好，下午换了个问法，它就开始自由发挥，结果完全不对味。
我遇到过的最极端情况是，让模型按固定格式输出一份巡检报告，它写倒是写了，但格式一会儿换换缩进、一会儿换换术语，我不得不在脚本里写一堆正则去兜底。后来我意识到，问题不在模型笨，而在于我每次都指望它“临时领悟”我的流程。今年我陆陆续续给项目里加了一套叫 agent-skills 的技能库，模型干活的稳定性和效率直接上了一个台阶。
这篇文章不聊任何商业背景，也不蹭什么高大上的概念，纯粹基于我在实际项目里的使用经验，把 agent-skills 这套方法拆开揉碎——它到底怎么落地、技能包内部长什么样、怎么写才不会翻车，适合正在折腾智能体应用、提示词工程，或者只是想让大模型更听话一点的同学参考。
1. 为什么靠嘴说不行：Agent Skills 解决的问题
先说一个最容易被忽略的事实：现阶段的模型不是没能力，而是能力发挥不稳定。你让它分析一份日志，它知道字段，也懂异常判断逻辑，但真正干活的时候，它很容易被上下文里的无关信息带偏，或者自己“发明”一套处理规则。
所谓 agent-skills，说到底不是模型本身多了一种魔法，而是我们这些使用方换了一种交互方式：把某一个领域的操作流程封装成一段结构清晰、带明确触发条件的“技能文本”，让模型在运行过程中按需加载。它不需要预置在第一批输入里，而是在判定任务匹配时主动读取技能说明，再按照说明里的步骤去执行。这个机制等于在模型和你原本的临时对话之间，加了一层标准作业程序。
我最初看到这类做法时，觉得不过就是把提示词拆开存了。真正用起来才发现，几个细节决定了它和普通提示词完全是两种效果：
- 技能有明确的边界：什么情况下用、什么情况下停，模型不用猜。
- 技能有固定的结构：输入、输出、步骤、注意事项，每一项都清清楚楚。
- 技能是可选装载的：不占主上下文的预算，降低无关信息对模型的干扰。
- 技能是可复用的：同一套流程换一批数据，换个场景，甚至换一个模型，照样能跑。
这让我想到一种类比：普通提示词像是让一个新人只听口头描述就上手干活，而 agent-skills 更像是把工作手册递给他。手册不是万能的，但有了手册，新人的下限就被兜住了。
1.1 它和 System Prompt 的本质区别
很多人看到这里会问：那我把所有规则都写进 System Prompt 不就行了吗？还真不行。
System Prompt 在一轮对话里是“常驻”的，模型从头到尾都能看到，这既是优点也是缺点。如果技能很多，全塞进 System Prompt，上下文长度很快就被吃光了，而且相互之间还可能干扰——模型看到几十条不相关的技能描述时，反而不知道当前任务到底该启用哪一个。
Agent Skills 的思路是动态加载。主对话里只保留模型的任务目标和基本约束，技能文本单独存放。模型先根据用户请求做判断，看是否命中某个技能的触发条件，命中了才把那段完整说明拉进上下文。这种做法的直接好处有两层：一是上下文更干净，模型在长任务里的专注度明显提升；二是技能可以做得非常长、非常详细，不用像 Prompt 那样为了省 token 而删删改改。
从维护角度看差别更大。过去我调一个 System Prompt，稍微动一个词都可能影响其他任务的表现，牵一发动全身。技能库则天然隔离，日志分析技能和代码生成技能互不相关，改其中任何一个都不需要回归另一套场景。对项目迭代来说，这种“低耦合”的价值比什么花哨功能都重要。
1.2 动态加载到底是怎么触发的
这一点我当初同样好奇，还专门做过对照。触发机制通常分两层：第一层是主对话里写一个简短的“路由器”指令，告诉模型有哪些技能可用、每项技能一句话概括；第二层是当模型判断任务匹配时，由外部程序把该技能文本注入上下文。
这里强调一点，技能库里每一项技能的描述信息（也就是元数据）必须写得非常具体。比如“用于给 nginx 日志按五分钟窗口统计状态码”，比“分析日志”要好得多。因为模型的匹配依据是描述文本和用户请求的语义相似度，描述越具体，命中越准。
如果模型支持 tool/function 调用的形式，还可以直接把技能列表注册成可调用工具，由模型在需要时发起请求，应用侧再把技能全文返回给它。这种方式在需要严格权限管理的项目里也比较干净，技能不暴露给用户，只在代码侧注入。
2. 一个技能包内部的结构拆解
讲完了动机和原则，下面进入到最实际的部分：一段 agent-skills 技能文本到底该写哪些东西。我研究了不少公开模板，也自己迭代了很多版，最终沉淀下来的结构是固定的几块：元数据、目标定义、步骤执行、输出规范、边界条件与反例。这五个部分缺了谁都会出问题。
元数据不参与模型的任务推理，更多是给匹配器和人类维护者看的。我一般用 YAML 块放在技能文本最顶部，包含技能名称、适用场景、输入要求、输出产物、相关文件路径。这里有个容易被忽略的点——元数据里最好标注“不适用的场景”。比如一个做 JSON 格式化的技能，明确写一句“输入不是字符串或无法解析的文本时不要调用”，能避开很多尴尬。
2.1 步骤执行区：少用描述，多用指令
很多人写技能喜欢用大段描述性文字，例如“深入分析用户的需求，给出专业建议”。这种话模型读过一千遍，等于没读。真正有效的写法是拆成可以按序执行的指令：
1. 读取输入中的原始文本，识别文本类型 2. 如果文本包含 URL，先抓取该 URL 的内容 3. 对抓取内容做正文抽取，去除导航和广告噪音 4. 按目标字段清单提取信息，缺字段标为 N/A 5. 输出 JSON 结构指令越靠近程序式的“操作序列”，模型的表现就越稳。原因是模型完成这个任务的思考路径被固定了，它不需要每次临时编排步骤，只需要老老实实按清单执行。这个方法在 Claude 和 GPT 系列上都验证过，效果差异不大。
2.2 输出规范：让结果结构化的关键
模型输出不稳定的根源之一，是“描述期望结果”和“定义结果结构”被混为一谈。你想让它给一个表格，光是强调“要对齐”“要清晰”没用，要给模板：
{ "status": "ok", "summary": "一句话总结", "details": [ {"time": "10:00", "event": "service restart", "level": "info"} ] }有模板兜底，模型哪怕中间理解有偏差，输出格式也不会歪。顺便提醒，定义模板时最好顺带说明每个字段的含义。像 department 用缩写、用户 ID 保持字符串原样，这种细节在模型眼里是重要约束，不是废话。
2.3 边界条件与反例
这部分是我写技能时最花心思的地方，因为大模型的通病不是不知道怎么做，而是“过度执行”。你让它处理三条异常，它可能顺手帮你把正常的数据也“修复”了。所以每个技能包都必须写清楚边界，比如：
- 只处理指定格式，其他格式原样跳过
- 输入为空时返回空结果，不猜测
- 不要修改原始文件，输出为独立文件
- 数据量超过 5000 条时停止处理并提示分批执行
反例的作用更多是“纠偏”。我习惯在每个技能包的末尾附上一组“错误示例→正确结果”的小对照。模型在实际执行时碰上类似情况，会不自觉地按正确示例靠拢。这个技巧我试过很多次，比写三行“不要做什么”都管用。
2.4 依赖和工具的声明
如果技能执行过程需要调用外部工具或文件，一定写清楚。比如“本技能依赖 data/raw_logs/ 目录下的现有文件”“处理结果写入 output/reports/”。模型在判定是否使用技能时，能提前判断前置条件是否满足，避免做到一半发现缺数据。有些框架支持在技能描述里声明环境变量和脚本路径，这种能力要善用，因为把环境相关的信息固化到技能里，意味着团队内部换人也能跑，不依赖个人经验。
3. 一个完整实操：日志异常归因技能包的从零构建
前面说的都是原则，接下来我带大家走一遍我在本地完整实现一个“日志异常归因”技能包的流程。选这个例子是因为它贴合绝大多数后端项目的真实需求，而且能覆盖前面提到的所有结构要素。
3.1 第一步：定义触发场景和输入
我最初的输入形态很随意，可能就是用户丢一句“帮我看看今天的日志，为什么接口超时变多了”。这属于典型的多语义任务，模型如果不被约束，可能去分析网络，可能去分析数据库，也可能输出一堆废话脚本。所以我把触发场景定义得非常窄：
适用场景：输入包含应用访问日志文件路径、日志格式说明，并明确要求在时间窗口内对状态码 5xx/4xx 做归因分析。 不适用的场景：输入不是日志文件路径；未指定日志时间字段；用户只是询问日志格式规范，没有异常归因诉求。
这样定义之后，匹配器就不会在闲聊或一般性问答里误触发技能。
3.2 第二步：写主流程，拆成可校验的步骤
技能主流程我设计为七个环节，每环节一步，单步结果影响下一步输入。实际代码和指令是这样组织的：
1. 定位文件：读取输入中的日志路径，确认文件可读，不可读则直接反馈错误。 2. 格式识别：根据给定格式解析一行样例，提取 time、level、url、status、latency_ms 等字段。 3. 时间过滤：仅保留指定时间窗口内的行，其他行丢弃。 4. 状态码聚合：按状态码分组，统计 5xx/4xx 占比，按 URL 路径汇总异常排名。 5. 实例提取：对 top3 异常路径，各保留 3 条原始日志行作为证据。 6. 归因策略：基于 latency_ms 和错误关键字给出“慢调用”或“依赖异常”的倾向性判断。 7. 输出报告：按既定 JSON 模板输出，附证据行。可能有人觉得步骤太死板，但我在测试里发现，步骤越死板，模型越少“开脑洞”。例如第四步和第五步之间的顺序绝对不能换——先聚合才能决定取哪几个路径的实例，否则模型很可能随便挑几行就开始分析，结论自然不靠谱。
3.3 第三步：定义输出结构和验证方式
输出结构我规定成 JSON，字段和含义全部写死，这一点前面说过，不再重复。但有个额外的点要说：在技能里加入“自检清单”，让模型在最终输出前检查几项硬指标：
- 所有时间字段格式是否与输入样例一致
- top3 路径是否来自步骤 4 的聚合结果
- 证据行是否截断，原始文本是否保留完整
- 单个字段长度是否可能超过下游表字段限制
如果你用程序解析模型输出，这个自检环节能显著降低报错率。因为我遇到过太多次模型把报告写得漂漂亮亮，结果时间字段带了时区后缀，数据库一插入就崩。给模型一个自检项，让它在输出前自己纠正，能挡掉一批低级错误。
3.4 第四步：设计反例，堵住模型自由发挥的口子
这个技能包最容易翻车的地方是“归因策略”。模型在输出意见时有个习惯——数据不足也硬给结论。所以我专门写了三条反例：
- 错误示范：日志没有数据库慢查询记录，却断言“可能存在慢 SQL”。
- 正确行为：日志未涉及数据库模块，归因结果为“数据不足，无法确认根因”，建议补充链路追踪。
- 错误示范：只有一个实例样本的情况下给出“普遍性问题”判断。
- 正确行为：基于样本量提示“现象为个案，建议扩大时间窗口确认”。
这些反例让我省了很多人工复核的时间。模型看到正确行为示例后，学到的不仅是规则本身，还包括对“归因结论”的克制态度——这对所有分析型任务都是通用的，强烈建议写进技能里。
3.5 第五步：挂载技能到智能体运行时
我的挂载方式是给主对话系统提示里增加一段可用技能清单，每项就一行字说明，不做全文载入：
可用技能： - log_anomaly_attribution：对访问日志做 5xx/4xx 异常归因，要求提供文件路径和时间窗口。技能会执行聚合分析并输出 JSON 报告。 - json_formatter：将任意 JSON 字符串按模板重建字段顺序和缩进。模型在收到具体用户请求时，如果匹配到 log_anomaly_attribution，应用侧就把完整技能文本注入消息列表。这一步我验证了很多次，技能注入后模型会在后续消息里直接进入了执行状态，不会和当前对话的主题搞混。而且由于技能文本只在匹配时载入，主对话里的“路由开销”很小，长对话的稳定性也更好。
4. 写技能时最常踩的坑与排查手册
这部分是我最想直接给到大家的实操经验，因为光看结构容易，真的动笔总会踩到各种细节问题。我把我自己和身边朋友踩过比较多的情况整理成了几个典型的坑，每个都附上了排查思路。
4.1 元数据表述模糊，导致命中率忽高忽低
这是最常见的问题。明明技能写得很好，却经常不触发，用户问题变成了模型自己“想到哪打到哪”。排查下来，罪魁祸首基本都是描述文本和真实用户表达方式不匹配。
比如你写“对过期离线缓存做一致性校验”，用户实际说的是“跑一下缓存比对”。这俩词面差别很大，如果框架用字面匹配，永远命不中。我的做法是：在元数据的“其他触发词”里塞进用户可能使用的各种口语表达。维护者平时从日志里看到哪些问题被漏判，就顺手把对应的用户原话加进去。
另外一个技巧是给技能写一个“反面描述”，明确列出不负责的任务类型，能减少错误触发。有些场景下两条技能描述类似，模型选中的那个往往不是你要的，反面描述能提前排除掉一批语义重叠。
4.2 技能步骤太抽象，模型跳过关键节点
这是我早期最头疼的问题：我在步骤里写“检查数据完整性”，模型直接回答“数据完整”，但实际上它的输入里根本没数据文件。为什么会这样？因为“检查”这个词模型没法把它变成一个可观测的动作。
后来我把所有动词都改成可执行动作——不是“检查”，而是“读取文件的前 20 行并计算字段缺失率”。模型一旦能操作具体的数据对象，它的执行质量立刻上来了。由此我得到一个重要经验：技能里的每一句话都要对应一个可以检验的产物，这是技能设计和普通写作最大的区别。
4.3 技能文本过长，反而压过主任务意图
动态加载的好处是长文本不占常驻空间，但技能文本本身如果冗长到一万字以上，把用户的原始需求和上下文挤到几乎看不见，模型依然会被带偏。我通常在技能文本超过 2000 字时强制自己精简：凡是可写可不写的背景信息一律删掉，凡是只对维护者有意义的注释块移到文末，标注为“维护信息，不用于执行”。
让模型区分“执行指令”和“背景说明”很重要。我会在技能开头加一行注释：
> 以下内容为执行指令，全文按顺序生效；除非冲突，否则背景信息不覆盖执行指令。这一行在效果上有点像闹钟，提醒模型接下来是操作手册，不是闲聊资料。实践证明这种明示对减少指令漂移很有帮助。
4.4 输出格式校验缺失，下游脚本崩盘
就算技能里写了 JSON 模板，模型偶尔还是会夹带解释性文字，或者输出 Markdown 代码块包裹。这不能甩锅给模型，只能怪我们没在外部做严格校验。我的建议是不要在技能内部塞过多“请只输出 JSON”的废话，而是在接过模型输出的应用层做解析和提示：
- 尝试去掉第一段 ```json 标记
- 解析失败时，把模型最后两轮消息和完整技能文本发给一个低成本的“修正提示”，让它只重新输出 JSON
- 如果两次解析仍失败，记录案例，反过来改进技能模板
这种兜底方案虽然听起来不优雅，但在生产环境里极其必要。技能包可以优化模型表现，但不能把宝全押在模型“永远听话”上。
4.5 版本管理一锅乱，技能改坏了难回滚
技能文本是代码，就该像代码一样管理。我见过有同事直接改线上技能文件，出问题了只能凭记忆找备份。更稳妥的做法是：技能文件放在 git 仓库，每次修改走分支、合并、发布三步；每个技能文件头部维护一个 version 字段，并在发布说明里记录对应改动。配合自动化测试示例，比如用一组固定输入跑技能看输出是否符合预期，这样回滚和迭代都会非常有底。
5. 关于技能维护节奏和个人体会
技能库不是写完放那儿就完事的。模型能力在迭代，用户的输入习惯会变，业务需求也会漂移，一套技能如果不维护，三周之后就可能开始出现奇怪的执行偏差。我最常做的维护动作有两个：一是定期查看哪些技能命中率低，二是把每次用户纠正模型回答的案例存下来，反向补充进技能的反例清单里。
“skill 的收益是复利式的”这句话一点不夸张。最初搭建花的时间确实多，一个技能从写到调通往往要一两天，但每个技能都解决了一大类重复劳动。到后来模型交付的成果越来越标准化，让我节省出来的时间远远超过写技能本身的时间。我个人的体会是，不要指望一个技能解决所有问题，宁可多建几个小而精准的技能，也不要拼一个看似全能实际谁也管不好的“大杂烩”包。
最后再分享一个我在真实项目里的原则：技能不是越复杂越好，恰恰相反，当我发现一个技能里出现大量“如果某些条件下，可以酌情”之类的模糊表述时，我就知道它的边界失控了。合理范围内的含混可以增加灵活性，但含混一旦铺开，模型又会开始自由发挥。把技能当成给同事写的一份详细交接文档，这个心态，比任何技巧都重要。
