最近大半年我一直在打磨一个给内部研发团队用的大模型问答助手。模型本身的对话能力是现成的真正让人抓狂的是另一件事同一件事换个问法它就干不明白今天答得没问题明天给它多塞一段上下文它就开始自由发挥。折腾好几个星期之后我发现问题的症结不在提示词写得多长而在于有没有把“做一件事的完整方法”沉淀成一个可以被加载、被路由、被版本管理的东西。这个思路圈子里通常就叫“skills”——模型技能包。如果你正在做智能体类应用或者已经被“提示词越写越长、行为却越来越飘”折腾到怀疑人生那这篇文章应该能帮上忙。我会把技能包到底是什么、为什么要单独做这一层、怎么设计一个高质量技能包、怎么接到工程链路里以及我踩过的那些坑完整地讲一遍。全程用实战视角说话有示例、有代码、有排查方法尽量让你看完就能动手。1. 模型技能到底是什么1.1 从“会聊天”到“会干活”技能的本质先从一个最容易混淆的点说起。模型的原生能力更像一种“通识能力”。你问它“怎么写周报”它能给你一套放之四海而皆准的模板但如果你说“我们研发团队的周报要自动汇总 git 提交记录、工时系统数据、上周遗留风险然后按固定模板分别输出给 leader 和 PM 两个版本”它立刻就懵了。这不是模型变笨了而是它缺一套“干这一件事的完整方法”。技能包解决的就是这个问题把“做什么、怎么做、做成什么样、什么不能做”打包成一个结构化文件在需要的时候注入给模型。我特别喜欢用“新员工培训”来打比方。你请了一个很聪明的实习生他智商高、学习能力强但你直接跟他说“帮我整理一下今天的会议纪要”他大概率会给你一份看起来漂亮、实际没法用的东西。这时候你真正需要做的是递给他一份 SOP 手册“会议纪要按 5W2H 结构整理行动项必须标注负责人和截止时间不确定的事项单独放到待确认清单里。”输出瞬间就稳定了。技能包就是给模型的 SOP 手册。模型的“聪明”是底座技能决定它在一件具体事情上能不能稳定地把活儿干好。这也是为什么很多人觉得“我的模型不聪明”其实问题往往出在“我的技能包没写好”。1.2 技能与工具调用、RAG、微调的边界做技术方案之前必须先把几个经常混在一起的概念理清楚。很多团队一上来就想微调模型或者拼命堆 RAG结果发现成本高、周期长问题还没解决。技能层恰好填补了它们之间的空白。方案解决什么问题本质典型成本和技能的关系工具调用Function Calling让模型能触发外部 API、执行命令扩展模型的“手脚”中需维护接口技能可以调度工具但工具本身不是技能RAG让模型知道原本不知道的信息把外部资料放进上下文中需维护知识库技能告诉模型“找到资料之后怎么处理”微调改变模型底层的知识或行为偏好修改模型权重高需训练与评测用技能层做轻量交互没必要上微调Prompt 模板给模型一段临时指令即用即走的文字低技能是结构化的、可版本化的扩展形态我见过一个真实案例某团队做内部文档问答一开始疯狂堆 RAG把几万份文档全灌进向量库。结果文档找得到但模型回答质量一直不稳——因为它不知道“找到文档之后要先判断文档版本是否有效再对比当前项目分支最后按固定格式给结论”。这些流程知识既不在文档里也不在模型参数里只存在于业务专家的脑子里。技能包就是把这些流程知识从人脑搬到模型上下文里的载体。2. 为什么要把技能单独做一层2.1 直接用长提示词的三个致命伤有人可能会问我直接把技能内容写进系统提示词不就行了为什么非要单独做一层我一开始也是这么干的直到吃了大亏。第一个问题叫“提示词膨胀失控”。最开始我的系统提示词只有 800 字后来业务方每加一个需求就往末尾追加一段三个月后膨胀到 4000 字。结果模型开始出现“选择性遗忘”——前面的指令被后面的指令覆盖甚至出现互相矛盾的规则。你很难通过“再改一行”来定位到底是哪句话导致了行为漂移。第二个问题叫“行为不可复现”。同一个需求用户上午问“帮我处理一下这个工单”下午问“这个工单你看下怎么办”模型的输出差异能大到像换了个人。原因很简单长提示词给模型留了太多自由发挥空间没有把动作固化成步骤。技能包的核心就是把“允许发挥”和“必须按步骤走”的边界划清楚。第三个问题更隐蔽业务知识和工程代码完全耦合。业务专家不懂提示词工程RD 懂技术但不精通业务。一旦所有逻辑都堆在那一大段 prompt 里等于只有 RD 能改业务专家只能干瞪眼。技能包是一个独立的、用自然语言写的文件业务专家可以直接审阅、提修改意见RD 负责把它做成可加载的格式。这本质上是一个“协作界面”的问题。2.2 技能层带来的工程化收益把技能单独抽一层短期看是多写了一点文件结构和加载逻辑长期看收益非常大。版本管理是第一个红利。技能包本质上是文本文件丢进 git 仓库就能做 diff、做评审、做回滚。改了一个技能可以清楚看到改了哪一行、影响哪个领域而不用像改大 prompt 那样提心吊胆。第二个红利是权限和灰度。不同业务线可以用不同的技能目录A 团队的技能不会污染 B 团队的请求。上线前还可以按“开发版、预发版、线上版”给技能打标签让一小部分流量先试用新版技能观察稳定了再全量放量。第三个红利是可测试性。每个技能包是独立单元可以用一组固定的黄金测试样本去回归。技能 2.0 改完之后把 20 条历史问题跑一遍对比输出质量合格才允许上线。这在长 prompt 模式下基本做不到。第四个红利是可观测性。技能层能让你统计“每个用户请求命中了哪个技能”“这个技能的采纳率是多少”“失败样本长什么样”。有了这些数据你才知道该优化哪个环节而不是靠感觉瞎调。3. 设计一个高质量技能包的完整流程3.1 目录结构与元信息设计先看一个我目前比较常用的技能目录结构skills/ 工单分级与转交_v2/ SKILL.md references/ ownership_map.json sla_policy.md assets/ grading_table.md每个技能一个目录目录名带版本号SKILL.md 是技能主文件控制在 15002000 token 以内references 放按需加载的长资料比如负责人映射表、SLA 策略assets 放评分表、模板等辅助素材。这个结构是实践之后才定下来的。最早我把所有内容都塞进一个文件结果技能文件越来越长每次请求都要把几千 token 的指令全部注入上下文响应变慢、费用变高。后来强制规定主文件只放“模型必须时刻记住的规则”参考资料一律外置由调用方按需加载。这就像给员工一本《员工手册》而不是让他每次上班前把公司所有制度背一遍。SKILL.md 的元信息建议用 Markdown Frontmatter 格式写在文件最开头方便程序解析。版本号一定要写否则你根本不知道线上跑的是哪个版本出了问题都没法回溯。3.2 SKILL.md 字段拆解与完整示例下面给一个完整的技能包示例场景是“客服工单分级与转交”。这类技能非常适合复用因为判断逻辑明确、输出格式固定模型只需要按流程执行。--- name: 工单分级与转交 description: | 用户提交客服工单内容时判断工单的紧急程度和业务归属 输出建议的响应时限和处理小组。 当用户只是询问工单状态时不要使用本技能 不要在客户身份信息不完整时自行假设客户等级。 version: 2.1 --- # Instructions ## 目标 将一条客服工单文本转化为结构化的分级与转交结论。 ## 步骤 1. 提取关键要素客户ID、问题描述、影响范围、客户等级。 2. 调用分级表见 assets/grading_table.md 判断工单级别为 P0/P1/P2。 3. 根据 references/ownership_map.json确定对应处理小组。 4. 当影响范围或客户等级缺失时标记“信息不足” 不得猜填补全。 ## 输出格式 只输出如下 JSON不要附加任何解释性文字 { ticket_id: string, level: P0 | P1 | P2, owner_group: string, sla_hours: number, missing: [客户等级] } ## 边界 - 本技能只做分级和转交不做回复话术生成。 - 若工单描述明显不属于客服范畴如研发需求 输出 out_of_scope: true。逐字段解释一下设计意图。name 字段就是技能的 ID路由层靠它做索引保持唯一、稳定。description 字段是整个技能包里最重要的部分。它不光是给人看的说明更是路由系统判断“什么时候该用这个技能”的依据。写法上我有个很深的体会必须同时写清楚“什么时候用”和“什么时候不用”。正面触发描述让路由系统能命中负面触发描述防止误匹配。比如上面例子就明确写了“用户只是询问工单状态时不要使用”这一句话能挡掉大量误路由。Instructions 部分按“目标—步骤—边界—输出”四段式组织。为什么一定要这个顺序因为模型对前缀内容的注意力更强把目标放在最前面能让它在执行时始终围绕目标展开输出格式紧跟其后等于先给它画好“答卷模板”减少自由发挥的概率。边界这一段很多人会忽略但恰恰是它决定了技能能不能长期稳定。模型没有边界意识你不写清楚“不做什么”它就什么都有可能做。你要么给它划好跑道要么接受它随时跑偏的事实。3.3 三条经验准则第一description 是技能命中率的胜负手。我见过太多人精心写了 stepsdescription 却只写了“简历筛选”四个字。后果是路由系统完全无法判断什么时候该调用它技能等于白写。正确做法是把触发条件、上下文特征、禁区信息全部浓缩进去哪怕长一点也没关系。宁可让 description 像一段“业务规则说明”也不要让它变成一句标签。第二参考示例必须给而且是准确的正反例。模型对“演示效应”极其敏感。只给规则、不给示例模型会用自己脑子里的“通识模板”来填空。你给它一个坏样例它能精准地模仿坏样例。所以每个技能包里至少放一个“输入→输出”的对子把输入文本和期望的 JSON 都写上。示例越贴近真实业务效果越好。第三输出格式约束要放在最前面用强制语气。比如“只输出如下 JSON不要附加任何解释性文字”这句话要写在 Instructions 靠前的位置。放在中间或末尾模型往往会忽略。把它放在步骤之前等于先定规矩再干活。我踩过最惨的一次坑是模型在一个分类任务里输出了三段话开头全是“好的我来帮您分析一下”直接把下游解析逻辑干挂了。4. 技能接入与调用链路的工程实现4.1 四段链路加载、路由、执行、观测技能包设计得再好没有工程链路承接也只是个 Markdown 文件。完整接入方案我拆成四段每段都有独立职责和常见陷阱。加载阶段负责在服务启动时扫描技能目录解析每个 SKILL.md 的元信息建立技能索引。这个阶段的关键点是容错一个技能文件格式坏了不应该导致整个服务起不来要能跳过坏文件并报警。路由阶段负责把用户输入映射到最合适的技能。这是整个链路的技术难点后面我会单独展开。执行阶段负责把命中的技能指令注入模型上下文并加上会话历史、业务数据让模型按技能要求产出结果。这里要控制注入顺序和 token 预算否则技能起不到应有的作用。观测阶段负责记录每一个请求的路由结果、技能版本、输出校验结果。没有观测数据后面所有优化都是盲人摸象。4.2 加载与路由的最小可运行实现先给一个最小加载实现Python 伪代码级别可以直接抄去改import os from pathlib import Path SKILL_ROOT Path(./skills) def load_skills(root: Path) - dict: skills {} for skill_dir in root.iterdir(): md_file skill_dir / SKILL.md if not md_file.exists(): continue text md_file.read_text(encodingutf-8) meta parse_frontmatter(text) # 解析 --- 之间的元信息 if not meta.get(name): continue skills[meta[name]] { description: meta[description], content: text, # 完整技能文本 version: meta.get(version, 0.0.0), } return skills解析 Frontmatter 可以用现成的库比如 Python 的pymdownx或者python-frontmatter不建议自己写正则硬解边界情况太多。路由是重头戏也是最容易偷懒又最危险的地方。最朴素的做法是用“关键词包含”来判断比如用户输入里出现“工单”两个字就命中工单技能。实测下来这种方案几乎不可用用户表达千变万化关键词规则越写越多最终变成一团乱麻。我更推荐两种方案。第一种是向量召回把每个技能的 description 做 embedding用户输入也做 embedding用余弦相似度召回 Top-K再交给下游决策。这种方案对语义多样性的容忍度很高缺点是服务需要引入向量计算能力。第二种是模型自选把技能名称和简短说明放给模型让模型自己决定当前请求该用哪个技能。这个方案准确率高但会多一次模型调用延迟会加一点。生产环境我一般用“向量召回 优先级排序”的组合。每个技能包里的priority字段决定同时命中多个技能时谁优先避免出现“两个技能打架”的情况。4.3 执行时的上下文组装顺序技能命中之后怎么把内容放进上下文直接影响最终效果。我的经验是分层组装顺序非常重要系统指令固定不变的全局行为规则比如“你是某公司的智能助手回答要简洁”。技能主文件目标、步骤、边界、输出格式。参考资料从 references 按需加载的数据。会话历史用户最近的对话内容。当前输入用户这一轮的问题。这个顺序的核心逻辑是越靠近“约束”的内容越优先让模型先建立行为框架再读对话内容。如果把技能放最后模型很可能被前面冗长的历史对话带偏。token 预算也要控制。技能主文件建议不超过 2000 token参考资料单独扣预算避免一次请求注入 8000 token 导致响应极慢。真遇到复杂技能宁可拆分成多个子技能也不要追求一个超长技能包解决所有问题。5. 常见问题排查与避坑实录5.1 问题速查表症状可能原因解决办法模型完全不调用技能description 描述太窄路由没命中重写 description加入更多触发同义词和场景描述技能命中但输出格式不对输出格式约束写得太靠后或被历史对话干扰把输出格式移到 Instructions 前面强制“只输出...”两个技能经常互抢边界重叠路由召回多个结果明确各自的正面/负面触发条件用 priority 排序技能改了之后行为反而变差改动没有经过测试集回归建立 1020 条黄金样本每次改动跑一遍注入技能后响应明显变慢技能主文件过大或参考资料无脑全加载精简主文件到 2000 token 内references 按需加载模型会自己脑补缺失信息边界规则没写“信息不足时怎么办”明确要求标记“缺失字段”禁止猜填5.2 一个完整的排查路径如果你遇到了“模型就是不按技能走”的问题强烈建议按下面这套顺序排查不要一上来就改 prompt。第一步看路由日志。确认用户这句输入到底命中了哪个技能还是压根没命中。很多看似“模型不听话”的问题其实是路由阶段就选错技能了。第二步做最小复现。把用户输入、技能文本、系统提示词全部抽出来在一个干净的测试环境里单独复现。如果复现不出来说明问题出在会话历史或上下文污染而不是技能本身。第三步降级对比。把技能内容临时当作普通提示词直接注入不做任何路由看行为是否恢复。如果降级后行为正常说明问题在加载或组装链路如果降级后行为依旧异常说明技能指令本身有问题。第四步反向补规则。拿到失败样本之后分析模型到底是在哪一步跑偏的把失败原因浓缩成一句反例写进边界区。比如模型总是漏掉“信息不足”标记就在边界里补一句“缺失关键字段时必须输出 missing 数组不得自行假设”。这套流程我用了很久解决过不少疑难杂症。印象最深的一次是模型在一个分类任务里始终把“退款咨询”误判成“投诉工单”路由命中没问题、指令也没问题最后发现是历史对话里用户之前提过“投诉”两个字把模型带偏了。最终靠“边界区增加一句‘以当前工单文本为准忽略历史对话中的分类倾向’”解决。5.3 技能包的生命周期管理技能包不是写一次就完事的东西它的生命周期需要和代码一样被管理。版本号必须显式暴露到调用链路里。我的习惯是在加载时记录技能版本并把版本号带进观测日志。这样一旦线上出现质量回退能立刻定位到“是哪个版本的技能导致的”一键切回旧版本。灰度发布也很重要。大型一点的项目同一个技能可以先让 5% 的请求用新版跑一天看观测数据没问题再逐步放量。新版技能和旧版技能的区别可能只差一句话但这句话可能直接影响线上体验灰度是成本最低的安全网。黄金样本回归是最值得投入的一件事。挑 2030 条历史真实问题作为每个技能的固定测试集。每次改技能跑一遍测试集人工或者用规则判断输出是否达标。这套机制能挡住大多数“改坏了但当时没发现”的情况。我的实测经验是有了技能层和黄金样本之后系统行为的稳定性比长 Prompt 时代提升了不止一个量级。最后分享一个我在实际维护中养成的习惯每周从真实对话记录里捞 5 条“模型答非所问”的样本把失败原因归一下类。凡是能靠边界规则解决的就更新到对应 SKILL.md 里凡是路由漏掉的就补到 description 里。半年下来技能命中率从刚开始的六成涨到了九成以上。技能的瓶颈从来不在模型而在于你对业务流程拆解得够不够细。拆得越细技能越稳模型越省心。
最近大半年我一直在打磨一个给内部研发团队用的大模型问答助手。模型本身的对话能力是现成的真正让人抓狂的是另一件事同一件事换个问法它就干不明白今天答得没问题明天给它多塞一段上下文它就开始自由发挥。折腾好几个星期之后我发现问题的症结不在提示词写得多长而在于有没有把“做一件事的完整方法”沉淀成一个可以被加载、被路由、被版本管理的东西。这个思路圈子里通常就叫“skills”——模型技能包。如果你正在做智能体类应用或者已经被“提示词越写越长、行为却越来越飘”折腾到怀疑人生那这篇文章应该能帮上忙。我会把技能包到底是什么、为什么要单独做这一层、怎么设计一个高质量技能包、怎么接到工程链路里以及我踩过的那些坑完整地讲一遍。全程用实战视角说话有示例、有代码、有排查方法尽量让你看完就能动手。1. 模型技能到底是什么1.1 从“会聊天”到“会干活”技能的本质先从一个最容易混淆的点说起。模型的原生能力更像一种“通识能力”。你问它“怎么写周报”它能给你一套放之四海而皆准的模板但如果你说“我们研发团队的周报要自动汇总 git 提交记录、工时系统数据、上周遗留风险然后按固定模板分别输出给 leader 和 PM 两个版本”它立刻就懵了。这不是模型变笨了而是它缺一套“干这一件事的完整方法”。技能包解决的就是这个问题把“做什么、怎么做、做成什么样、什么不能做”打包成一个结构化文件在需要的时候注入给模型。我特别喜欢用“新员工培训”来打比方。你请了一个很聪明的实习生他智商高、学习能力强但你直接跟他说“帮我整理一下今天的会议纪要”他大概率会给你一份看起来漂亮、实际没法用的东西。这时候你真正需要做的是递给他一份 SOP 手册“会议纪要按 5W2H 结构整理行动项必须标注负责人和截止时间不确定的事项单独放到待确认清单里。”输出瞬间就稳定了。技能包就是给模型的 SOP 手册。模型的“聪明”是底座技能决定它在一件具体事情上能不能稳定地把活儿干好。这也是为什么很多人觉得“我的模型不聪明”其实问题往往出在“我的技能包没写好”。1.2 技能与工具调用、RAG、微调的边界做技术方案之前必须先把几个经常混在一起的概念理清楚。很多团队一上来就想微调模型或者拼命堆 RAG结果发现成本高、周期长问题还没解决。技能层恰好填补了它们之间的空白。方案解决什么问题本质典型成本和技能的关系工具调用Function Calling让模型能触发外部 API、执行命令扩展模型的“手脚”中需维护接口技能可以调度工具但工具本身不是技能RAG让模型知道原本不知道的信息把外部资料放进上下文中需维护知识库技能告诉模型“找到资料之后怎么处理”微调改变模型底层的知识或行为偏好修改模型权重高需训练与评测用技能层做轻量交互没必要上微调Prompt 模板给模型一段临时指令即用即走的文字低技能是结构化的、可版本化的扩展形态我见过一个真实案例某团队做内部文档问答一开始疯狂堆 RAG把几万份文档全灌进向量库。结果文档找得到但模型回答质量一直不稳——因为它不知道“找到文档之后要先判断文档版本是否有效再对比当前项目分支最后按固定格式给结论”。这些流程知识既不在文档里也不在模型参数里只存在于业务专家的脑子里。技能包就是把这些流程知识从人脑搬到模型上下文里的载体。2. 为什么要把技能单独做一层2.1 直接用长提示词的三个致命伤有人可能会问我直接把技能内容写进系统提示词不就行了为什么非要单独做一层我一开始也是这么干的直到吃了大亏。第一个问题叫“提示词膨胀失控”。最开始我的系统提示词只有 800 字后来业务方每加一个需求就往末尾追加一段三个月后膨胀到 4000 字。结果模型开始出现“选择性遗忘”——前面的指令被后面的指令覆盖甚至出现互相矛盾的规则。你很难通过“再改一行”来定位到底是哪句话导致了行为漂移。第二个问题叫“行为不可复现”。同一个需求用户上午问“帮我处理一下这个工单”下午问“这个工单你看下怎么办”模型的输出差异能大到像换了个人。原因很简单长提示词给模型留了太多自由发挥空间没有把动作固化成步骤。技能包的核心就是把“允许发挥”和“必须按步骤走”的边界划清楚。第三个问题更隐蔽业务知识和工程代码完全耦合。业务专家不懂提示词工程RD 懂技术但不精通业务。一旦所有逻辑都堆在那一大段 prompt 里等于只有 RD 能改业务专家只能干瞪眼。技能包是一个独立的、用自然语言写的文件业务专家可以直接审阅、提修改意见RD 负责把它做成可加载的格式。这本质上是一个“协作界面”的问题。2.2 技能层带来的工程化收益把技能单独抽一层短期看是多写了一点文件结构和加载逻辑长期看收益非常大。版本管理是第一个红利。技能包本质上是文本文件丢进 git 仓库就能做 diff、做评审、做回滚。改了一个技能可以清楚看到改了哪一行、影响哪个领域而不用像改大 prompt 那样提心吊胆。第二个红利是权限和灰度。不同业务线可以用不同的技能目录A 团队的技能不会污染 B 团队的请求。上线前还可以按“开发版、预发版、线上版”给技能打标签让一小部分流量先试用新版技能观察稳定了再全量放量。第三个红利是可测试性。每个技能包是独立单元可以用一组固定的黄金测试样本去回归。技能 2.0 改完之后把 20 条历史问题跑一遍对比输出质量合格才允许上线。这在长 prompt 模式下基本做不到。第四个红利是可观测性。技能层能让你统计“每个用户请求命中了哪个技能”“这个技能的采纳率是多少”“失败样本长什么样”。有了这些数据你才知道该优化哪个环节而不是靠感觉瞎调。3. 设计一个高质量技能包的完整流程3.1 目录结构与元信息设计先看一个我目前比较常用的技能目录结构skills/ 工单分级与转交_v2/ SKILL.md references/ ownership_map.json sla_policy.md assets/ grading_table.md每个技能一个目录目录名带版本号SKILL.md 是技能主文件控制在 15002000 token 以内references 放按需加载的长资料比如负责人映射表、SLA 策略assets 放评分表、模板等辅助素材。这个结构是实践之后才定下来的。最早我把所有内容都塞进一个文件结果技能文件越来越长每次请求都要把几千 token 的指令全部注入上下文响应变慢、费用变高。后来强制规定主文件只放“模型必须时刻记住的规则”参考资料一律外置由调用方按需加载。这就像给员工一本《员工手册》而不是让他每次上班前把公司所有制度背一遍。SKILL.md 的元信息建议用 Markdown Frontmatter 格式写在文件最开头方便程序解析。版本号一定要写否则你根本不知道线上跑的是哪个版本出了问题都没法回溯。3.2 SKILL.md 字段拆解与完整示例下面给一个完整的技能包示例场景是“客服工单分级与转交”。这类技能非常适合复用因为判断逻辑明确、输出格式固定模型只需要按流程执行。--- name: 工单分级与转交 description: | 用户提交客服工单内容时判断工单的紧急程度和业务归属 输出建议的响应时限和处理小组。 当用户只是询问工单状态时不要使用本技能 不要在客户身份信息不完整时自行假设客户等级。 version: 2.1 --- # Instructions ## 目标 将一条客服工单文本转化为结构化的分级与转交结论。 ## 步骤 1. 提取关键要素客户ID、问题描述、影响范围、客户等级。 2. 调用分级表见 assets/grading_table.md 判断工单级别为 P0/P1/P2。 3. 根据 references/ownership_map.json确定对应处理小组。 4. 当影响范围或客户等级缺失时标记“信息不足” 不得猜填补全。 ## 输出格式 只输出如下 JSON不要附加任何解释性文字 { ticket_id: string, level: P0 | P1 | P2, owner_group: string, sla_hours: number, missing: [客户等级] } ## 边界 - 本技能只做分级和转交不做回复话术生成。 - 若工单描述明显不属于客服范畴如研发需求 输出 out_of_scope: true。逐字段解释一下设计意图。name 字段就是技能的 ID路由层靠它做索引保持唯一、稳定。description 字段是整个技能包里最重要的部分。它不光是给人看的说明更是路由系统判断“什么时候该用这个技能”的依据。写法上我有个很深的体会必须同时写清楚“什么时候用”和“什么时候不用”。正面触发描述让路由系统能命中负面触发描述防止误匹配。比如上面例子就明确写了“用户只是询问工单状态时不要使用”这一句话能挡掉大量误路由。Instructions 部分按“目标—步骤—边界—输出”四段式组织。为什么一定要这个顺序因为模型对前缀内容的注意力更强把目标放在最前面能让它在执行时始终围绕目标展开输出格式紧跟其后等于先给它画好“答卷模板”减少自由发挥的概率。边界这一段很多人会忽略但恰恰是它决定了技能能不能长期稳定。模型没有边界意识你不写清楚“不做什么”它就什么都有可能做。你要么给它划好跑道要么接受它随时跑偏的事实。3.3 三条经验准则第一description 是技能命中率的胜负手。我见过太多人精心写了 stepsdescription 却只写了“简历筛选”四个字。后果是路由系统完全无法判断什么时候该调用它技能等于白写。正确做法是把触发条件、上下文特征、禁区信息全部浓缩进去哪怕长一点也没关系。宁可让 description 像一段“业务规则说明”也不要让它变成一句标签。第二参考示例必须给而且是准确的正反例。模型对“演示效应”极其敏感。只给规则、不给示例模型会用自己脑子里的“通识模板”来填空。你给它一个坏样例它能精准地模仿坏样例。所以每个技能包里至少放一个“输入→输出”的对子把输入文本和期望的 JSON 都写上。示例越贴近真实业务效果越好。第三输出格式约束要放在最前面用强制语气。比如“只输出如下 JSON不要附加任何解释性文字”这句话要写在 Instructions 靠前的位置。放在中间或末尾模型往往会忽略。把它放在步骤之前等于先定规矩再干活。我踩过最惨的一次坑是模型在一个分类任务里输出了三段话开头全是“好的我来帮您分析一下”直接把下游解析逻辑干挂了。4. 技能接入与调用链路的工程实现4.1 四段链路加载、路由、执行、观测技能包设计得再好没有工程链路承接也只是个 Markdown 文件。完整接入方案我拆成四段每段都有独立职责和常见陷阱。加载阶段负责在服务启动时扫描技能目录解析每个 SKILL.md 的元信息建立技能索引。这个阶段的关键点是容错一个技能文件格式坏了不应该导致整个服务起不来要能跳过坏文件并报警。路由阶段负责把用户输入映射到最合适的技能。这是整个链路的技术难点后面我会单独展开。执行阶段负责把命中的技能指令注入模型上下文并加上会话历史、业务数据让模型按技能要求产出结果。这里要控制注入顺序和 token 预算否则技能起不到应有的作用。观测阶段负责记录每一个请求的路由结果、技能版本、输出校验结果。没有观测数据后面所有优化都是盲人摸象。4.2 加载与路由的最小可运行实现先给一个最小加载实现Python 伪代码级别可以直接抄去改import os from pathlib import Path SKILL_ROOT Path(./skills) def load_skills(root: Path) - dict: skills {} for skill_dir in root.iterdir(): md_file skill_dir / SKILL.md if not md_file.exists(): continue text md_file.read_text(encodingutf-8) meta parse_frontmatter(text) # 解析 --- 之间的元信息 if not meta.get(name): continue skills[meta[name]] { description: meta[description], content: text, # 完整技能文本 version: meta.get(version, 0.0.0), } return skills解析 Frontmatter 可以用现成的库比如 Python 的pymdownx或者python-frontmatter不建议自己写正则硬解边界情况太多。路由是重头戏也是最容易偷懒又最危险的地方。最朴素的做法是用“关键词包含”来判断比如用户输入里出现“工单”两个字就命中工单技能。实测下来这种方案几乎不可用用户表达千变万化关键词规则越写越多最终变成一团乱麻。我更推荐两种方案。第一种是向量召回把每个技能的 description 做 embedding用户输入也做 embedding用余弦相似度召回 Top-K再交给下游决策。这种方案对语义多样性的容忍度很高缺点是服务需要引入向量计算能力。第二种是模型自选把技能名称和简短说明放给模型让模型自己决定当前请求该用哪个技能。这个方案准确率高但会多一次模型调用延迟会加一点。生产环境我一般用“向量召回 优先级排序”的组合。每个技能包里的priority字段决定同时命中多个技能时谁优先避免出现“两个技能打架”的情况。4.3 执行时的上下文组装顺序技能命中之后怎么把内容放进上下文直接影响最终效果。我的经验是分层组装顺序非常重要系统指令固定不变的全局行为规则比如“你是某公司的智能助手回答要简洁”。技能主文件目标、步骤、边界、输出格式。参考资料从 references 按需加载的数据。会话历史用户最近的对话内容。当前输入用户这一轮的问题。这个顺序的核心逻辑是越靠近“约束”的内容越优先让模型先建立行为框架再读对话内容。如果把技能放最后模型很可能被前面冗长的历史对话带偏。token 预算也要控制。技能主文件建议不超过 2000 token参考资料单独扣预算避免一次请求注入 8000 token 导致响应极慢。真遇到复杂技能宁可拆分成多个子技能也不要追求一个超长技能包解决所有问题。5. 常见问题排查与避坑实录5.1 问题速查表症状可能原因解决办法模型完全不调用技能description 描述太窄路由没命中重写 description加入更多触发同义词和场景描述技能命中但输出格式不对输出格式约束写得太靠后或被历史对话干扰把输出格式移到 Instructions 前面强制“只输出...”两个技能经常互抢边界重叠路由召回多个结果明确各自的正面/负面触发条件用 priority 排序技能改了之后行为反而变差改动没有经过测试集回归建立 1020 条黄金样本每次改动跑一遍注入技能后响应明显变慢技能主文件过大或参考资料无脑全加载精简主文件到 2000 token 内references 按需加载模型会自己脑补缺失信息边界规则没写“信息不足时怎么办”明确要求标记“缺失字段”禁止猜填5.2 一个完整的排查路径如果你遇到了“模型就是不按技能走”的问题强烈建议按下面这套顺序排查不要一上来就改 prompt。第一步看路由日志。确认用户这句输入到底命中了哪个技能还是压根没命中。很多看似“模型不听话”的问题其实是路由阶段就选错技能了。第二步做最小复现。把用户输入、技能文本、系统提示词全部抽出来在一个干净的测试环境里单独复现。如果复现不出来说明问题出在会话历史或上下文污染而不是技能本身。第三步降级对比。把技能内容临时当作普通提示词直接注入不做任何路由看行为是否恢复。如果降级后行为正常说明问题在加载或组装链路如果降级后行为依旧异常说明技能指令本身有问题。第四步反向补规则。拿到失败样本之后分析模型到底是在哪一步跑偏的把失败原因浓缩成一句反例写进边界区。比如模型总是漏掉“信息不足”标记就在边界里补一句“缺失关键字段时必须输出 missing 数组不得自行假设”。这套流程我用了很久解决过不少疑难杂症。印象最深的一次是模型在一个分类任务里始终把“退款咨询”误判成“投诉工单”路由命中没问题、指令也没问题最后发现是历史对话里用户之前提过“投诉”两个字把模型带偏了。最终靠“边界区增加一句‘以当前工单文本为准忽略历史对话中的分类倾向’”解决。5.3 技能包的生命周期管理技能包不是写一次就完事的东西它的生命周期需要和代码一样被管理。版本号必须显式暴露到调用链路里。我的习惯是在加载时记录技能版本并把版本号带进观测日志。这样一旦线上出现质量回退能立刻定位到“是哪个版本的技能导致的”一键切回旧版本。灰度发布也很重要。大型一点的项目同一个技能可以先让 5% 的请求用新版跑一天看观测数据没问题再逐步放量。新版技能和旧版技能的区别可能只差一句话但这句话可能直接影响线上体验灰度是成本最低的安全网。黄金样本回归是最值得投入的一件事。挑 2030 条历史真实问题作为每个技能的固定测试集。每次改技能跑一遍测试集人工或者用规则判断输出是否达标。这套机制能挡住大多数“改坏了但当时没发现”的情况。我的实测经验是有了技能层和黄金样本之后系统行为的稳定性比长 Prompt 时代提升了不止一个量级。最后分享一个我在实际维护中养成的习惯每周从真实对话记录里捞 5 条“模型答非所问”的样本把失败原因归一下类。凡是能靠边界规则解决的就更新到对应 SKILL.md 里凡是路由漏掉的就补到 description 里。半年下来技能命中率从刚开始的六成涨到了九成以上。技能的瓶颈从来不在模型而在于你对业务流程拆解得够不够细。拆得越细技能越稳模型越省心。
