做Agent开发这段时间，我最大的感受就是：代码写多了，真正让人头疼的不是模型能力不够，而是同一个任务，Agent每次干的活都不一样。今天让它总结一份会议纪要，它给你列了五条；明天再让它总结一份类似的，它给你列了八条，格式还换了。你问它为什么这么干，它能给你讲一堆“推理过程”，但结果就是不稳定。
后来我琢磨明白一件事：我们在用“对话”的方式让Agent干活，但工程化要的是“行为可控”。对话的特点是自由，工程的特点是约束。怎么平衡？答案就是我今天想聊的这套东西——agent-skills，一套给Agent建立“技能体系”的工程化实践方案。
这玩意儿解决的问题很直接：把那些经常要做的复杂操作，固化成一套标准动作，让Agent像熟练工一样按规范干活，而不是每次都临时发挥。它适合所有在搞Agent应用的人，不管你是做大模型产品、企业内部自动化流程，还是研究智能体的底层架构，这套思路都能用得上。下面我把整个设计逻辑和实操过程拆开讲，搞懂之后你手头的Agent绝对能上一个台阶。
1. 思路解构：为什么“工具”解决了连接，却解决不了稳定
很多人一听Agent技能，第一反应是“这不就是给Agent加几个工具函数吗”。这个理解差了根本。工具解决的是“Agent能干什么”的问题，技能解决的是“Agent怎么干才不出错”的问题，这是两层完全不同的设计。
1.1 工具与技能的分层逻辑
先说工具层。工具的本质是原子操作，比如“发送HTTP请求”“读数据库”“调用某个API”。它没有记忆、没有上下文、没有对任务的全局理解。你在代码里定义好输入输出结构，Agent需要的时候拿过来用就行。这个东西设计起来很爽，因为边界清晰，测试也好写。
但问题来了：现实世界的工作流，很少是单个原子操作能搞定的。拿“生成一份周报”来说，它可能涉及拉取本周工单、统计处理时长、分析异常项、调用模板生成文档、发给指定邮箱。这一串动作，你要是让Agent自己在运行时一步一步现场编排，那结果就看它当天心情了。某些模型今天觉得应该先用SQL查再调API，明天觉得可以并行处理，后天突然在中间插一段自己的“理解”。你说它错了吗？流程跑通的时候好像也没错。但一致性呢？没有。
技能层解决的就是这个。技能不是一个函数，它是一套“既定的动作序列 + 限制条件 + 经验约定”。它告诉Agent：当你遇到某一类任务时，不要自由发挥了，照着我预先打磨好的这套方法论来。工具是零件，技能是标准作业程序。Agent可以自己选零件去拼一台机器，但如果你想保证每台机器铆钉都打在同一个位置，你得给它一套装配手册，这就是技能。
1.2 为什么这个设计对当前Agent架构是必选项
当前主流Agent架构，说白了还是LLM循环：模型思考 → 决定动作 → 调用工具 → 看结果 → 继续思考。这个循环的自由度很高，高到失控的边缘。你在代码里设定max_iterations=10，它可能八步跑偏；你给它塞了一堆系统提示词，它可能上下文爆掉后开始自作主张。
原因在于，LLM本质上是个概率模型，同样的输入，每次输出的logits分布都不一样。你没法靠“提示词写得再清楚一点”来保证行为的一致性。提示词写长了，后面内容被稀释；写短了，约束不够。这也是为什么很多人最后发现，表面上是在做Agent开发，实际是在和概率搏斗。
技能体系改变的是这个系统的工作方式。当Agent识别到当前任务匹配某个技能时，它不再是“临时想怎么做”，而是“加载已经验证过的做法”。这套做法的每一步、每一个边界条件、每一个兜底逻辑，都是你在开发期反复打磨过的。模型只在必要的地方做决策，比如“读取到的数据里哪个字段属于异常值”，而不是在“我该用什么方式读取数据”这种层面重新发明轮子。
在我做的几个项目里，引入skills之后，最明显的变化是：同一类任务跑几十次，输出结构的方差大幅缩小。有些任务甚至能做到输出格式高度一致，直接进下游流程都不需要清洗。这种稳定性，光靠调模型参数或者堆提示词，是永远打不出来的。
1.3 一个核心矛盾：技能要固化到什么程度才不算过度设计
设计技能的时候最容易犯的错，是想把一切可能性都固化进去。比如写一个“文档总结技能”，不仅规定要用什么模型、什么模板、什么长度限制，还把“如果文档超过100页就分段总结再合并”这种分支也写死了。结果技能变得臃肿不堪，稍微遇到一个新场景就匹配不上。
我的经验是，技能固化的是“业务路径”和“行为边界”，而不是“具体参数”。所谓业务路径，是完成这个任务必须经过哪些环节、这些环节以什么顺序执行；行为边界是哪些事情绝对不能做、哪些情况下必须停下来问人。至于每步具体怎么调参数，那是Agent在执行时根据上下文自己决定的。技能是流程的骨架，不是血肉。留出适配的空间，才有泛化的可能。
这个原则，后面在讲技能内部构造的时候还会反复提到。
2. 核心细节解析：一套完整技能长什么样
那么，一个真正的、可以被Agent稳定调用的技能，内部到底是什么结构？我把它拆成四个组成部分，缺一个，技能的可靠性都会打折扣。
2.1 技能注册信息：让Agent知道“什么时候该用我”
这是最容易被忽略但最致命的部分。技能的调用时机不是写死在代码里的，而是由Agent根据当前任务上下文，从一个技能清单里选择的。如果Agent根本不知道你的技能存在，或者不知道什么情况下应该用它，那这个技能就等于白写了。
技能注册信息里最关键的是description字段。这个字段直接决定了Agent在技能之间做匹配时的成功率。很多人图省事，写一句“用于生成工作报告”，结果Agent在该用的时候往往不选它，选了别的更“看起来像那么回事”的工具。我个人的经验是，description要写成场景触发式，描述“用户遇到什么情况时，这个技能能帮他做什么”，而不是干巴巴地写功能名称。这背后是LLM做语义匹配时的工作机制：它更擅长匹配具体的场景描述，而不是抽象的功能概括。
另外注册信息里最好带上边界声明——写明这个技能不擅长处理什么、不适合什么场景。这个看起来反直觉，因为一般人都觉得描述应该尽量让人想用它。但实测下来，边界声明反而能显著提升匹配准确率。因为Agent在做决策时，如果同时看到好几个候选技能，负向信息能帮它快速排除掉错误选项，这和人类做选择题时排除法更好用是一个道理。
2.2 技能体：一段经过验证的标准操作流程
这是技能的主体，也是一般人理解的“技能本体”。在实现上有两种主流方式。一种是纯代码编排，把每个步骤写成函数调用，技能体就是一个执行函数；另一种是半结构化脚本，配合LLM在关键环节做决策，比如“这一步根据读取到的内容判断是走分支A还是分支B”。
从工程实践看，我推荐多数场景用半结构化方式。为什么？因为纯代码编排的优点是稳定、可测试，但缺点也很明显：灵活性差。Agent面对的输入千变万化，你不可能把每个分支都预先写死。半结构化脚本的好处是，把步骤框架定死，每一步可以用代码实现，但步骤和步骤之间的衔接、每一步内部的数据处理，允许模型在约束范围内自由适配。这样既有确定性，又有适应性。
技能体内部要显式声明“退出条件”——也就是技能执行到什么程度就算完成。这一点很多实现里面没有，导致Agent把技能跑完之后，没法明确告诉系统“任务已经做完了”，而是又回到主循环里继续思考，白白浪费算力，还可能画蛇添足地再补一刀。我在技能体里固定加一个terminate步骤，技能内部逻辑跑完，必须返回一个结构化结果，标明执行状态、产物位置、遗留风险，这些信息对后续流程的可跟踪性至关重要。
2.3 技能的经验沉淀：把“踩过的坑”变成下次不踩的保证
这是我和很多做Agent的同学交流时发现，大家普遍没有意识到的一个设计点。Agent和普通程序最大的区别是，它在执行过程中会产生大量上下文信息——某个API报错了、某个分支走偏了、某个参数不符合预期。这些信息如果每次执行后都扔掉，那下一次遇到同样的情况，Agent还会在同一个地方踩坑。
技能体系里，我会为每个技能配置一个小型的经验记录区，它是跟着技能走的，不是跟着会话走的。技能每次执行，系统会把执行轨迹中的关键节点记录下来，包括：卡点发生在哪一步、当时Agent做了什么决策、最终如何解决的。下一条相同任务过来，Agent在加载技能的时候，会把这些历史经验一并带到上下文中，作为参考。
这个方法一开始我没抱太高期望，但实际效果意外地好。它相当于给Agent做了一个“肌肉记忆”的机制，而且实现成本很低——不需要微调模型，不需要改权重，就是结构化地把过往轨迹沉淀下来，在合适的时机重新注入上下文。随着技能被使用的次数增加，它的表现会越来越稳定，相当于越用越智能。
2.4 技能与短期记忆的配合边界
还有一个很多文档里不会讲的问题：技能和上下文记忆的边界在哪。
技能里不该装的是：当前任务的具体数据、对话历史、用户偏好。这些属于工作记忆（working memory），应该放在会话上下文中，随任务结束而销毁。你要是把这些东西也塞进技能，技能会膨胀成一个越来越大的脏袋子，最后查询和匹配都会变慢，而且上一个任务的信息还会干扰下一个任务的表现。
技能里该装的是：稳定的、可复用的方法论、经验规则、兜底逻辑。这些不随具体任务变化，属于长期记忆（long-term memory）。
我在项目里的切分标准很简单：这段内容，换一个用户、换一批数据，还能不能照样用？能，放技能里；不能，放会话上下文中。这个原则看着简单，能坚持执行却是另一回事——很多人写着写着就把具体业务的临时规则混进去了。
3. 实操过程：从零搭建一套可用的技能体系
说了这么多理论，下面进入正题：怎么从零开始，把这套东西在你的项目里落地。我拿一个通用场景——“生成项目周报”来走一遍完整流程，你照着这个路径可以举一反三。
3.1 第一步：整理技能清单，先列业务场景而不是列功能
很多人的习惯是从功能出发，想着“我的系统要能处理文档、要能查数据、要能发通知”，然后一个一个做工具。这样做的结果是工具确实不少，但Agent不知道怎么用，也不知道什么时候该用哪个。
我的做法是反过来的：从业务场景出发，列出用户的高频真实需求。比如你做的是一个团队协作助手，高频场景可能是：周报生成、工单分派、进度同步、风险预警。这些才是技能的一等公民。工具是技能用到的“弹药”，是技能内部实现时才会具体设计的东西。
场景清单整理好之后，再对每个场景做一个小型流程分析——拆解它包含哪些环节，每个环节可能有哪些变化形式。比如“工单分派”，可能因为工单类型不同、紧急程度不同，分派策略也不一样，这就是技能内部的分支点。
3.2 第二步：为场景写注册信息，用三个问题校准匹配率
这一步看起来简单，其实最需要反复打磨。我会用三个问题来检验description写得好不好：
第一个问题：把这个description盖住技能名，让另一个开发者（或者让模型自己）来猜测这个技能是干什么的，能不能猜得准。
第二个问题：反过来，给一堆任务描述，看这个description能不能被准确触发。我做过一个实验，把十几个技能的description打乱，让模型做匹配，结果发现写得越具体的匹配率越高，而写“通用型”“多功能”这种词的，基本匹配率惨不忍睹。
第三个问题是负面测试：拿一批和这个技能无关的任务喂进去，看它会不会被误触发。误触发比不触发还麻烦，因为它会静默地跑一个不该跑的操作，可能造成数据污染。
经过这三个问题打磨，description基本就能达到可用状态了。这里再强调一次：场景描述优于功能描述，负向声明一定要有。
3.3 第三步：实现技能体，用“流程框架 + 决策点”的结构组织代码
我实际使用的技能体结构，代码层面长这样：
class WeeklyReportSkill: """生成项目周报的技能。 Attributes: procedure: 主流程定义，按顺序执行 decision_points: 流程中的动态决策点 """ def __init__(self): self.name = "weekly_report_generator" self.procedure = [ "fetch_task_records", # 强制第一步：获取任务记录 "aggregate_by_status", # 强制第二步：按状态聚合 "analyze_exceptions", # 决策点：异常项分析 "render_to_template", # 强制第四步：填模板 "verify_output", # 强制第五步：自检输出 ] self.decision_points = { "analyze_exceptions": self._decide_exception_action } def run(self, context: dict) -> dict: """执行技能主流程。""" result = {"status": "success", "artifacts": {}, "risks": []} for step in self.procedure: method = getattr(self, step) step_result = method(context) result["artifacts"].update(step_result) if step in self.decision_points: decision = self.decision_points[step](step_result) if decision == "abort": result["status"] = "need_human_input" break return result这里的关键设计是procedure用列表显式定义，而不是散落在各种if-else里。这样整个流程的路径一目了然，新人接手也能快速看懂。而且每一步的结果都被记录到artifacts里，方便最后追溯整个执行过程。
这个实现方式的最大好处是：流程骨架是强制的，Agent不能跳步，不能调整顺序。你可能会问：这样会不会太死板？我的回答是：任何“合格”的执行路径都应该被固化，你不固化，Agent就会自由发挥，而自由发挥对工程来说就是bug。决策点的存在，已经给了它必要的灵活性。
3.4 第四步：配置技能索引，让Agent“找得到”技能
技能多了之后，还有个工程问题：怎么让模型高效地从技能库中选出正确的那一个。我把技能注册信息汇总到一个索引表里，每次请求只把索引表相关片段加载到上下文中，而不是把全部技能描述都塞进去。
skills_index: weekly_report_generator: category: "reporting" triggers: - "周报" - "weekly report" - "项目进展汇报" dependencies: ["task_system_api", "template_renderer"] output_schema: "report_artifact_v2" work_order_dispatcher: category: "dispatch" triggers: - "工单分派" - "指派任务" - "assign work order" dependencies: ["user_directory_api", "work_order_db"] output_schema: "dispatch_result_v1"这个索引表本身也是技能体系的一部分，我把它当成配置来管理，代码和配置分离。每次技能更新，索引自动同步。这样Agent匹配的时候，先读索引表做粗筛，再加载对应技能详情做细匹配，开销小，准确率高。实测下来加载成本至少降了50%，匹配率反而涨了十几个点。
3.5 第五步：为每次技能执行留痕，异常必须有记录
运行记录和复盘机制，是技能体系能否持续演进的保障。我要求每个技能执行完，都要生成一个标准的执行报告，包含：触发原因、匹配置信度、执行路径、各步骤耗时、决策点决策依据、异常项描述、最终产物位置。
这些报告不只是给人看的，它们还有一个重要用途：反哺上一节说的“经验沉淀区”。系统会对执行报告做自动化摘要，提取出有哪些步骤运行耗时异常、哪些决策点反复横跳、哪些异常经常出现，然后以“技能使用建议”的格式回写到经验区里。下一轮技能执行时，这些建议会被加载到上下文中，帮助Agent避开上次踩过的坑。
这套机制跑起来之后，整个技能体系是活的——每次执行都在增强自身。虽然每次迭代的变化很微小，几个月下来，技能在特定场景的表现会肉眼可见地变好。
4. 高频问题与排查技巧：我踩过的坑，记在这里
这个章节整理一下实操中我碰到最多的问题，以及对应的排查思路。每一条都是我亲手踩过的，分享出来，能帮你少花几个晚上的调试时间。
4.1 技能匹配老是“复读到不了闸”，怎么办
这是出现频率最高的问题：技能库建好了，Agent在任务中却完全不调用技能，或者调用了错误的技能。
先查注册描述。我在2.2里说过，description写成场景触发式，不要写抽象功能。如果这个已经做到了，再看是不是索引表的问题。比如技能索引里triggers写得太死，只匹配了中文关键词，用户用英文提问就触发不了。
还有一个隐蔽的问题，排查起来挺费劲的：技能之间描述相似度太高。特别是同一类任务的不同变体，比如“生成周报”和“生成月报”，描述如果不仔细区分，Agent在匹配时经常选错。解决办法是，在负向边界里明确写清楚“如果你正在处理月度汇总，不要使用本技能”。这种负向提示在同类技能比较多的时候，效果立竿见影。
最后还有一个权重因素。系统提示词中，技能列表是放在比较靠前的位置还是靠后的位置，会显著影响匹配率。我做过对比测试，把技能索引放在系统提示词前1/4的位置，比放在后半部分匹配率高出来将近20%。做的时候可以顺手验证一下。
4.2 技能体过厚：把技能写成了“小系统”
对应的反面问题也常见：一个技能内部塞了大量逻辑，执行路径巨长，一个技能体跑起来像是跑了一个完整应用。这样做的后果是：执行时间长、上下文占用大、调试困难，而且因为把大量决策集成在技能里，Agent在技能内部的自由度也被压缩得很厉害，反而更容易跑偏。
我用来自查的原则是：如果一个技能执行路径中，需要读取外部配置的选项多于五个，或者步骤之间传递的中间数据超过七八个字段，就说明这个技能太厚了。解决方法是拆技能——把大技能拆成几个相互独立又相互配合的子技能。子技能之间通过标准输入输出接口衔接，Agent负责编排子技能，子技能内部各自保持精简。这符合软件工程里的“单一职责”，而且在Agent场景下尤其重要，因为模型对复杂流程的控制力是有限的，超过一定复杂度就失控。
拆技能的另一个好处是，子技能的复用性天然会提高。比如“拉取任务记录”如果单独做成一个技能，不管是生成周报、做进度分析、还是预警通知，都能调用它，而不是各自内部写一套。
4.3 决策点反复横跳：同一个输入，给不同的输出
这是技能体系引入后新冒出来的问题，在纯工具调用时代反而不存在。原因在于决策点用的是LLM做判断，模型本身有随机性。同样一批数据，第一次分析认为异常，第二次觉得正常；第一次走分支A，第二次走分支B。
排查这个问题，首先区分是模型随机性还是上下文污染。模型随机性可以通过低温度参数解决，我一般把决策点的temperature调到0.2以下；上下文污染，指的是上一次执行的中间数据残留在上下文中，干扰了下一次判断，这种情况要检查上下文管理逻辑，确保每次技能执行前，历史执行数据已经被清理干净。
如果做到这两点还在横跳，那就是决策逻辑本身有问题。比如判断标准写得太模糊，“如果数据表现异常就提示”，什么叫“异常”？没有量化标准，模型每次都会有自己的理解。解决方法是把判断标准具体化，至少给出可操作的数值边界或者明确的模式匹配逻辑。决策点不是让模型“感觉”该怎么做，而是让模型“依据什么”该怎么做。
注意：很多人以为给Agent更长的思考时间能解决决策不稳定问题，在实际测试中这往往是反向效果。思考链太长，模型反而会在中间步骤产生更多偏移，让决策结果更不稳定。你的决策点设计，应该让模型“少想”，而不是“多想”。
4.4 治理策略：让技能库保持健康状态
技能库是一种会不断增长的系统资产。如果不加治理，它会像没人打理的代码仓库一样，慢慢变得冗余、冲突、混乱。
我维护技能库的几条规定，都是血的教训换来的：
第一，技能新增必须有实际调用数据支撑。新技能上线后，先小流量跑，观察匹配率和成功率。如果一个技能上线两周，触发次数还是个位数，或者触发了但执行失败率高，就考虑回滚或者重构，不要让它长期躺在技能库里占资源。
第二，定期做技能去重。技能多了之后，很容易出现功能重叠——这个技能处理“周报”，那个技能处理“项目总结”，实际业务边界就是模糊的。我每季度会做一次技能清单review，把边界模糊的合并，把调用率低的淘汰。
第三，技能更新要留版本。技能内部实施的是行为逻辑，一旦行为发生变化，下游的产物格式就可能变。如果直接原地更新，之前依赖旧行为的流程全部受影响。给技能体做版本管理，更新时走灰度切换，至少能保证出问题的时候有回滚的余地。
治理这个事，短期看增加了一点工作量，长期看是让技能体系持续发挥作用的唯一办法。没有治理的技能库，半年后就会腐化成一堆互相矛盾的无序流程，比没有技能体系还麻烦。
5. 写在最后：这是技能工程，不是提示词工程
最后说一点我对这件事的大判断：很多人现在还把所有精力花在写提示词上，觉得提示词写得好Agent就听话。这个思路已经在过时了。提示词解决的是单次对话的引导问题，技能体系解决的是跨会话、跨任务的行为一致性问题。后者才是Agent真正走向工程化的必经之路。
我在这个项目里切身体会到，Agent技能体系的威力不在于某一个技能写得多漂亮，而在于它建立了一个“行为经验库”的增长飞轮——每一次执行都在沉淀经验，每一次沉淀都在让下一次执行更好。这个机制一旦运转起来，你的Agent就不是一个“每次都重新开始”的实习生，而是一个“越干越熟练”的老员工。
你可能会问，技能体系是不是只能用于AI Agent开发？也不全是。这套思路里，“把成熟流程固化、把踩坑经验沉淀、把匹配机制做精准”的底层方法论，放到很多业务系统设计里都是一样通用的。本质上，它是在解决一个古老的问题：如何让一个能力很强但自由散漫的执行者，变成稳定可靠的工程单元。
实操中保持一个习惯会很受益：每次技能执行失败，不要急着改代码，先记录当时的输入、上下文、决策过程，然后才能在根源上定位是匹配问题、流程问题还是决策点设计问题。这个记录习惯，是技能体系能够持续迭代的根本，也是我个人觉得这套方案最值得借鉴的一个地方。
