1. 为什么Agent需要一套“技能库”最近在带项目的时候不少做Agent开发的朋友都跟我聊到一个问题单模型能力越来越强但落到具体业务上总感觉哪里都差一口气。模型能对话、能总结可真要让它在某个业务场景里稳定干活——比如自动整理客户信息、按规范生成周报、跨表格查数再发给正确的人——它就经常跑偏。这就是我为什么特别关注agent-skills这套思路。所谓skills往通俗里说就是给Agent准备的一套“标准动作库”把那些高频、重复、可组合的能力提前封装成结构化的技能模块。Agent在执行任务时根据用户意图去技能库里匹配一个或多个技能按技能定义的流程、工具、约束去干活而不是每次都靠大模型自由发挥。这个思路解决的问题很直接确定性、复用性、可控性。不带技能库的Agent每次面对同类任务都像新员工凭感觉上手带技能库的Agent像老员工翻开标准作业指导书照着步骤执行哪怕模型换了一个版本技能层依然稳定。这套东西适合谁适合三类人一是正在做Agent产品、被Prompt稳定性困扰的开发者二是想给团队沉淀一套Agent能力资产、避免反复“教”模型的基础架构同学三是刚接触Agent、想知道技能模块化该怎么落地的初学者。下面内容主要围绕“技能库的设计结构、搭建步骤、调用机制、避坑思路”来展开尽量讲清楚“为什么这么做”以及“实际做时会遇到什么”。2. 先拆清楚Agent技能的本质是什么2.1 技能不是Prompt也不只是工具很多初学者容易把Skills、Tools、Prompt三件事混在一起。我倾向用一句话划分边界Prompt是教模型“怎么说话、按什么口径输出”Tools是替模型“触达外部世界”的能力接口比如查天气、写文件、调APISkills则是把“目标 → 流程 → 工具组合 → 输出规范 → 边界约束”打包成完整可复用的执行单元。举个例子。你做一个“批量生成长图配文”的任务。如果走Prompt路线你可能写一段很长的“请根据产品卖点生成风格活泼的文案”效果时好时坏。如果走Tools路线你会准备一个生成文案的API但模型不一定知道何时调用、如何判断输入是否合法。而Skills路线会定义成这样name: product_copywriter description: 根据产品信息、目标用户生成多平台适配的推广文案 trigger_intents: - 写推广文案 - 生成产品介绍 - 朋友圈种草文案 steps: - step: parse_product_info tool: llm_extract required_fields: [product_name, selling_points, target_user] - step: draft_copy tool: llm_generate params: platforms: [wechat, xiaohongshu, douyin] tone: [lively, professional] - step: validate_output tool: rule_check rules: - 字数不超过200 - 必须包含slogan - 禁止出现绝对化用语这里面既有原料解析、生成、校验的完整流程也包含了工具选择和参数约束。模型接到任务后不再自己临场发挥而是按步骤走流程结果天然更稳。2.2 技能库解决的三层核心问题第一层是上下文污染。你让Agent先查库存、再写邮件、再生成报表如果全堆在一个Prompt里前面任务的输出很容易带偏后面任务的口径。技能库把每个动作封装成独立模块调用结束后清理临时上下文降低互相干扰。第二层是复现与迁移成本。团队里A同学调好的写法存在自己电脑里B同学根本不了解。而技能库以标准文件、标准目录沉淀下来换人、换项目、换模型都能快速迁移本质是能力资产化。第三层是评估和兜底。裸Prompt的评估只能看单个输出结果而技能库可以设计成“每一阶段都有校验点”比如解析阶段必须提取哪些字段、生成阶段必须满足哪些约束。这样出问题能定位到具体步骤不是笼统地“模型效果不好”。2.3 不同形态的Agent对技能库的诉求不一样我也踩过坑上来就搞一套特别复杂的技能编排框架结果发现团队里并不需要。实际按产品形态分一下诉求完全不同聊天助手型Agent核心诉求是意图识别准、多轮上下文稳技能通常偏轻重点在“什么时候该触发哪个技能”。工作流自动化型Agent核心诉求是步骤固定、参数强校验、异常可恢复技能要偏重流程编排和规则兜底。开放探索型Agent比如让模型自主拆解任务核心诉求是技能库要足够丰富、组合灵活模型能够自主挑选合适技能并串联起来。所以第一件事不是急着写技能配置文件而是先想清楚你的Agent在哪一种形态下工作这决定了技能库的粒度、深度和校验强度。3. 从零搭建一套可用技能库的完整步骤3.1 先约定目录与命名别让技能库变成垃圾堆技能库一多最常见的问题就是找不到、不知道用哪个这时候命名的规范性比内容还重要。我比较推荐的目录结构是这样skills/ product_copywriter/ skill.yaml skill.md assets/ template_cn.md template_en.md data_analyst/ skill.yaml skill.md meeting_helper/ skill.yaml skill.md customer_service/ skill.yaml skill.md一个技能一个文件夹文件夹名就是技能名全部用小写字母下划线。skill.yaml存元信息和配置skill.md写具体的执行说明和注意事项assets放模板、样例等辅助文件。命名上我强烈建议带业务语义不要叫skill_01、skill_02这种也别用大写和空格因为后期可能会在配置文件、代码、甚至模型能看到的技能描述里引用这些命名会直接影响解析和匹配效率。配置头推荐字段如下name: product_copywriter version: 1.2.0 author: ops-team description: 根据产品资料生成多平台适配的推广文案 license: internal tags: [marketing, copywriting, content] depends_on: - base_text_tools这里version和depends_on很多人会忽略等技能改出问题或者依赖工具升级时就知道它们多重要了。3.2 把“技能描述”写到模型一眼看懂技能配置成功与否最关键的其实是description字段怎么写。模型在读技能库时本质上是靠description去理解“这个技能管什么、什么时候用”。写得含糊模型就会在错误场景触发或者根本不触发。我个人总结出比较管用的模板{技能名称}用于{精确场景}。当用户需求出现以下特征时使用{关键词1}、{关键词2}、{关键词3}。 主要动作{简洁列出1-3个核心动作}。 不适用于{明确排除的场景避免误触发}举个例子description: 产品文案生成技能。当用户提供产品名、卖点或活动信息并要求输出社交平台推广文案时使用。 主要动作解析产品资料、按平台模板生成文案、执行合规校验。 不适用于纯聊天回复、不属于推广场景的日常问答。这里“不适用”三个字很关键它能显著降低误触发率。因为LLM在识别意图时被排除项帮它缩小了候选集。另外技能数量超过十来个以后我建议维护一份INDEX.md里面按业务域分组列一下每个技能一句话功能和触发建议。Agent在技能匹配前可以先看索引再决定去加载哪些技能包效率会高很多。3.3 设计技能主文件从抽象到具体逐层落地skill.md是技能的灵魂它告诉Agent“拿到这个任务后按什么思考路径走”。我们不能指望模型看一眼description就能完美执行必须给它一套可执行的SOP。一个比较成熟的skill.md结构我通常是这么编排的一、技能目标一句话说明产出物是什么尽量定量比如“生成三版不同风格的文案每版150字以内”。二、执行前置条件明确需要哪些输入字段缺失时如何处理是拒绝执行还是向用户澄清。三、分步操作流程每个步骤要有编号、目标、涉及的工具、输入输出要求、异常处理方式。四、输出规范规定最终输出格式必要的时候直接给模板。五、合规与红线把规则明确写出来比如“禁止承诺效果”“禁止使用绝对化用语”。六、示例给一个完整的输入输出示例让模型少走弯路。拿“会议纪要整理”这个技能来说核心步骤可能是四步第一步解析会议录音转文字第二步按发言人分离内容并提取决策项第三步按“背景-讨论-决策-待办”格式生成纪要第四步检查待办事项是否包含负责人和截止时间。关键逻辑在于步骤越细出错的概率越低但对应的token消耗和时间成本也会上升。所以步骤设计要在确定性和成本之间找平衡。像“会议纪要”这种任务步骤做到四级就够但如果做一些金融复核、医疗结构化这类高合规要求的技能步骤可以拆到七到八级。3.4 参数和校验规则要放在明面上真正老实干活的时候模型会幻想一些不存在的字段或者把参数的类型搞错。比如技能要求输入price为数字模型可能给出“价格实惠”这种文本。因此在技能设计里补充输入校验规则很有必要。input_schema: product_name: type: string required: true description: 产品正式名 price: type: number required: false description: 产品价格数字类型 selling_points: type: array required: true item_type: string description: 卖点列表 validation: - check: required field: product_name error_message: 产品名称为必填项 - check: type field: price error_message: 价格必须为数字同时skill.md里也可以加一段“参数异常处理”的说明告诉模型遇到缺失参数时不要自行编造应该回到澄清模式向用户提问。3.5 测试技能不光测正常流程更要测边界和回退技能文件写完了测试这关不能省。我的经验是每个技能至少要过这三类用例第一类是正常用例输入一个典型任务看输出质量、格式、步骤遵循情况是否达到预期。第二类是边缘用例比如输入中带了emoji、全大写文本、语序混乱的口语、含错别字的字段看看模型是否还能妥善处理。大部分技能的翻车点都在这里。第三类是回退用例故意设计成不该触发该技能的场景看模型是否能拒绝执行或切换其他技能。这类测试对防误触发特别重要。测试通过后建议把测试案例随技能一起归档到assets/test_cases.md里后面技能升级时直接回归验证。4. 技能调用的核心机制与编排策略4.1 模型是怎么从技能库里选中技能的这部分理解透了你写技能的水平会直接上一个台阶。Agent在运行时通常先接收用户的输入再结合系统提示词里对技能库的描述来决定“要不要调用技能、调用哪些技能”。目前主流的做法是把技能库的元信息和description注入到Agent的“可见列表”里模型根据当前任务语义对候选技能打分排序选出匹配度最高的一个或多个然后加载对应的skill.md和工具配置开始执行。这个机制决定了两个关键点Description的语义清晰度直接决定选型准确率写得越具体、边界越明确选型越准。技能库不宜过大候选列表太长会稀释注意力建议控制在20到30个以内。超过这个数就要做分组或分级加载。我见过一个团队的做法是两级索引第一级按业务域分营销域、数据域、客服域模型先判断属于哪个域再去加载该域下的技能列表。这样既能扩大总技能数量又不至于把注意力撑爆。4.2 多技能组合时的关键过渡衔接复杂任务往往一个技能覆盖不了需要多个技能组合。比如“做一份竞品分析报告给老板”可能涉及信息搜集技能 → 数据整理技能 → 报告生成技能。多技能串联最怕的不是单个技能不行而是上一个技能的输出规格跟下一个技能的输入规格对不上。解决方案是定义标准的数据结构作为技能之间的“通用语言”。比如信息搜集技能输出统一保存为一个research_result.json包含sources、key_findings、data_table三个部分数据整理技能读取这个JSON时就有明确的字段可以依赖不会乱猜。{ research_result: { sources: [url-1, url-2], key_findings: [ {factor: 价格, observation: 竞品A较竞品B低15%} ], data_table: [ {competitor: A, price: 99, market_share: 0.31} ] } }这时候每个技能的责任边界要写清楚一个技能只负责自己那一阶段的事不要越界去修改下游的数据。像“信息搜集技能”就不要顺便开一个“报告撰写”的脑子专心把信息整理结构化工整就行。4.3 上下文打包与环境隔离Agent在执行多个连续技能时如果不做上下文管理很快就会被前面的历史记录淹没。我常用的做法是每个技能执行结束后把核心结论压缩成一段摘要旧的全量过程数据归档到文件或缓存不再参与下一技能的上下文输入。给每个技能定义“工作时内存”变量执行完即释放。尤其注意不要在跨技能场景里保留临时Prompt、中间推理。在长任务场景中每隔几步做一次“状态快照”把已完成步骤和产物记录在案这样如果后面执行异常可以从最近快照恢复而不是重头再来。这套思路对长任务的稳定性提升非常显著。前期可以不搞复杂的状态机先做到“做完一步、清一步、存一步”就已经能解决大部分上下文漂移的问题。4.4 技能冲突怎么避免技能库到了几十个规模会出现一种尴尬情况两个技能描述上有部分重叠同一个用户请求可能同时触发两个技能。比如“产品文案”和“活动方案”在用户提出“帮我写个新品发布的宣传计划”时就可能同时被选中。处理方式我给三个建议第一靠description主动做区分。把重叠场景的“职责边界”直接写清楚比如产品文案技能注明“仅负责文案创作不包含活动策划排期”活动方案技能注明“如果只需要文案部分请转交产品文案技能”。第二在技能里设计冲突仲裁的字段比如设置优先级两技能同时触发时选优先级高的。第三在编排层加一个路由校验模型选出技能后由一个轻量级规则检查“该技能是否适合该请求”如果命中两个以上则做二次判断必要时向用户澄清。5. 我踩过的一些坑给你列成排查手册5.1 技能写了但就是不触发这个问题我自己遇到好几次。原因通常出在description和真实用户提问的语义差距太大。你写了“生成产品文案”用户却说“帮我整一段朋友圈卖货的词儿”模型可能匹配不上。解决方案是在description里把同义表达和口语化说法都列出来比如“文案”“卖词”“种草文案”“朋友圈推广”全写上并且用trigger_intents字段强化触发意图。另外注意技能匹配是基于“意图语义”的如果模型当前版本对中文口语理解有波动可以适当在description里补充一句“该技能包括但不限于这些表达”。5.2 输出格式老是不对字段总缺失很多技能的翻车现场是模型意会了任务但输出缺了必填字段或者格式和模板不一致。这时候我一般先查三处一查skill.md里的输出模板是否够具体。模板里要直接给出Markdown结构或JSON示例别只说“按规范输出”。二查校验规则有没有做硬校验。如果只是提示模型可能不当回事要配合规则引擎做输出后校验不合格就自动重试一到两次。三查是不是模型偷懒省略了字段。这时候可以在样例输出里故意展示完整、详细的版本模型会倾向于模仿样例而不是自己去精简。5.3 多技能组合时下游技能接受的数据是脏的组合项目中频发的数据污染本质是上游技能的输出规格太宽松。比方说信息搜集技能输出了带Markdown符号的摘要下游分析技能读取时就把**当成内容的一部分算进去了。解决方法很简单在技能交接点设置标准数据契约明确字段类型、取值范围、格式并且让上游技能在输出前做一次自检转换。宁可多花一点token也要保证交接数据是干净、结构化、字段齐全的。5.4 模型“不熟悉”新技能跟没装一样偶尔会遇到模型好像完全没理解技能的存在这种情况通常是技能库加载方式出问题比如系统提示词里技能列表注入太靠后或者被其他长指令挤掉了注意力。排查思路确认技能元信息是否出现在Agent的上下文前部二、确认description长度合理我一般控制在80到150个中文字符之间太长会稀释匹配度太短语义不足三、确认当前对话历史是否已经很长必要时做历史压缩后再进行技能匹配。5.5 技能升级后旧任务跑不通技能迭代很容易出现“新版技能把老任务的细节要求覆盖了”的情况。我踩过最典型的一次是更新了数据格式校验规则但下游还有老流程在使用旧的字段名结果批量任务全部报错。所以技能升级必须走版本化流程skill.yaml里的version字段认真维护变更记录写清向下兼容情况涉及字段、流程大规模调整的影响面评估一定要做。技能库沉淀越久版本管理越不能省。6. 几点个人心得纯经验之谈6.1 技能库是“约定大于配置”的工程做技能库的关键不在工具多高级而在团队内部对“技能长什么样”达成共识。结构、命名、校验方式、加载策略、目录布局这些约定一旦定好后续维护成本会直线下降。我见过一家公司用简单的Markdown文件也把几十个技能管理得井井有条靠的就是统一规范。6.2 别一上来就追求“大而全”技能库初期一定要克制。优先级最高的十个高频任务把它们打磨到“稳定、可靠、可解释”远胜于铺开五十个泛泛技能。技能库的价值密度取决于每个技能被真实调用的频率和成功率而不是技能数量的绝对值。6.3 把“人的验收经验”固化进技能里技能库最有价值的部分往往不是那套骨架而是执行细节里藏着的“老师傅经验”。比如写某个行业报告时哪些数据源可信、哪些口径容易出错、哪些表达合规上过黑名单……这些一旦沉淀进技能文件新来的同事也能快速上手团队就不再依赖某个人了。6.4 后续还可以怎么玩技能库积累到一定规模之后可以做训练侧的场景数据增强把技能执行的成功案例整理成微调样本也可以在技能之上加一层“技能编排蓝图”让Agent能根据任务自主规划组合路径。这条路很长但每一步都有实际收益。最后分享一个小习惯我每次新写一个技能都会强制自己在skill.md里加一节“已知边界”。把当前这个技能做不到的事情、不适合的场景、容易踩的坑先写进去。等它真正上线被调用的时候这一节会帮模型避开很多错误路径。技能这个东西写得越诚实跑起来越靠谱。