说实话这两年做 Agent 项目的人不少但真正能让 Agent 稳定“干活”而不是“聊天”的团队少之又少。我自己带过多个智能体项目最深的体会是大部分人把精力全砸在模型提示词上却忽略了一个关键中间层——技能Skills。如果把 Agent 比作一个人模型是大脑工具是手脚而技能是刻在肌肉里的那套标准动作。今天这篇我就拿自己实际开发过的“agent-skills”项目来拆一拆这个层到底怎么设计、怎么写、怎么调踩过哪些坑。1. 为什么 Agent 必须有一套“技能层”1.1 从翻车现场说起没有技能的 Agent 有多不靠谱先讲一个真实场景。我们之前接了个需求让 Agent 自动筛选技术候选人简历要求是从几十份 PDF 里找出符合“五年以上后端经验、有高并发项目、带过团队”的人并输出表格推荐给 HR。第一版没做技能层就靠一个长 Prompt 解释器工具。结果你猜怎么着模型对“带过团队”的理解五花八门有人写着“管理 30 人技术团队”被漏掉有人只是“协助组长分配任务”却被标成高匹配。更麻烦的是它会把“熟练使用 Excel”当成“高并发经验”误判。那几天我们团队天天对着推荐列表挑错人力成本比人工筛简历还高。这个例子其实说明了一个核心矛盾大模型有知识但没有“岗位操作规范”。你知道怎么做不等于你能稳定做到。Agent 也一样给它一个开放指令它每次发挥都会漂移。技能层要解决的就是这种漂移把“怎么做”固化成可执行的流程、可校验的规则、可复用的经验。1.2 技能、工具、提示词三者的真实边界在哪很多初学者会把 Agent 的工具Tools、插件和技能混在一起。我的理解很简单工具Tools是 Agent 的手脚负责具体执行比如“读取 PDF”“发 HTTP 请求”“写数据到数据库”。它是无状态的像一个函数输入输出明确。提示词Prompt是 Agent 的短期指令解决“这一次任务怎么做”但它是易失的换了上下文就没了也难以复用。技能Skills是 Agent 的工种能力它是“提示词 流程 校验规则 示例 领域知识”的组合体是把一顿饭的菜谱变成厨师的拿手菜。打个比方给你一个高级厨师 Prompt说“做一道川菜”他可能今天做麻婆豆腐、明天做水煮牛肉都不算错。但如果你给他一套“宫保鸡丁技能包”里面写清楚腌制时间、火候曲线、下料顺序、出锅标准那十次做出来九次都在及格线以上。技能层要的就是这个效果它不是限制模型的创造力而是把模型的能力约束在能被预期管理的范围内。1.3 技能层在 Agent 架构里到底站在哪个位置从系统架构看技能层位于大模型之上、业务逻辑之下。完整链路大概是这样用户需求进入 Agent 编排层编排层从技能库检索匹配的技能技能包被加载进上下文并指导模型完成任务任务执行中调度工具去读文件、调 API、写结果最后按技能包里的校验规则质检输出。你可能要问那技能层和编排层Orchestrator有什么区别我的理解是编排层管“路由”决定哪个技能上场技能层管“执行”决定这个活怎么干得漂亮。如果编排层是项目经理技能层就是老师傅的手艺。两者解耦之后你会发现迭代某个技能完全不影响路由逻辑团队可以并行开发复用起来也干净。2. 一个标准技能包的内部结构拆解2.1 技能不是一段 Prompt而是一个“资源包”我在项目里定义技能时一直遵循一个原则一个技能必须是一个自包含的目录而不是一个文本块。这样做的好处太多了可版本管理、可单独测试、可多人协作维护、可按需加载。一个典型的技能目录长这样你可以直接抄skills/ resume-screener/ SKILL.md workflows/ screen_resume.md interview_guide.md checklists/ key_experience_checklist.md team_lead_checklist.md rules/ matching_rules.yaml output_schema.json examples/ good_case.md bad_case.md references/ company_level_mapping.md每个文件都有自己的职责。SKILL.md 是技能的“身份证”和“启动开关”告诉系统这个技能干什么、什么时候启用workflows 是步骤拆解checklists 是操作清单rules 里放的是硬性规则和输出格式examples 是给模型看的参考答案references 是领域背景资料。2.2 最关键的三个文件SKILL.md、校验规则和示例这三者各有侧重缺一不可。SKILL.md 的元信息部分要写成机器可读的格式方便检索和路由。我用的是简单的 YAML front-matter包括技能名称、适用任务类型、所需工具、预期输出类型。这里特别要注意“适用任务类型”的覆盖面别太窄也别太宽——太窄了检索引擎匹配不上太宽了容易误触发。校验规则rules/是技能包的“质检员”它的价值在于把模型输出从“自由发挥”拉回到“稳定交付”。我见过很多团队在 SKILL.md 里写了规则但没有单独成文件结果就是规则写了一大堆模型实际遵循率只有一半。单独成文件后可以把这些规则抽出来转成代码里的断言逻辑在运行时自动检测。示例examples/是给模型做 few-shot 参考的重要性经常被低估。不要写那种完美的理想答案反而要给一个“中等偏上”的示例外加一个“有明显缺陷”的示例模型对对比式示例的学习效果比你给十个完美样例都好。提示我见过不少技能包把“校验规则”写在提示词里然后让模型自己检查自己效果很差。模型自己判断自己的输出质量等于让学生自己改自己的考卷基本都会放水。正确的做法是能用正则判断的用正则能用枚举比对用的枚举实在需要语义判断的单独用一个弱模型做“质检员”和主模型隔离。2.3 用软件包管理的思维来管理技能库当技能多起来之后你会发现维护成本急剧上升。我现在习惯把技能库当成一个私有的软件源来管理技能目录都用 Git 仓库单独维护版本号有语义化规范技能的 README 里写明依赖的工具版本发布时打 tag加载器支持按版本拉取。这套做法帮了大忙。有一次排查线上问题时发现同一个 Agent 同一个任务昨天表现很好今天突然崩了。后来查了半天发现不是模型升级导致的而是某个技能包被动过——里面示例文件被替换成了另一个格式而技能的版本号忘了更新缓存还留着旧的新旧加载混用了。从那以后技能包一律只读部署改动必须走版本升级这个教训对任何做 Agent 工程的人来说都值回票价。3. 从零到一开发一个技能以结构化简历筛选为例3.1 先定位场景边界再动笔写提示词很多新手一上来就写“你是一个资深 HR”这种开场白最没用。技能开发的第一步是定义技能的场景边界什么时候该用它、什么时候不该用它、输入是什么、输出给谁看。我做简历筛选技能时边界定义如下项目定义适用场景批量技术候选人简历初筛输出推荐排序表不适用场景社招终面评估、候选人沟通话术生成输入简历原始文本PDF 转出后或候选人 JSON输出结构化推荐表、每项匹配理由、待确认问题清单这个边界极其重要。如果不设边界模型会有一种“什么都能干”的倾向简历筛选任务做到一半它可能突然开始给你写问候邮件模板因为它觉得这样更有帮助。有了边界编排层就可以在任务不匹配时拒绝触发而不是强行执行。3.2 把任务拆成“澄清—初筛—纵深”三段式流程核心的工作流设计我总结成三段式这个模式在几乎所有技能开发里都适用第一段澄清输入。要求模型先列出理解到的筛选标准再检查输入数据是否完整。比如“候选人 A 的简历缺失工作年限”这一步就把后续误判的概率提前压下去。如果输入不完整直接输出“信息缺失清单”而不是硬着头皮判断。第二段执行初筛。按技能包里的 checklist 逐项核对每一项给出“命中/未命中/存疑”三态判定。这里特别强调不要只输出最终推荐结果中间判定过程必须留下。否则一旦结果错误你根本没法定位是哪个条件判错了。第三段纵深评估与输出。针对初筛通过的人再按更深维度做比较——比如“并发规模描述的真实性”“团队管理幅度”“业务匹配度”逐项打分最终汇总成表格。三段之间用明确的输出状态衔接第一段输出“澄清结果”第二段输出“初筛明细”第三段才输出“推荐名单”。我实测下来这种分段最大的好处是可调试线上如果出问题翻开中间结果一眼就知道卡在哪一步。3.3 为模型写“操作手册”而不是写“岗位职责”这是技能文档写作最容易错的点。很多人写技能内容时喜欢用目标式描述比如“评估候选人的技术深度。”这句话说了等于没说。模型知道什么叫“技术深度”吗它的训练数据里有海量关于“深度”的讨论但没有人告诉它在这个场景里怎么操作。模型能做的是把你的目标和它记忆里的模式强行对齐结果就是不稳定。正确的写法是行为式描述直接告诉模型做什么、观察什么、怎么判断“如果简历中出现‘主导设计’‘端到端负责’‘从 0 到 1 搭建’等描述标记为‘深度参与’如果仅出现‘参与开发’‘协助优化’等标记为‘常规参与’。”我给技能包写指令时的经验是每条指令都要能被一个初中生理解并执行才算是合格的技能指令。因为模型本质上不具备你的领域直觉它需要的是可执行的动作指令而不是愿景。更实操的技巧是把判断标准量化。比如“高并发经验”这个条件别写“具备高并发经验”要写“在简历中提取到 QPS/TPS/并发量数值且数值大于 5000或包含‘双十一’‘春晚’等明确高流量场景的记为命中。仅出现‘高并发’词汇但没有具体描述或场景佐证的记为存疑”。这样写模型的行为就从“猜”变成了“查”。3.4 用参考示例固化“好”与“坏”的样子技能的参考示例我建议每个维度都给三个合格正例、边界反例、典型错误例。举简历筛选的例子。同样一句项目描述“负责订单系统的性能优化提升了系统稳定性”在不同示例里可以这样区分合格正例描述“针对订单高峰期接口响应变慢的问题通过引入 Redis 缓存热点数据和异步化改造将下单接口 P99 耗时从 800ms 降到 200ms支撑日均百万级订单量。”——这个就很好有时间、有路径、有数字、有影响。边界反例描述“负责订单系统优化产出良好。”——没有具体技术动作没有指标按规则只能标记为“存疑”不能自己脑补。典型错误例描述“使用 Java 技术栈完成订单功能。”——这种如果都被标成“性能优化经验”那模型就是在幻觉。示例存在的意义是给模型划出一条“说人话”的边界。你不需要把这些示例全塞进 Prompt 里而是把它们放在技能包的 examples 文件中在运行时按需召回一两条效果远好于一次性全给。3.5 运行时校验让输出永远保持可控技能包的最后一道防线是校验。我的做法是在业务流程里嵌入一个“校验层”流程如下模型产出结果后不直接出库先经过校验逻辑校验不通过就触发二次修正或转人工。校验分三层结构校验输出是否符合 schema比如推荐表字段是否齐全JSON 能否解析日期格式是否统一。规则校验用代码实现技能包 rules 目录里的硬规则比如“推荐人数不得超过总候选人数的 30%”“未命中关键条件的候选人不得标记为高匹配”。一致性校验检查中间判定与最终结论是否矛盾。比如某个候选人初筛时“团队管理经验”判为未命中最终结论却推荐为“重点跟进”这就属于一致性冲突必须打回。这一层做得好技能的可靠性会有一个质的飞跃。我在职业技能裁减时给团队立过规矩宁可模型产出慢两秒也不能让错误结果直接出库。因为用户对 Agent 最脆弱的信任往往在一次错误结论上就被击碎了。4. 技能的评测与迭代怎么知道这个技能到底行不行4.1 构建评测集固定输入才能对比输出技能能不能用不能靠感觉。我在项目里会为每个技能准备一个 20~50 条样本的评测集里面覆盖标准样本、边界样本、异常输入、噪音输入。异常输入包括“PDF 转出来全是乱码”“候选人信息明显虚构”噪音输入包括“简历里有大段无关项目经历”“多个候选人信息拼在一份文件里”等等。评测集的价值在于让技能的迭代回归到可比较的轨道上。没有评测集的时候你会发现“优化”全靠玄学——今天调了提示词感觉效果好过两天又出问题根本分不清是提示词的原因还是模型的随机性。4.2 三个核心指标准确率、返工率、稳定性我主要看三个指标。准确率评测集里人工判定合格的输出比例。这个最容易理解但也最容易刷虚高因为评测集一旦被模型“记住”就失效了所以评测集要定期轮换一部分。返工率校验层打回的输出比例。这是我最关注的指标之一它反映的是“模型第一次做对的概率”。如果校验规则严格返工率会很高但准确率不一定低这里要平衡。稳定性同一份输入跑五遍结果一致的比例。注意模型有温度参数温度不为 0 时结果天然会波动。稳定性指标衡量的是“核心结论是否漂移”比如推荐名单一致哪怕推荐理由措辞不同也算稳定。我在简历筛选技能上做过一次量化对比第一版技能只改 SKILL.md 不配校验规则准确率约 71%稳定性 60%加上校验规则和分段工作流之后准确率到了 86%稳定性到了 82%再配上筛选后的参考示例准确率达到 91%稳定性 93%。这个提升曲线说明技能的收益不是单点优化而是层层叠加出来的。4.3 从一次线上错误反推技能缺陷技能迭代还有一个重要输入源线上错误日志。我们的做法是每次 Agent 输出结果被用户标记为“不满意”或“错误”时系统自动将该轮对话存档回传形成错误案例库。每周固定时间开发团队会拿错误案例去重新跑评测集把复现的错误归类再针对性修改技能。有一次印象很深用户投诉某个候选人明明有 12 年后端经验却被技能筛掉了。我们复盘发现问题出在技能的“经验年限提取”环节模型只提取了 PDF 文本中的阿拉伯数字但该候选人的简历把工作年限写成“十二年”。这属于典型的提取规则漏洞。修法是在规则里增加“中文数字与阿拉伯数字归一化”步骤并在示例里加了一条中文数字年限的样本。就这么一个小改动评测集准确率提升了一个多点。这类细节恰恰是技能设计里最见功力的地方。5. 常见坑与排查方法实录5.1 模型不按技能流程走总爱“自由发挥”做过 Agent 的人应该都有体会你给模型一个严谨的三段式流程它经常从第一段直接跳到最后一段把中间步骤省略掉。我的解决方法是状态强制 输出锚点。状态强制是指每一段的开头必须输出固定的状态标记比如[阶段1/澄清]模型输出这个标记后校验层就知道当前阶段如果发现阶段跳变就拒绝继续。输出锚点是指每段末尾必须输出固定的“本段结论”这样模型必须完成当前段才能进入下一段。5.2 技能描述太长模型根本“顾不上”你可能会写一个很完整的技能包目录一大堆规则好几十条。但模型的实际上下文窗口有限描述太长了它开始“丢三落四”。我的经验是加载时不全部塞入上下文只加载当前步骤需要的部分。比如在澄清阶段只加载澄清步骤的模板和 checklist进入初筛阶段再动态追加初筛的评分规则。这有点像做菜的时候只把用得上的调料放灶台而不是把整个厨房搬到桌上。5.3 多技能协作时的上下文污染这是后期才会遇到的问题。两个技能同时在一个 Agent 里跑技能 A 的中间输出可能严重干扰技能 B 的判断。我的处理办法是技能之间的上下文做物理隔离每个技能运行前缀带独立的工作区标识中间产物不共享跨技能只传递最终数据和必要的业务标签。刚开始有工程师觉得这样做太死板后来线上出现“技能 A 的判断影响技能 B 输出”的问题后所有人都承认隔离是对的方向。5.4 结构化输出总是崩坏让模型严格按照 JSON Schema 输出这事说起来容易跑起来经常翻车。我见过模型把 JSON 注释当成正式内容输出、在字符串里塞未转义换行、把一个字段名从work_years悄悄改成workYears等奇奇怪怪的问题。我的对策是两层防线第一层在技能规则里明确“输出必须通过 json.loads 解析否则视为失败”让模型知道校验是动真格的第二层代码里实现自动修复器常见的小毛病先用正则修复修复失败才触发重试。实测下来加了这两层后结构输出的成功率从最开始的 78% 提升到 97% 以上。6. 技能的可移植性与扩展方向6.1 技能包做成“跨平台”有没有可能现在各类 Agent 框架如雨后春笋技术栈五花八门。技能的理想状态是像 Docker 镜像一样在哪个平台都能跑。目前业界还在摸索阶段但我看好的是走“技能 内容资产”的路线也就是把 SKILL.md、流程规则、校验规则、示例文本都严格地与平台解耦只用标准文本格式Markdown、YAML、JSON描述。平台适配层只负责“翻译”把技能包加载为某个框架能识别的函数调用、Prompt 模板或工作流节点。我们团队做过一个实验同样一份简历筛选技能包分别在两个主流 Agent 框架上跑共用同一个校验层最终输出结果的一致性达到了 95% 以上。这说明技能层确实有机会成为跨平台的标准中间资产。以后做 Agent 开发有价值的资产可能不再是某个平台的配置而是一整套打磨好的技能库。6.2 从单体技能到技能编排系统技能多了之后还需要一个“调度大脑”用户输入需求后能自动判断需要哪些技能、按什么顺序编排、技能之间如何传参。我现在的实践是在技能库之外维护一层轻量的“技能路由配置”每条配置写明触发意图、所需技能列表、技能执行顺序、失败降级策略。这块做得好才能真正实现“一个 Agent 多面手”的效果。6.3 技能生态开源和复用是大方向最后聊聊未来的方向。我个人非常看好技能的开源生态——这就跟当年软件从单体应用走向组件化、模块化一样一旦技能包成为可流通的标准资产不同团队维护各自领域的技能整个社区的知识复用效率会提升一个量级。我自己也在整理手头十几个技能包打算把一些通用性强、不涉及业务隐私的技能开源出来让更多人少走弯路。根据我目前踩过的这么多坑和实测经验我最大的体会是Agent 工程的护城河不在于你调模型调得多好而在于你能不能把经验沉淀成一套可复用、可迭代、可校验的技能库。模型会升级、框架会更换但一套打磨精细的技能资产会持续产生复利。如果你正在做 Agent 项目建议你先停下来想想你的智能体到底有没有一套真正属于自己的“肌肉记忆”如果没有从今天开始攒吧。