先聊一个观察做AI Agent的应用做到后面大家会发现真正拉开差距的不是模型有多强不是LangChain还是什么框架而是你给Agent准备的“技能”到底靠不靠谱。“agent-skills”这个项目标题看起来简单但它是目前Agent落地最核心的单元。如果说模型是Agent的大脑记忆是它的长期经验那么技能就是它的双手——没有技能的Agent再聪明也只能聊天没法干活。这篇文章我想结合我自己实际调Agent的经验把“技能”这件事从头拆到尾它到底是什么、怎么设计、怎么写才能让模型真正用起来、以及我在真实项目里踩过的那些坑。适合正在做Agent应用、被各种框架绕得头疼、想自己动手给Agent配一套靠谱技能库的开发者参考。1. 别把技能当成工具先搞清它在Agent里的定位1.1 工具、技能、任务三者的边界到底在哪很多刚上手的朋友会把技能和工具混为一谈这是第一个容易踩的坑。工具通常是单个确定性的函数比如“查询天气”“发送邮件”“计算MD5”输入输出都极为固定你调用它就像调一个API没有太多决策空间。而技能是一整套“在某种场景下可以被复用的能力封装”它不只是指功能本身还包含怎么评估该不该用、用什么参数、按什么顺序执行、遇到边界情况怎么处理这一整套行为方式。我举个例子。单纯写一个send_email函数这是工具。但你要让Agent“替我起草一封会议纪要邮件并发出”这就涉及判断纪要格式、提取关键决定、选择语气、决定是否抄送领导等多个环节——这时候你需要的不是工具而是一个“发会议纪要邮件”的技能。技能是包裹工具的策略层它告诉模型什么场景下动用什么工具、怎么用、用完之后怎么判断结果。再往上一层叫任务。任务是用户给Agent的一个目标比如“帮我安排下周的客户拜访”它可能需要组合多个技能查日历、查路线、写邮件、订餐厅。技能是任务的基本积木块而不是任务的替代品。你在设计Agent时永远要先拆任务、再映射技能、最后补工具。1.2 为什么Agent应用越做越依赖技能封装早期做Agent大家习惯把Prompt写得很长——什么角色设定、规则、工具说明全挤在系统Prompt里。结果就是上下文被占得满满当当模型决策准确率还上不去。技能封装本质上是把“能力”从Prompt里挪到外部模块中让模型按需加载核心优势有三个。第一是上下文瘦身。技能描述通常只需要一两行说明真正的指令和参数放在技能内部。模型在每一轮只需要看到“有哪些技能可用”的索引而不是全部技能的完整定义这种“延迟加载”思路节省了大量token。第二是行为可控。当你把一套完整的行为模式封装成技能后你可以单独测试、单独调参、单独优化。如果“写周报”这个能力表现差不需要动整个系统Prompt只需要改这个技能的描述和内部指令评估成本大幅下降。第三是复用性。技能一旦沉淀就能跨Agent复用。同一个“代码审查”技能可以用在编码助手、CI机器人、代码教学Agent里只是外层策略略作调整。这就像你把一个函数写成公共库收益是长期性的。1.3 技能是Agent的“肌肉记忆”再用个生活化的类比帮你建立直觉模型像是一个很有天赋的新员工懂原理、反应快但不知道你们公司的流程技能则是标准作业程序手册把“怎么请假、怎么写周报、怎么提交代码”这类事情固化成固定流程。新员工不需要每次遇到事情都从头想一遍翻手册照着做就行而且犯错的概率大大降低。这也解释了为什么Agent技能的兴起几乎成了行业共识——各大Agent平台都开始用“Skills”作为核心抽象。它的本质思路一致把高频、稳定、可验证的行为模式沉淀为可加载的模块让Agent的行为从“自由发挥”走向“有章可循”。这不是限制Agent的能力反而是释放Agent的能力让它把手脚从低层操作中解放出来专注在真正需要推理的地方。2. 技能设计的底层逻辑好技能与劣质技能的差距在哪2.1 技能的完整结构不止是一段Prompt很多人在实践“agent-skills”时第一个误区就是以为技能就是写一段Prompt塞给模型。你要是这样做很快就会发现技能时灵时不灵。存在一个完整的技能单元结构我一般把它拆成四个部分。元信息技能的名称、用途的一句话总结、适用的场景条件这部分是给“调度器”看的——不管是Agent框架还是模型本身都要靠它来决定什么情况触发这个技能。核心指令告诉模型这个技能具体要做什么、按什么步骤做、遵循什么原则。这是技能的“思维链”但要注意的是控制长度太长了模型会迷路太短了模型会自由发挥。约束条件明确边界比如什么情况下不能使用、哪些参数必填、哪些输出格式必须遵守。示例一到两个完整的输入输出样例这是模型理解技能最有效的方式比任何抽象描述都管用。这四个模块缺一不可。元信息负责“何时用”核心指令负责“怎么做”约束条件负责“别做错”示例负责“照样子做”。你把一个技能文件写全它的稳定性会远超一段临时写出的Prompt。2.2 关键元信息让模型认得、想得起、用得上技能描述description永远是最关键的一行字。这一行字会被嵌入到Agent的上下文里模型要靠它来判断到底要不要调用这个技能。描述写得不准确模型要么无视技能要么乱触发技能。如何写好这一行我的经验是三个要素任务类型、典型场景、关键对象。无效写法处理文档有效写法对上传的PDF或Word文档提取结构化要点生成摘要或对比表格适用于会议纪要、合同审阅、论文泛读等场景你能明显感觉到后者信息密度高、边界明确。我在实际项目中测算过描述重写之后技能调用准确率提高了超过两成——别小看这一行字它是最便宜的优化手段。另外技能的名称也很重要。我建议用“动词对象”的结构比如summarize_document、search_codebase、generate_ddl。这样的命名让元信息检索非常直观Agent在判断“当前用户请求对应哪个技能”时几乎不需要费劲推理。2.3 技能的粒度多大算合适多小算碎片化粒度问题是技能设计里最能体现经验的地方。技能粒度太大一个技能里有十几条路径模型执行起来负担重、出错概率高粒度太小技能库膨胀到几百个模型光检索匹配就晕了。我常用的判断标准有三条这个技能是否承担了超过两个“决策点”如果执行过程中要求模型频繁判断走哪条分支说明粒度太大了拆开。这个技能能否独立测试如果你没法为它单独构造测试用例、单独判断结果好坏说明边界不清晰重新划分。这个技能在不同场景下的表现是否方差大表现忽好忽坏往往是技能里混淆了多个不同任务拆开反而每个都稳定。我手头有个“数据处理”技能最开始它又能清洗CSV、又能做数据可视化、又能做统计分析结果处处拉胯。拆分成了三个独立的技能之后每个技能的准确率都上去了。这就是典型的“大而全不如小而精”。2.4 技能的执行路径设计串行、并行与条件跳转一个复杂的技能内部经常包含多个步骤。这些步骤之间的组织方式直接决定了技能执行的效率和稳定性。最基础的模式有三种。串行执行步骤之间有强依赖前一步输出是后一步输入。比如“读日志-定位报错-查询相关文档-给出修复建议”这是最常见也最好控的路径。并行执行互相独立的子任务可以同时跑。比如“审查前端代码”和“审查后端代码”可以拆成两个子任务并行进行再合并结果节省时间。条件跳转根据中间结果决定走哪条路。比如“检查代码风格不合格就返工合格就进入测试环节”这种路径对模型的判断力要求最高。我建议在技能内部设计步骤时默认用串行。因为并行和条件跳转会显著增加输出格式解析的复杂度出错后排查也困难。当你的技能已经稳定运行一段时间、你对各个步骤的成功率都有数据支撑了再逐步引入并行和条件跳转。稳是第一位快是第二位。3. 动手建一个技能库从零到一的全流程实操3.1 明确使用场景技能库和项目要一一对应技能库不是越大越好而是越贴合业务越好。我建立技能库的第一步永远是回答三个问题我的Agent要在什么场景下服务用户最常提的需求是哪几类每一类需求需要哪些外部数据或操作以一个我最近做过的“项目文档助手”为例。它的用户是项目组成员Agent需要帮他们快速理解各类文档。我梳理出来的高频场景有四个读需求文档并出摘要、读接口文档并生成调用示例、对比两个版本文档的差异、为评审会议整理问答列表。这四个场景就是技能库的第一批种子技能。我强烈建议你从“过去一个月真实出现的用户请求”出发来定场景而不是自己闭门造车猜需求。先翻聊天记录看用户到底在问什么拿高频请求作为技能开发的需求池按出现频率排序先做最痛的那几个。3.2 技能文件的标准格式与目录组织在定义技能文件格式时不一定要跟风某个框架的标准但自己项目内部一定要统一。我目前最习惯的组织方式是一个技能一个目录目录下有主描述文件和若干资源文件。目录命名用英文小写加下划线和技能名称一一对应。summarize_document/SKILL.md技能主文件包含元信息、指令、约束、示例summarize_document/references/可选放参考文档、模板文件供模型按需加载summarize_document/scripts/可选放Python脚本用于外部工具调用主文件的头部再固定放一段YAML格式的元信息方便程序扫描和索引。你可以在项目中解析这些元信息构建技能清单或做向量化处理。目录组织看似不起眼但项目里技能数量超过几十个之后统一的结构能让你的维护成本成倍降低。你不需要翻遍整个技能库才能找到某个技能新人也更容易上手。3.3 技能内容的写法如何同时说清流程和边界编写技能主体内容的时候我遵循一个基本要求让模型照着做就能得到80分的结果不需要它发挥灵感。核心写法是列出步骤、明确每一步的输出、给出避坑提示。以“代码审查”技能为例先读取目标代码文件识别其语言与主要职责。检查逻辑错误重点关注边界条件、空值处理、并发安全。检查可读性与项目风格一致性。输出审查结果每个问题按“严重程度-问题描述-修改建议-示例代码”的格式组织。注意这里面每一句都在约束模型的输出。你反复强调“按格式输出”模型出错率会显著下降。另外别忘了在约束条件里写清楚“不做什么”——比如只审查代码质量不做架构规划不重写整个文件。边界划得越清楚模型越不容易跑偏。3.4 快速原型与迭代验证别指望一次写好技能开发绝不是一蹴而就的。我的流程是先快速出一个粗糙版本让它跑起来看效果再根据失败案例循环打磨。通常第一版只求流程跑通命令逻辑只要大体对就行——因为只有真实运行后你才会看到模型在哪些环节理解偏了。具体操作方法是准备一组覆盖典型场景的测试用例每次修改技能后用同一组用例回归测试记录通过率。这一步很关键。没有测试集你的优化就是玄学。我每轮迭代都会跑大约20个测试用例然后人工检查输出把错误归为分类描述没触发、步骤执行遗漏、输出格式不对、内容理解错误。每一类问题对应的修改动作不同分类之后你才知道该改哪里。比如描述没触发大概率是元信息里的描述写得不够贴合用户表达方式改用用户的话术重写描述步骤执行遗漏多半是指令不够明确需要把步骤拆得更细。这样的迭代循环走三到四轮一个技能基本能稳定下来。4. 技能落地的核心环节Agent怎么“想”到要用什么技能4.1 技能注册表把技能列表喂给Agent技能文件写好只是万里长征走了一半。更关键的问题来了Agent怎么知道有哪些技能可用怎么在恰当的时机调用正确的技能这里面需要一套调度机制而不是把全部技能一股脑塞给模型。我一般先建一张“技能注册表”把每个技能的元信息名称、描述、使用条件汇总成一段结构化文本。这段文本会被注入到Agent的系统提示中。你需要控制这张表的体积保证它能在有限的上下文里被模型完整看到。一般来说一张注册表描述十个到二十个技能是合适的再多就要考虑分级调度。4.2 基于语义检索的技能召回与动态加载当技能数量超过二十个把全部技能描述一次性塞进上下文就不太现实了既浪费token又干扰模型注意力。这时候就需要动态召回根据用户当前请求从技能库里检索出最相关的几个技能动态注入上下文。我常用的实现方式是把技能描述做向量化存进向量数据库。用户每发一条请求先把请求向量化做相似度检索取Top-K个技能描述连同系统级指令一起拼进Prompt。这里的K一般取三到五个太小会漏召回太大会引入干扰。另外一个细节是把“技能名称”和“技能描述”绑定返回因为模型最后要针对技能名称来决定是否调用。如果检索结果里只有描述没有名称模型就缺少一个稳定的指代标识容易把技能弄混。4.3 技能调用的触发条件与自动决策在提示词工程层面你会发现让模型“主动调用技能”其实没那么难难的是怎么让它“不误调用技能”。行为约束和召回机制配合起来非常讲究。我见过最多的误调用类型是用户只是想聊聊天Agent却调了一个“开始写代码”的技能用户问的是概念性问题Agent调了搜索技能去网上找答案。原因在于技能的触发条件写得过于宽泛模型看到一点沾边的关键词就触发。解决办法是在技能描述里增加“触发条件”和“不触发条件”。比如搜索技能里写明仅当用户明确要求获取最新信息或外部信息时调用当用户问的是通用知识或概念解释时不调用。这类约束要写在描述字段里因为描述才是模型每次都在看的内容。4.4 技能输出的校验与反馈闭环技能运行完之后还有一个容易忽略的环节对技能输出做校验。尤其对于自动化程度较高的Agent如果技能输出是一个JSON结构那么格式校验就是必须的。解析失败时你需要自动触发纠错逻辑——把错误信息反馈给模型让它按要求重试。这个迭代机制是Agent稳定性的最后一道防线。我在代码生成类技能上的做法更严格技能生成的代码一定会过一遍静态检查工具有语法错误就直接让模型修复修复次数限制在三次以内。超过三次则显式标记为“执行失败”并转人工。这种做法把技能的“表面完成率”和“真正可用率”分开统计给我的技能迭代提供了最重要的数据依据。5. 我踩过的技能开发深坑五个差点劝退的坑与排查实录5.1 描述写得太诗意模型“读不懂”技能有一次我写一个“代码重构”技能描述用了大量形容词——“优雅地优化代码结构”“提升代码的可维护性与美感”。听起来挺专业但实测下来模型触发率极低。排查过程让我意识到模型像个阅读理解能力一般的同事它更擅长从具体名词和行为动词里提取信号。“优雅”“美感”这种词它不知道该怎么对应到操作。我重写成重构指定模块的代码结构提取重复逻辑为公共函数保持外部接口输入输出不变之后触发率和执行准确率都明显回升。教训技能描述要像给搜索引擎写摘要动词要具体、名词要明确不要追求语言美感。5.2 技能内容与真实流程脱节纸上谈兵要不得这是一个比较痛的教训。我曾给一个“数据导出”技能写了非常详细的流程自认为逻辑严密结果真实用户跑起来完全不对——因为我在流程里假设数据源是MySQL但真实项目里两个数据的来源不同其中一个数据在API网关后面。排查之后明白一个道理技能开发前的最重要一步不是写内容而是先做流程调研。必须要把真实链路跑一遍确认每一步的数据源、工具、权限、输出格式再开始写技能定义。否则技能写得再漂亮也是纸上的流程落地就翻车。5.3 技能库过度膨胀后调用准确率下降这是我项目中期遇到的一个真实瓶颈。在技能库数量从十几个扩张到四五十个之后注册表已经塞不进系统提示众多技能描述相似度也高检索召回时常抓错。Agent开始频繁用错技能。我的解决路径分两步。第一步做技能合并把描述相近、任务重叠的技能合并成一个更通用的技能靠内部指令区分场景。第二步做分层设计把注册表拆成“全局技能”和“场景技能”两层全局技能始终加载场景技能只在用户请求进入特定场景时动态注入。这样既控制了上下文体积又避免了技能之间的互相干扰。这背后的经验是技能库不是收藏夹别什么都往里塞。定期审视技能的使用频率把长期没有触发记录的技能下线或合并保持技能库“小而精”。5.4 多技能协作时的输出格式冲突当单个技能运行稳定之后我开始尝试让Agent串联多个技能完成复合任务。这个时候出现了新问题技能A输出的结果技能B吃不下。比如技能A输出的是Markdown格式的概要技能B却期望收JSON格式的输入。排查下来根因是我在定义技能时只考虑了“对人类可读”没有考虑“对机器可用”。修改方案是给每个技能的输出部分增加标准的机器可读结构比如统一要求JSON输出或Markdown分节输出。更关键的是在串联技能时定义好“接口约定”——前一个技能输出什么字段、后一个技能从哪开始读全链条统一起来。现在我在新写技能时会在一开始就问自己一个问题“这个技能的输出能不能被另一个技能直接消费”这个视角极大提升了多技能协作的顺畅度。5.5 技能版本混乱改了啥都不知道还有一个容易被忽略的问题就是技能版本管理。技能是在频繁迭代的但我曾经连续改一个技能改了七八版也没系统记录过改了什么。结果某次线上效果大幅下滑我回滚都不知道滚回哪个版本。从那天起我坚持每个技能目录放一份CHANGELOG每次修改记录三件事改了什么、为什么改、效果如何。听起来很繁琐但等你需要回溯问题的时候这个记录能帮你节省数小时。不仅是给自己看更是给未来的协作者看——技能库也是代码库需要像对待代码一样对待。6. 技能评估与持续优化没有度量就没有改进6.1 评估集的建设场景覆盖与难度分层技能好不好不能靠感觉要靠数据。我在项目里维护了一套评估集每个技能至少配备十个测试用例覆盖典型场景、边界场景和反例场景。比如“生成数据库表结构”技能典型场景是“根据用户需求生成一张订单表”边界场景是“用户需求描述不清缺失字段类型”反例场景是“用户根本没提到数据库要求写文案”。每次改动技能后我会把这套评估集完整跑一遍统计通过率。这里的通过率是分拆到每个测试用例的而不是一个总的分数——因为只有看到具体哪个用例挂了你才知道该往哪个方向优化。6.2 评估指标不仅仅是准确率评估Agent技能时建议不要只用“最终输出对不对”这一个指标。因为技能涉及调用决策、执行过程、输出格式等多个环节各环节的问题需要用不同指标来捕捉。我会记录以下四类数据调用决策准确率该触发时是否触发不该触发时是否误触发。执行步骤完整率是否按技能定义完成了所有步骤有没有漏步骤。输出格式合法率生成的JSON能否被解析Markdown结构是否完整。用户侧满意度最终交付物是否真正满足用户需求。这类指标偏主观但不可或缺。四个指标分别定位不同环节的问题一起看才能全面评估技能的健康状况。我一般以周为周期复盘这些指标识别出质量下降的技能再针对性做迭代。6.3 基于失败样本的持续优化循环评估的价值在于发现失败样本失败的样本才是你改进技能的最大信息来源。我的迭代循环是收集失败案例、归类根因、小步修改、回归验证。有一个必须提醒自己的原则一次只改一个变量。你可以通过对比“变化描述”还是“变化示例”哪个对结果影响更大。如果一次改了好几处模型表现变好了你也说不清到底是哪一处起作用变差了就更麻烦不知道怎么回退。这类优化循环每完成一轮建议把旧版本和新版本在新采集的测试集上做对比测试确认改进不是偶然。经得起对比的改动才值得固化进技能文档里。6.4 技能的生命周期管理上架、维活、下架技能也是有生命周期的。新技能上线后会经历快速优化期、稳定使用期然后随着业务变化进入衰退期。衰退期的信号是调用率持续走低或错误率持续走高原因是业务场景已经变了这个技能不再匹配用户需求。遇到这种情况需要果断下线或重构。下线不代表删掉我会把它归档到独立目录保留历史版本和评估数据方便以后重新启用时参考。这个流程让技能库保持活性不让过时的技能拖累整体质量。7. 技能进阶方向多智能体协作与自进化试探7.1 技能在多智能体架构中的角色当你的Agent应用走向复杂单Agent很难完成所有任务你就需要考虑多智能体架构。在这样的架构中技能的定义需要更清晰每个Agent应该拥有自己的技能子集而不是共享一个庞大的技能库。我的划分思路是“按角色分配技能”。一个“项目经理Agent”拥有任务拆解、进度跟踪、风险预警这类技能一个“研发Agent”拥有代码生成、代码审查、单元测试生成这类技能。Agent之间通过消息协作而不是直接调用对方的技能。这种隔离降低了耦合度也让每个Agent的技能优化目标更明确。7.2 技能的自进化从使用数据中自动沉淀技能这是一个比较探索性的方向。我的思路是当Agent多次成功完成某类任务时可以把过程中的关键步骤、Prompt片段、工具调用序列记录下来自动沉淀为一个新的技能草稿然后通过评估集验证后纳入技能库。这个逻辑的本质是把“隐性的成功经验”转化为“显性的可复用技能”。听起来机器在自我进化但实际落地还是需要人来把关的——自动生成的技能草稿质量参差不齐必须经过人工审查、评估测试才能正式入库。7.3 跨项目迁移技能库的资产化技能一旦沉淀成熟就可以作为组织的资产跨项目迁移。比如你在电商项目里打磨出来的“生成商品描述”技能换到另一个零售项目中只需要调整产品术语和模板细节大体能力是通用的。我做跨项目迁移时通常分三步先评估技能与目标项目的匹配度再调整技能内示例数据和业务词汇最后在新的评估集上验证效果。这个流程能帮你避免每次都是从零开始搭建技能库的重复劳动。8. 技能与Agent安全容易被忽视的边界控制8.1 技能权限控制技能越强大权限边界就越重要。如果一个技能能执行Shell命令、修改文件、调用外部API而没有任何权限约束这个Agent就是一个潜在的危险源。我在技能定义里增加了权限元信息标明这个技能能访问哪些资源、能执行哪些操作、禁止执行哪些操作。在技能执行之前调度层会校验操作是否超出权限范围。这种“技能级权限控制”比在聊天侧做粗粒度限制细得多实际防御效果好很多。8.2 危险技能的双人复核机制对于涉及高影响操作的技能比如“执行数据库迁移”“推送生产环境代码”我要求执行前必须经过人工确认。最大程度避免Agent领会错意图就直接执行破坏性动作。实现上也不复杂技能执行流程中增加一个需要_人工确认True的标记。Agent生成执行计划后暂停等人工批准再继续。虽然牺牲了一部分自动化效率但换来的安全收益是值得的。8.3 技能失效时的降级策略技能不是永远可用的被调用的外部接口可能变更、依赖的数据库可能迁移。技能失效时你不能让Agent卡死或给出错误结果。我一般设置一个降级策略当技能执行失败时Agent会明确告知“当前无法完成该操作原因是XX”并尝试替代方案或建议人工介入。这个策略需要在技能文件里定义“失败处理”一节。明确告诉模型执行失败时应该怎么反馈。宁可让Agent承认自己做不到也不能让它编造一个结果出来。一点个人的实操体会写到这里我翻了一下自己这两个月来的技能文档修改记录发现一个有意思的规律前两周我花最多时间在写指令和调参后六周几乎全是在改描述、改示例、做边界约束。这让我越来越确定一个判断——技能的稳定性主要不来自复杂的内部逻辑而来自清晰的外部边界和准确的触发条件。你写的每一步指令、每一个示例、每一行描述本质上都是在跟模型“校准共识”。你描述得越精确模型的理解偏差就越小。这件事没有捷径只能靠一次次测试、一次次迭代去逼近那个平衡点。如果说有什么经验值得带走我会说先挑一个最常用的任务从最小技能做起用你手头真实的数据流和工具链把流程跑通再逐步往里面加复杂度。不要一开始就追求大而全的技能体系因为那会让你很难定位问题。一个能稳定运行、被你真正理解的小技能比十个看起来很全面但一上线就漏洞百出的大技能有价值得多。