写技能的时候我踩过最大的坑就是把Agent的技能写得像教科书目录——条理清晰、面面俱到结果Agent每次调用都犹豫不决甚至把不相关的技能拼接起来产出一堆莫名其妙的中间结果。后来我把整套“agent-skills”体系推翻重写才慢慢摸清了门道。先交代一下背景。我做的这套东西本质上是一个给Agent装配“职业技能包”的框架。它要解决的核心矛盾是底层大模型什么都懂一点但什么都不精遇到专业任务时如果完全依赖模型自由发挥输出质量就像抽卡。而一套精心设计的技能体系相当于给Agent一本图文并茂的操作手册告诉它遇到什么样的活按什么流程干调什么工具产出什么格式每一步的关键参数是什么。这篇文章不聊花哨的概念直接拆解agent-skills的骨架、实操过程和我在真实项目里趟出来的经验。如果你正在做Agent开发或者被“Agent能力不可控”这个问题折磨过这篇内容应该能帮上忙。1. 项目整体设计与核心思路1.1 技能不是指令而是“可复用的能力封装”刚开始接触Agent开发的人很容易把“技能”和“提示词”混为一谈。觉得给Agent写一段详细的prompt告诉它遇到问题怎么一步步做就算是给Agent配技能了。这个理解方向对但粒度差得很远。我的实践结论是技能skill不应该是写进系统提示词里的一段话而应该是一个结构化的、可以被按需加载和调用的独立模块。它类似人脑海里的“工作程序”——你不需要在每次写代码前把“如何设计类结构”整个过一遍你只需要知道项目需要什么然后在合适的时候把对应的知识和方法调出来用。在设计agent-skills时我参考了前端工程里“组件化”的思路。每个技能像是一个独立组件有自己的输入输出接口、依赖关系、版本信息和使用约束。Agent在做任务规划时先看一眼任务目标决定要调用哪些技能然后按技能定义里写的流程去执行。这里有一个很重要的设计决策技能文件里的内容不仅是给模型看的“说明书”还是给调用方看的“契约”。也就是说技能文件本身要能被程序解析也要能被模型理解。双轨制是这套体系稳定运行的基础。1.2 为什么选择文件目录式的技能组织方式方案选型阶段我有过几个候选方案把所有技能写在一个巨大的YAML/JSON配置里启动时全量加载用数据库存技能运行时按需查询把每个技能做成一个目录目录里包含描述文件、提示词模板、工具调用配置等运行时按需发现和加载最终我选了第三个方案——文件目录式组织。原因很简单一是可维护性好一个技能对应一个目录增删改都不影响其他技能二是可读性好整个技能库的结构一眼就能看懂协同开发时不用借助额外的管理后台三是与Git等版本控制工具配合得天衣无缝每个技能的变更历史都清清楚楚回滚起来方便。这套方案还有一个意外的好处技能的“热插拔”变得非常容易。我在多轮对话的场景里根据用户意图动态决定加载哪几个技能目录不相关的技能完全不进入模型的上下文窗口这样既省token又降低了模型“混淆工具用途”的概率。1.3 技能体系的层次划分与职责边界在agent-skills里我把技能分成了三个层次每层的职责边界定义得很清楚原子技能完成一个不可再拆分的单一动作比如“发送HTTP请求”“执行SQL查询”“计算两段文本的相似度”。原子技能通常对应一个具体的工具或API。复合技能把多个原子技能按业务逻辑串联起来形成一个完整的工作流。比如“拉取网页内容并提取正文”“批量生成图片并打水印”。策略技能这一类是最有意思的。它不直接操作工具而是决定“在什么条件下用什么样的顺序和策略去组合使用下面的技能”。策略技能承载的是行业经验比如“处理用户投诉时先安抚情绪再定位问题”这类流程性的软知识。这个层次划分的价值在于责任清晰以后调优就有了抓手。我的经验是Agent表现不好时先判断是哪个层次的问题。如果工具调用参数总是错那是原子技能层的工具定义不清晰如果步骤顺序总是乱那是复合技能层的编排逻辑有缺陷如果是面对模糊需求时不知道选哪条路径那是策略技能层的决策规则没写明白。提示技能粒度不是越细越好。原子技能如果细到“点击某个按钮”会让技能数量爆炸规划开销大增如果粗到“做一次完整的市场分析”就又退化成提示词了。粒度把控的参考标准是——技能的执行结果是否具有明确的、可检验的完成标志。2. 技能文件的结构设计与编写规范2.1 一个技能文件的完整骨架我的技能目录结构大致长这样skills/ ├── web_search/ │ ├── SKILL.md │ ├── tools.json │ ├── templates/ │ │ └── search_prompt.j2 │ └── assets/ │ └── example_output.json ├── data_analysis/ │ ├── SKILL.md │ ├── tools.json │ └── references/ │ └── metric_definitions.md └── customer_email_reply/ ├── SKILL.md ├── workflow.yaml └── examples/ └── good_bad_cases.md核心文件是SKILL.md。它是一份面向模型的主文档统一使用Markdown格式方便模型理解和解析。我习惯的字段包括name技能名称全局唯一description用自然语言描述“这个技能解决什么问题、在什么场景下使用”这段话就是模型做意图匹配时的依据when_to_use明确列出“适用场景”和“不适用场景”正反两面写减少误调用workflow核心执行流程用编号步骤描述完整操作过程dependencies依赖哪些原子技能或外部工具output_format输出结构的规范说明一个简单示例## name send_invoice_email ## description 根据订单信息和客户联系方式生成发票邮件并调用邮件API发送。 ## when_to_use - 用户要求发送发票、账单或付款凭证时 - 订单已完成支付、需要把电子发票发给客户时 不适用场景 - 用户仅询问发票金额而未要求发送邮件 - 收件人信息缺失或不明确此时应先向用户确认 ## workflow 1. 从订单数据库提取发票数据校验发票号与金额 2. 使用 invoice_email_template 渲染邮件正文 3. 调用 sendgrid_send 工具发送邮件 4. 返回邮件发送状态和 message_id ## dependencies - render_template原子技能 - sendgrid_send原子技能 - order_db_query原子技能 ## output_format 成功时返回 JSON {status: sent, message_id: ...} 失败时返回错误码和人类可读的错误描述。2.2 description的描述质量直接决定调用准确率这是我在实践中最深的一点体会模型选择技能时绝大多数情况是靠读description来判断“这个技能适不适合当前任务”。所以description写得好不好直接决定了技能调用准确率的天花板。什么叫写得好两个标准具体、有区分度。我见过很多人写技能描述时草草一句“用于处理数据分析相关任务”这种描述放在一个技能库里跟没说一样。模型在多个技能之间犹豫时越笼统的描述越容易造成误判。我现在的写法是把关键细节前置并刻意加入“限定条件”。比如同样是搜索类技能我会区分成“web_search”和“document_search”两个技能前者的描述强调“搜索互联网公开网页内容”后者的描述强调“在用户已上传或系统知识库的文档内进行检索”。这样一来模型根据输入特征就能做出明确选择误调用少了一大半。另外在描述里写明“不适用场景”非常管用。Agent卡住然后强行调用技能的情况大多是它判断不出边界。有了“不适用场景”的提示模型在犹豫时更容易走向“请求用户补充信息”的正确分支而不是瞎猜。2.3 workflow的写法基于“约束视角”而非“教程视角”workflow段是最容易写崩的地方。我初版写技能的时候这里写成了“步骤教程”事无巨细地描述每一步的内部实现结果模型执行时过于死板遇到边界情况就罢工。后来我把写法切换成“约束视角”——每一段步骤的核心是定义“这一步要求什么输入、要产出什么结果、完成标志是什么”而不是“怎么做到”。相当于给Agent一个目标函数而不是教它一步步走迷宫。以“分析销售数据并生成报表”这个复合技能为例初版我把workflow写成了读取CSV用pandas做透视表生成柱状图导出PDF换成约束视角后的版本是确认数据源路径和期望的分析维度若用户未明确先列出可分析维度清单请用户确认生成包含汇总统计和至少一个趋势分析维度的结果注意剔除异常值产出结果为可阅读的报表文本并附上对应的可视化文件路径报表内容必须包含数据日期范围和数据来源便于复查两种写法最大的区别在容错性。约束视角允许Agent根据实际情况自己琢磨实现路径自由度高了对模型的推理能力要求也更高但最终产出的质量反而更稳定尤其是面对非标准化的输入时。3. 实操环节从零搭建一套可用的agent-skills体系3.1 第一步盘点原子技能画清工具地图搭体系不要直接从上层需求倒推那样容易漏底层的支撑能力。我推荐的做法是先把当前Agent所有能调用的工具、API、函数列一个清单然后给每个工具写一张“能力卡片”。能力卡片的内容很简单工具名称和一句话功能说明输入参数列表包括每个参数的类型、必填选项、取值范围输出结果的结构调用限制超时时间、并发限制、费用参考错误码和常见异常这一步的价值在于“盘点”。等清单完成后你会对Agent的硬件能力有一个清醒的认知哪些业务场景可以直接支撑哪些场景需要组合多个工具哪些场景存在能力缺口需要额外开发。我团队里有个伙伴把这步叫“画工具地图”我觉得很贴切——工具地图是所有上层技能设计的基础。3.2 第二步面向典型业务场景编写复合技能有了工具地图下一步是从真实业务场景出发把高频的、重复性的工作流整理成复合技能。这里有个关键动作复盘历史对话或历史任务日志找出哪些流程是反复在做的哪些步骤是固定不变的把这些固定套路沉淀成技能。我做过一个客服场景的Agent刚开始完全依赖模型自由发挥后来复盘了上百条真实对话发现大约六成的任务能归类到五个高频场景里查订单状态、处理退换货、解释价格差异、修改收货地址、催开发票。把这几个场景各自沉淀成复合技能以后Agent的表现立刻稳了一大截模型不再需要在每次会话里重新“发明流程”。写复合技能时我的建议是先把“happy path”走通再慢慢补边界处理逻辑。不要一上来就想把所有异常情况写全那样技能文件臃肿模型反而抓不住主干。3.3 第三步设计技能的“触发协议”与上下文管理技能文件写好后还有一道关键工序设置触发协议。我使用的模式是在每一轮模型的最终回复前增加一个工具调用决策节点。模型根据用户的最新输入和当前会话上下文决定是直接回复、澄清问题、还是调用某个技能。其中有一个优化细节很值得分享技能的加载不是全量的而是在触发后才把对应的SKILL.md内容插入到模型的上下文窗口里。这样做的目的是控制上下文长度。试想一下如果Agent挂了200个技能就算每个技能文件的平均token消耗是800全量加载就是16万token直接把上下文撑爆。改为按需加载后每次会话只加载活跃的那几个技能长上下文压力小了一个数量级。触发协议的具体实现可以用一个函数调用的形式def select_skill(user_input: str, available_skills: list[str]) - str | None: 基于用户输入与技能描述选出一个最匹配的技能名。 prompt f根据用户输入从以下技能列表中选择最匹配的一个技能。 如果所有技能都不适合输出 None。 用户输入{user_input} 技能列表 {available_skills} 只输出技能名不要输出任何解释。 response llm_call(prompt, max_tokens16) return response.strip() if response.strip() ! None else None当然这只是最简实现。真实场景中触发协议还要考虑会话历史、已加载技能的状态等。但核心思路不变让模型做一个轻量级的“路由决策”而不是每次都全量推理。3.4 第四步建立技能评测机制持续迭代技能写完不是终点评测迭代才是常态。我给技能库配了一套最简单的评测方案准备一组标准测试用例每个用例包含“输入请求、期望调用的技能、期望的输出类型、关键的验收点”然后每次技能定义有改动就全量跑一遍回归。这个流程初期投入的成本不小但回报非常可观。尤其是当你改了某个原子技能的工具定义后影响范围往往超出预期。没有回归测试兜底线上Agent出现诡异行为你甚至不知道是哪次改动导致的。4. 技能编排与多技能协作实战4.1 当一个任务需要多个技能按顺序配合真实任务极少是单个技能能搞定的绝大多数需要多个技能有序配合。技能编排就是设计这些技能的协作路径。以一个“自动整理竞品动态并生成周报”的场景为例。这个任务背后的技能编排路径是web_search检索竞品相关的最新新闻和公告web_extract打开高价值内容的URL提取正文summarize对每篇内容生成不超过200字的摘要weekly_report_merge把多条摘要按竞品维度分组输出结构化周报这个流程看起来顺理成章但如果让模型自由发挥常常有意外事故。比如模型搜完直接开始写总结跳过了正文提取环节导致摘要内容基于搜索结果的只言片语或者模型在搜索阶段就试图执行周报模板的格式浪费了大量上下文。解决这个问题的利器是“工作流约束”在复合技能里用明确的步骤列表把编排路径固定下来。模型不是不能发挥而是只能在“流程固定、参数灵活”的框架内发挥。4.2 策略技能让Agent学会“分情况讨论”比固定编排更进一步的是策略技能。它描述的不是一条固定的路径而是一个“决策树”或者在多个路径间选择的规则。举个例子我做过一个“内容审核辅助”的技能。它的策略逻辑是识别文本类型如果是纯事实性陈述直接走“事实核查”分支如果包含观点性内容走“标注观点来源”分支如果两者混合先拆解再分别处理。这种“分情况讨论”的策略极大提升了输出与需求的匹配度。写策略技能最大的心得是别试图覆盖所有分支只覆盖统计上最高频的那几个分支。长尾情况留给模型临场判断。这就像带新人你把“正常情况怎么处理”讲清楚剩下的让他自己体会成长反而更快你事无巨细把每种情况都规定死新人反而畏首畏尾。4.3 技能间的数据流约定多技能协作时数据格式的一致性往往是被忽视的坑。A技能输出的数据结构B技能期望的输入结构如果对不上模型就得在中间做一层“格式转换”。转换一次两次没问题转换多了信息损耗和出错率都会上来。我的做法是在技能库的统一规范里约定公共的数据交换格式。比如所有检索类技能的统一输出都是{ items: [ { title: 标题, url: 来源地址, snippet: 摘要片段, source: 来源名称, timestamp: ISO时间字符串 } ] }所有技能在设计阶段就要“对齐接口”。这跟前后端分离开发时先定接口文档是一个道理。省去了模型在中间兜圈子的开销正确率提升立竿见影。注意技能间的“粘合逻辑”尽量放到代码里而不是依赖模型生成。能用几行Python函数处理的数据清洗就不要让模型来做。模型只做理解和决策不做事无巨细的体力活。这是Agent工程与纯提示词工程最大的分水岭。5. 常见问题与排查技巧实录5.1 症状一Agent总是选错技能这是最让人头疼的问题每次有90%的概率是description写得不够精准。排查方法很简单把技能列表打印出来把当前用户输入放在旁边自己站到模型视角上选一次。如果你自己都觉得“两个技能好像都沾边”那模型也会糊涂。解决方向在description里强调触发场景的“强信号特征”。比如“当用户输入中出现‘订单号’时优先考虑调用订单查询类技能”在“不适用场景”里明确排除容易混淆的情形如果两个技能的功能确实有重叠考虑合并成一个技能内部按参数分支模型误选择技能的另外一个原因是技能库数量太大超过了模型阅读全部的注意力范围。这种情况可以往技能库加一个索引层——一个精简的技能速查表模型先读索引再决定到底加载哪个技能。5.2 症状二技能流程执行到一半就断了我遇到过执行半路断掉的原因大多出在“工具调用失败后的重试策略”上。Agent调某个API超时了直接放弃了整个任务也不告诉用户发生了什么。我一开始以为是模型能力问题后来排查发现是技能文件里漏写了“调用失败时怎么办”的兜底说明。现在我的技能模板里workflow的最后永远有一节“on_error”说明明确每种常见失败类型对应的处理方案。比如“工具超时重试最多两次若仍失败返回错误并建议用户稍后再试”。这种兜底说明对模型来说是一颗定心丸它能区分“应该继续尝试”和“应该放弃并上报”而不是在两者之间摇摆不定。5.3 症状三Agent打开技能文件后上下文明显变长响应变慢技能文件过多或过长带来的性能损耗是真实存在的。我的处理方案有两个方向精简技能文件内容把大段示例移到单独的references目录主文档只保留核心信息。模型需要时可以按需查看子文件这个策略类似代码模块的懒加载。分级缓存对已加载过的技能内容做会话级缓存同一会话内多次调用同一技能不需要重复插入。5.4 症状四输出格式不稳定有时候给JSON有时候给散文这类问题八成是output_format没写死。我的经验是要多写一层“模板示例”。给出一段完整的示例输出明确到什么字段、什么格式、甚至大括号和引号怎么放。模型看到具体示例时模仿能力是远好于纯文字描述的。另外每一步workflow里增加“本步骤产出物写入格式校验”也不算多余尤其在关键节点上做一次格式校验能及时拦截后续步骤的错误输入。5.5 踩坑实录一次因为“优先级冲突”引发的线上事故最后分享一个印象深刻的翻车经历。有一版技能库里我同时定义了“敏感内容检测”和“自动回复生成”两个技能前者逻辑是“检测到不当内容立即拦截并上报”后者逻辑是“对所有用户请求自动生成回复内容”。触发关系上“自动回复生成”的适用范围写得太宽结果Agent在检测到不当内容后仍然先走了一步自动回复生成把拦截结果给吞掉了导致不合适的回复直接发出去了。这个事故的根源在于两个并列技能都没有声明“相对优先级”。之后我在技能定义里增加了一个priority字段并约定当两个技能的能力边界存在交叉场景时优先级高的技能拥有决策权。这类“技能之间的冲突处理规则”是维护大技能库不能绕开的问题越早设计越好。一点个人体会做了这么久agent-skills最大的心得是Agent的能力天花板不在模型选得多大而在你给它装配的技能体系有多扎实。技能不是一次性写完就完事的资产它是需要随着业务演变持续迭代的系统。你观察Agent的每次失误本质上都是技能体系里某个定义不够精准的反馈信号。把反馈回路跑起来Agent的表现就会持续往上走。这套体系目前支持了我的多个业务场景从客服会话到内容生产到数据分析覆盖了数百个技能定义。如果你正在搭建自己的Agent应用建议从最小的场景开始先沉淀三五个核心技能跑通闭环再逐步扩展。与其一开始就追求庞大的技能库不如先把核心路径上的技能打磨到极致。