1. 从"agent-skills"这个命名说起：它到底指什么第一次看到"agent-skills"这个词，很多人会下意识地把它理解成某个具体的库或者框架。但如果你在工程实践里摸爬滚打过一段时间就会发现，它更像是一个能力组织范式，而不是一个可以直接pip install的包。这个区别非常关键，因为它决定了你后面所有的设计思路。我先把结论摆在前面：agent-skills 描述的是一套让智能体（agent）具备可插拔、可组合、可复用能力的组织方式。核心思想是把"一个智能体能做什么"拆解成一个个独立的技能单元，每个技能单元负责一类明确的输入输出，然后由一个调度层根据任务需要去组合调用这些技能。听起来有点像微服务，也有点像函数式编程里的组合子，但它的特殊之处在于——这些技能是给一个具备推理能力的智能体用的，而不是给一段确定性代码用的。为什么这个区分重要？因为如果你把它当成一个普通库，你会去找它的 API 文档、安装方式、版本号；但如果你把它理解成一种范式，你就会去思考：我的智能体需要哪些原子能力？这些能力之间怎么编排？状态怎么传递？失败怎么回滚？这些才是真正决定项目成败的问题。从关键词和摘要都为空这一点也能侧面印证——这个标题本身就是一个概念性的、偏架构层面的命名，而不是某个具体产品的名字。所以这篇内容我不会去编造一个不存在的库的用法，而是基于这个命名所指向的真实工程问题，把"如何给智能体设计和组织技能"这件事讲透。适合的读者是：正在做智能体应用、被"一个 prompt 塞所有功能"搞得焦头烂额、想让系统更可维护的开发者。2. 为什么"把所有能力塞进一个提示词"迟早会崩2.1 单体提示词的三个隐性成本刚开始做智能体应用时，几乎所有人都会走同一条路：写一个超长的系统提示词，把能想到的所有能力都描述进去。"你可以帮我查资料、可以帮我写代码、可以帮我总结文档、可以帮我做表格……" 一开始跑得挺顺，demo 效果也不错。但项目一旦进入真实使用阶段，问题就会集中爆发。第一个成本是注意力稀释。模型的上下文窗口是有限的资源，你塞进去的每一条能力描述都在和别的描述争夺模型的"注意力"。当能力超过七八个之后，模型开始出现"忘记某条规则""把两个技能的触发条件搞混"的情况。这不是模型变笨了，而是你给它的指令密度超过了它能稳定遵循的阈值。第二个成本是测试无法隔离。单体提示词下，你没法单独测试"总结文档"这个能力是否正常，因为它的行为会受到提示词里其他所有内容的干扰。改了一处，可能另一处就坏了，回归测试基本靠人肉。第三个成本是无法复用。你在 A 项目里写好的"文档总结"逻辑，想搬到 B 项目，只能整段复制粘贴，然后手动删掉不相关的部分。复制的那一刻，两份代码就开始各自漂移了。2.2 技能化拆解带来的结构性收益agent-skills 这套思路要解决的，正是上面这三个问题。把能力拆成独立技能之后，每个技能有自己清晰的职责边界、自己的输入输出契约、自己的测试用例。调度层只负责"什么时候调用哪个技能"，不关心技能内部怎么实现。这样带来的收益是连锁的：测试可以针对单个技能做，改一个技能不会影响别的；技能可以在不同项目间直接复用；提示词的复杂度被分散到各个技能内部，每个技能的提示词都短而聚焦，模型遵循度自然就上去了。我自己的经验是，当一个智能体的能力超过五个之后，技能化拆解带来的维护性提升会迅速超过拆解本身带来的复杂度。也就是说，前期多花的那点架构成本，很快就能回本。2.3 一个判断标准：什么时候该拆不是所有项目都值得上技能化架构。我的判断标准很简单：如果你发现自己在反复修改同一段提示词，而且每次修改都要重新验证一堆不相关的功能，那就该拆了。反过来，如果只是一个单一用途的小工具，比如"把这段文字翻译成英文"，那完全没必要拆，一个函数调用就够了。拆解的粒度也有讲究。太粗，等于没拆；太细，调度开销会吃掉收益。一个比较实用的经验是：一个技能应该对应一个"人一眼能说清楚它干什么"的职责。比如"从网页提取正文""把长文切成段落""给段落生成摘要"是三个技能，而"处理文档"就是一个太粗的职责。3. 技能单元的设计：接口、状态与边界3.1 每个技能都应该有明确的输入输出契约设计技能时，最容易犯的错误是让技能的输入输出变得模糊。比如一个"搜索"技能，输入是"一个字符串"，输出是"一些结果"——这种定义在真实系统里会立刻出问题：字符串是查询词还是自然语言问题？结果是列表还是文本？包含哪些字段？我的做法是给每个技能定义一份显式的契约，用类似下面这样的结构描述：# 技能契约示例（伪代码，描述结构而非具体实现） skill_contract = { "name": "extract_article", "description": "从一段HTML中提取正文内容", "input_schema": { "html": "string, 必填, 原始HTML", "url": "string, 可选, 用于解析相对链接" }, "output_schema": { "title": "string", "content": "string", "links": "list[string]" }, "failure_modes": ["html为空", "无法识别正文区域"] }这份契约的价值在于，它让调度层和技能实现之间有了一个稳定的约定。调度层不需要知道技能内部是用正则还是用模型，只需要知道"给它这些，它会还我那些"。这也是后面做自动化编排和错误处理的基础。3.2 状态传递：技能之间怎么"对话"技能是独立的，但任务是有前后依赖的。比如"提取正文"之后要"切分段落"，切分需要用到提取的结果。这个结果怎么传？有两种常见模式。一种是显式数据流：调度层维护一个共享的上下文对象，每个技能从里面读自己需要的字段，写自己产出的字段。这种方式清晰、可追踪，适合流程相对固定的场景。另一种是消息传递：技能之间通过消息队列通信，适合异步、并发的场景。对于大多数智能体应用，我推荐显式数据流，因为它更容易调试。你可以随时打印出上下文对象，看到每一步之后系统"知道"了什么。消息传递虽然灵活，但排查问题时链路会拉得很长。这里有个细节值得注意：上下文对象不要无限增长。如果每个技能都把原始输入和中间结果全塞进去，上下文会迅速膨胀，既浪费 token 又干扰模型。我的做法是给上下文定义明确的字段，技能只写自己负责的字段，中间产物用完就丢。3.3 边界处理：技能失败时谁来兜底技能失败是常态，不是异常。网络会抖、模型会抽风、输入会不符合预期。所以每个技能都必须定义清楚自己的失败模式，以及失败后应该怎么办。我一般把失败分成三类：可重试失败（比如临时网络问题）、可降级失败（比如某个数据源挂了，可以用备用源）、不可恢复失败（比如输入格式完全不对）。调度层根据失败类型决定是重试、降级还是直接上报。这里有个反直觉的经验：不要让技能自己决定要不要重试。技能应该只负责报告"我失败了，原因是X"，重试策略交给调度层统一管理。否则每个技能都自己重试，重试次数会叠加，一个请求可能触发几十次调用，把下游打挂。4. 调度层：让技能真正"活"起来的那一层4.1 调度层的核心职责技能本身只是静态的能力单元，真正让它们协同工作的是调度层。调度层要回答三个问题：当前任务需要哪些技能？按什么顺序调用？调用结果怎么处理？最简单的调度是硬编码的流水线：先调 A，再调 B，再调 C。这种方式在流程固定的场景下完全够用，而且可预测性最强。但智能体的价值恰恰在于处理不确定的任务，所以更常见的是基于模型决策的动态调度：把可用技能的描述（注意，只是描述，不是实现）提供给模型，让模型根据当前任务决定下一步调用哪个技能。这两种方式不是对立的。我的实践是混合调度：主干流程用硬编码保证稳定性，分支决策交给模型。比如"提取正文→切分段落"是固定的，但"切分之后是生成摘要还是提取关键词"可以根据用户意图动态决定。4.2 技能描述怎么写才能让模型选对动态调度的效果，几乎完全取决于技能描述的质量。模型是根据描述来决定调用哪个技能的，描述写得含糊，模型就会选错。写技能描述有几个要点。第一，说清楚"什么时候用"比"它是什么"更重要。比如"extract_article"这个技能，描述里要写"当用户提供了一段网页HTML，需要获取其中的正文文字时使用"，而不是只写"提取文章"。第二，明确排除条件。如果两个技能容易混淆，就在描述里写清楚边界，比如"如果输入已经是纯文本，不要用这个技能，直接用 split_paragraphs"。第三，描述要短。每个技能的描述控制在两三句话以内，因为所有技能的描述会一起进入模型的上下文，描述太长会挤占空间。我见过有人给每个技能写一大段说明，结果十几个技能加起来几千字，模型反而更容易选错。4.3 一个容易忽略的问题：技能数量与选择准确率的关系这里有个实测出来的规律：当可选技能超过十个之后，模型的选择准确率会明显下降。这不是模型的问题，而是人类自己面对十几个选项时也会犹豫。解决办法是分层组织。把技能按领域分组，先让模型选组，再在组内选技能。比如先分"文本处理""数据查询""文件操作"三组，模型先判断任务属于哪组，再在组内做细选。这样每一层的选项都控制在个位数，准确率会回升。另一个办法是动态裁剪。根据当前上下文，只把相关的技能暴露给模型。比如当前在处理一个纯文本任务，那所有跟文件、网络相关的技能就不需要出现在选项里。这需要调度层维护一套技能与场景的映射关系，前期有点工作量，但长期收益很大。5. 把技能串起来：编排、复用与版本管理5.1 编排模式：串行、并行与条件分支技能编排有三种基本模式，理解它们的适用场景能帮你少走弯路。串行是最常见的：A 的输出是 B 的输入，B 的输出是 C 的输入。适合有严格依赖关系的流程。并行适合相互独立的子任务，比如同时从三个数据源拉取信息，最后合并。并行能显著降低延迟，但要注意合并时的冲突处理。条件分支适合根据中间结果决定后续路径，比如"如果提取到的正文长度小于阈值，就走'提示用户内容过短'的分支"。实际项目里这三种模式往往是嵌套的。我的建议是先用串行把流程跑通，再针对明显的性能瓶颈做并行化。一上来就设计复杂的并行编排，调试成本会高得离谱。5.2 技能复用：怎么避免"复制粘贴式复用"技能复用的最大敌人是"看起来一样但其实不一样"。你在 A 项目里写了个"总结文档"技能，B 项目也需要总结，但 B 的总结要求更简短、更口语化。这时候直接复制一份改改，短期最省事，长期就是两份要各自维护的代码。更好的做法是把可变部分参数化。总结技能接受一个"风格"参数，A 项目传"正式"，B 项目传"口语"。这样技能只有一份，差异通过配置表达。当然，参数化也有度，如果参数多到十几个，说明这个技能承担了太多职责，该拆了。判断标准是：如果两个使用场景的差异可以用一两个参数表达，就参数化；如果需要改技能内部逻辑，就拆成两个技能。5.3 版本管理：技能升级时怎么不炸掉老流程技能是会演进的。今天"提取正文"只返回纯文本，明天可能要加上图片链接。如果直接改，所有依赖它的流程都可能受影响。我的做法是给技能加版本号，并且默认保持向后兼容。新增字段可以，但不要删字段、不要改字段含义。如果确实需要破坏性变更，就发一个新版本，老流程继续用老版本，新流程用新版本，给迁移留出时间窗口。这套做法借鉴的是 API 版本管理的思路，用在技能上同样有效。关键是要在调度层记录每个流程依赖的技能版本，这样升级时能清楚知道影响范围。6. 实测中踩过的坑与排查思路6.1 技能"看起来被调用了"但结果不对这是最让人头疼的一类问题：日志显示技能被调用了，参数也对，但返回结果就是不符合预期。排查这类问题，我的顺序是先看输入，再看技能内部，最后看输出解析。先确认输入：调度层传给技能的参数，和技能实际收到的参数，是不是一致的？中间有没有被序列化/反序列化搞坏？我遇到过一次，上下文对象里的一个列表在传递过程中被转成了字符串，技能收到的是字符串而不是列表，行为自然不对。再看技能内部：如果技能内部也调用了模型，那就要检查模型这次是不是"发挥失常"。同一个提示词，模型在不同时候的输出可能不同。这时候要看技能有没有对模型输出做校验，校验失败时有没有明确的错误信息。最后看输出解析：技能返回的结构，和调度层期望的结构是否匹配？字段名有没有拼错？类型对不对？这类问题在动态语言里特别常见，因为不会在编译期报错。6.2 上下文膨胀导致的"越跑越慢"项目跑一段时间后，你会发现响应越来越慢，token 消耗越来越高。八成是上下文在膨胀。排查方法是在每个技能调用前后打印上下文的字段和大小。你会看到某些字段在无限增长，比如"历史消息"列表从来没被清理过，或者某个技能每次都往上下文里追加而不是覆盖。解决办法是给上下文定义生命周期。哪些字段是全局的（整个任务期间保留），哪些是临时的（用完即弃），哪些是滚动的（只保留最近 N 条）。这个设计要在架构阶段就想清楚，后期补会很痛苦。6.3 技能之间的"隐性耦合"技能本该是独立的，但实际中经常出现隐性耦合。比如技能 B 假设技能 A 一定在它之前运行过，所以直接读 A 写的字段。如果某天流程调整，A 没跑，B 就崩了。这种耦合不会在代码里显式体现，所以特别隐蔽。我的应对办法是让每个技能显式声明自己的前置依赖，调度层在调用前检查依赖是否满足。不满足就报错，而不是让技能在运行时莫名其妙地失败。另一个办法是给技能写独立的测试，测试时只提供该技能需要的输入，不依赖其他技能。如果这个测试跑不通，说明技能有隐性依赖。7. 从能跑到好用：几个提升稳定性的实操技巧7.1 给技能加"自检"环节技能执行完，不要直接返回结果，先做一次自检。自检的内容包括：输出结构是否符合契约、关键字段是否为空、数值是否在合理范围内。自检不通过就按失败处理，而不是把脏数据传给下游。这个环节看起来多余，但能拦住大量"看起来成功其实失败"的情况。我见过太多因为一个空字段一路传到底、最后在用户面前才暴露的问题。7.2 用"影子运行"验证新技能新技能上线前，可以先让它"影子运行"：在真实流程里调用它，但不用它的结果，只记录它的输出，和现有方案对比。跑一段时间，确认它的表现稳定、结果合理，再正式切换。这种方式比单元测试更接近真实场景，又不会影响线上。代价是要多维护一套对比逻辑，但对于核心技能，这个投入是值得的。7.3 给调度决策留"后悔药"动态调度下，模型可能选错技能。如果选错了就直接执行，可能产生副作用（比如发了一封不该发的邮件）。我的做法是对高风险技能加确认环节：调度层决定调用后，先不执行，而是把"打算调用哪个技能、传什么参数"展示出来，确认无误再执行。这个确认可以是人工的，也可以是自动的规则校验。关键是给系统一个"反悔"的机会，而不是一路执行到底。7.4 记录完整的调用链路每个任务从开始到结束，完整记录调用了哪些技能、每个技能的输入输出、耗时、成功失败。这份链路日志在排查问题时价值极高，因为你能完整复现一次任务的执行过程。日志的粒度要平衡。太粗，排查时信息不够；太细，日志量大到没法看。我的经验是记录技能的输入输出摘要和关键中间状态，完整数据按需采样。8. 关于 agent-skills 这套思路，我自己的几点体会做了几个基于技能化架构的智能体项目之后，我最大的体会是：这套思路的价值不在于技术有多新，而在于它强迫你把"智能体到底能做什么"这件事想清楚。在单体提示词时代，很多能力边界是模糊的，因为反正都塞在一起。一旦要拆成技能，你就必须回答"这个技能的输入是什么、输出是什么、什么时候用、失败了怎么办"——这些问题想清楚了，系统自然就稳了。第二个体会是不要过度设计。我见过有人一上来就设计了一套复杂的技能注册、发现、编排框架，结果项目本身只有三个技能。技能化的收益来自规模，技能少的时候，简单直接反而更好。先跑起来，等能力多到管不过来了再拆，这个顺序不能反。第三个体会是技能描述的质量决定一切。动态调度下，模型选技能的依据就是描述。描述写得好，系统就聪明；描述写得烂，再好的架构也白搭。花在打磨技能描述上的时间，回报率比花在优化调度算法上高得多。最后一个，也是我觉得最容易被忽略的：给技能留出"我不知道"的出口。很多技能被设计成"必须返回一个结果"，于是模型在不确定的时候也会硬编一个答案出来。更好的设计是允许技能返回"无法处理"，让调度层去决定是换个技能、还是向用户澄清。承认不知道，比编一个错误答案有价值得多。
1. 从"agent-skills"这个命名说起：它到底指什么第一次看到"agent-skills"这个词，很多人会下意识地把它理解成某个具体的库或者框架。但如果你在工程实践里摸爬滚打过一段时间就会发现，它更像是一个能力组织范式，而不是一个可以直接pip install的包。这个区别非常关键，因为它决定了你后面所有的设计思路。我先把结论摆在前面：agent-skills 描述的是一套让智能体（agent）具备可插拔、可组合、可复用能力的组织方式。核心思想是把"一个智能体能做什么"拆解成一个个独立的技能单元，每个技能单元负责一类明确的输入输出，然后由一个调度层根据任务需要去组合调用这些技能。听起来有点像微服务，也有点像函数式编程里的组合子，但它的特殊之处在于——这些技能是给一个具备推理能力的智能体用的，而不是给一段确定性代码用的。为什么这个区分重要？因为如果你把它当成一个普通库，你会去找它的 API 文档、安装方式、版本号；但如果你把它理解成一种范式，你就会去思考：我的智能体需要哪些原子能力？这些能力之间怎么编排？状态怎么传递？失败怎么回滚？这些才是真正决定项目成败的问题。从关键词和摘要都为空这一点也能侧面印证——这个标题本身就是一个概念性的、偏架构层面的命名，而不是某个具体产品的名字。所以这篇内容我不会去编造一个不存在的库的用法，而是基于这个命名所指向的真实工程问题，把"如何给智能体设计和组织技能"这件事讲透。适合的读者是：正在做智能体应用、被"一个 prompt 塞所有功能"搞得焦头烂额、想让系统更可维护的开发者。2. 为什么"把所有能力塞进一个提示词"迟早会崩2.1 单体提示词的三个隐性成本刚开始做智能体应用时，几乎所有人都会走同一条路：写一个超长的系统提示词，把能想到的所有能力都描述进去。"你可以帮我查资料、可以帮我写代码、可以帮我总结文档、可以帮我做表格……" 一开始跑得挺顺，demo 效果也不错。但项目一旦进入真实使用阶段，问题就会集中爆发。第一个成本是注意力稀释。模型的上下文窗口是有限的资源，你塞进去的每一条能力描述都在和别的描述争夺模型的"注意力"。当能力超过七八个之后，模型开始出现"忘记某条规则""把两个技能的触发条件搞混"的情况。这不是模型变笨了，而是你给它的指令密度超过了它能稳定遵循的阈值。第二个成本是测试无法隔离。单体提示词下，你没法单独测试"总结文档"这个能力是否正常，因为它的行为会受到提示词里其他所有内容的干扰。改了一处，可能另一处就坏了，回归测试基本靠人肉。第三个成本是无法复用。你在 A 项目里写好的"文档总结"逻辑，想搬到 B 项目，只能整段复制粘贴，然后手动删掉不相关的部分。复制的那一刻，两份代码就开始各自漂移了。2.2 技能化拆解带来的结构性收益agent-skills 这套思路要解决的，正是上面这三个问题。把能力拆成独立技能之后，每个技能有自己清晰的职责边界、自己的输入输出契约、自己的测试用例。调度层只负责"什么时候调用哪个技能"，不关心技能内部怎么实现。这样带来的收益是连锁的：测试可以针对单个技能做，改一个技能不会影响别的；技能可以在不同项目间直接复用；提示词的复杂度被分散到各个技能内部，每个技能的提示词都短而聚焦，模型遵循度自然就上去了。我自己的经验是，当一个智能体的能力超过五个之后，技能化拆解带来的维护性提升会迅速超过拆解本身带来的复杂度。也就是说，前期多花的那点架构成本，很快就能回本。2.3 一个判断标准：什么时候该拆不是所有项目都值得上技能化架构。我的判断标准很简单：如果你发现自己在反复修改同一段提示词，而且每次修改都要重新验证一堆不相关的功能，那就该拆了。反过来，如果只是一个单一用途的小工具，比如"把这段文字翻译成英文"，那完全没必要拆，一个函数调用就够了。拆解的粒度也有讲究。太粗，等于没拆；太细，调度开销会吃掉收益。一个比较实用的经验是：一个技能应该对应一个"人一眼能说清楚它干什么"的职责。比如"从网页提取正文""把长文切成段落""给段落生成摘要"是三个技能，而"处理文档"就是一个太粗的职责。3. 技能单元的设计：接口、状态与边界3.1 每个技能都应该有明确的输入输出契约设计技能时，最容易犯的错误是让技能的输入输出变得模糊。比如一个"搜索"技能，输入是"一个字符串"，输出是"一些结果"——这种定义在真实系统里会立刻出问题：字符串是查询词还是自然语言问题？结果是列表还是文本？包含哪些字段？我的做法是给每个技能定义一份显式的契约，用类似下面这样的结构描述：# 技能契约示例（伪代码，描述结构而非具体实现） skill_contract = { "name": "extract_article", "description": "从一段HTML中提取正文内容", "input_schema": { "html": "string, 必填, 原始HTML", "url": "string, 可选, 用于解析相对链接" }, "output_schema": { "title": "string", "content": "string", "links": "list[string]" }, "failure_modes": ["html为空", "无法识别正文区域"] }这份契约的价值在于，它让调度层和技能实现之间有了一个稳定的约定。调度层不需要知道技能内部是用正则还是用模型，只需要知道"给它这些，它会还我那些"。这也是后面做自动化编排和错误处理的基础。3.2 状态传递：技能之间怎么"对话"技能是独立的，但任务是有前后依赖的。比如"提取正文"之后要"切分段落"，切分需要用到提取的结果。这个结果怎么传？有两种常见模式。一种是显式数据流：调度层维护一个共享的上下文对象，每个技能从里面读自己需要的字段，写自己产出的字段。这种方式清晰、可追踪，适合流程相对固定的场景。另一种是消息传递：技能之间通过消息队列通信，适合异步、并发的场景。对于大多数智能体应用，我推荐显式数据流，因为它更容易调试。你可以随时打印出上下文对象，看到每一步之后系统"知道"了什么。消息传递虽然灵活，但排查问题时链路会拉得很长。这里有个细节值得注意：上下文对象不要无限增长。如果每个技能都把原始输入和中间结果全塞进去，上下文会迅速膨胀，既浪费 token 又干扰模型。我的做法是给上下文定义明确的字段，技能只写自己负责的字段，中间产物用完就丢。3.3 边界处理：技能失败时谁来兜底技能失败是常态，不是异常。网络会抖、模型会抽风、输入会不符合预期。所以每个技能都必须定义清楚自己的失败模式，以及失败后应该怎么办。我一般把失败分成三类：可重试失败（比如临时网络问题）、可降级失败（比如某个数据源挂了，可以用备用源）、不可恢复失败（比如输入格式完全不对）。调度层根据失败类型决定是重试、降级还是直接上报。这里有个反直觉的经验：不要让技能自己决定要不要重试。技能应该只负责报告"我失败了，原因是X"，重试策略交给调度层统一管理。否则每个技能都自己重试，重试次数会叠加，一个请求可能触发几十次调用，把下游打挂。4. 调度层：让技能真正"活"起来的那一层4.1 调度层的核心职责技能本身只是静态的能力单元，真正让它们协同工作的是调度层。调度层要回答三个问题：当前任务需要哪些技能？按什么顺序调用？调用结果怎么处理？最简单的调度是硬编码的流水线：先调 A，再调 B，再调 C。这种方式在流程固定的场景下完全够用，而且可预测性最强。但智能体的价值恰恰在于处理不确定的任务，所以更常见的是基于模型决策的动态调度：把可用技能的描述（注意，只是描述，不是实现）提供给模型，让模型根据当前任务决定下一步调用哪个技能。这两种方式不是对立的。我的实践是混合调度：主干流程用硬编码保证稳定性，分支决策交给模型。比如"提取正文→切分段落"是固定的，但"切分之后是生成摘要还是提取关键词"可以根据用户意图动态决定。4.2 技能描述怎么写才能让模型选对动态调度的效果，几乎完全取决于技能描述的质量。模型是根据描述来决定调用哪个技能的，描述写得含糊，模型就会选错。写技能描述有几个要点。第一，说清楚"什么时候用"比"它是什么"更重要。比如"extract_article"这个技能，描述里要写"当用户提供了一段网页HTML，需要获取其中的正文文字时使用"，而不是只写"提取文章"。第二，明确排除条件。如果两个技能容易混淆，就在描述里写清楚边界，比如"如果输入已经是纯文本，不要用这个技能，直接用 split_paragraphs"。第三，描述要短。每个技能的描述控制在两三句话以内，因为所有技能的描述会一起进入模型的上下文，描述太长会挤占空间。我见过有人给每个技能写一大段说明，结果十几个技能加起来几千字，模型反而更容易选错。4.3 一个容易忽略的问题：技能数量与选择准确率的关系这里有个实测出来的规律：当可选技能超过十个之后，模型的选择准确率会明显下降。这不是模型的问题，而是人类自己面对十几个选项时也会犹豫。解决办法是分层组织。把技能按领域分组，先让模型选组，再在组内选技能。比如先分"文本处理""数据查询""文件操作"三组，模型先判断任务属于哪组，再在组内做细选。这样每一层的选项都控制在个位数，准确率会回升。另一个办法是动态裁剪。根据当前上下文，只把相关的技能暴露给模型。比如当前在处理一个纯文本任务，那所有跟文件、网络相关的技能就不需要出现在选项里。这需要调度层维护一套技能与场景的映射关系，前期有点工作量，但长期收益很大。5. 把技能串起来：编排、复用与版本管理5.1 编排模式：串行、并行与条件分支技能编排有三种基本模式，理解它们的适用场景能帮你少走弯路。串行是最常见的：A 的输出是 B 的输入，B 的输出是 C 的输入。适合有严格依赖关系的流程。并行适合相互独立的子任务，比如同时从三个数据源拉取信息，最后合并。并行能显著降低延迟，但要注意合并时的冲突处理。条件分支适合根据中间结果决定后续路径，比如"如果提取到的正文长度小于阈值，就走'提示用户内容过短'的分支"。实际项目里这三种模式往往是嵌套的。我的建议是先用串行把流程跑通，再针对明显的性能瓶颈做并行化。一上来就设计复杂的并行编排，调试成本会高得离谱。5.2 技能复用：怎么避免"复制粘贴式复用"技能复用的最大敌人是"看起来一样但其实不一样"。你在 A 项目里写了个"总结文档"技能，B 项目也需要总结，但 B 的总结要求更简短、更口语化。这时候直接复制一份改改，短期最省事，长期就是两份要各自维护的代码。更好的做法是把可变部分参数化。总结技能接受一个"风格"参数，A 项目传"正式"，B 项目传"口语"。这样技能只有一份，差异通过配置表达。当然，参数化也有度，如果参数多到十几个，说明这个技能承担了太多职责，该拆了。判断标准是：如果两个使用场景的差异可以用一两个参数表达，就参数化；如果需要改技能内部逻辑，就拆成两个技能。5.3 版本管理：技能升级时怎么不炸掉老流程技能是会演进的。今天"提取正文"只返回纯文本，明天可能要加上图片链接。如果直接改，所有依赖它的流程都可能受影响。我的做法是给技能加版本号，并且默认保持向后兼容。新增字段可以，但不要删字段、不要改字段含义。如果确实需要破坏性变更，就发一个新版本，老流程继续用老版本，新流程用新版本，给迁移留出时间窗口。这套做法借鉴的是 API 版本管理的思路，用在技能上同样有效。关键是要在调度层记录每个流程依赖的技能版本，这样升级时能清楚知道影响范围。6. 实测中踩过的坑与排查思路6.1 技能"看起来被调用了"但结果不对这是最让人头疼的一类问题：日志显示技能被调用了，参数也对，但返回结果就是不符合预期。排查这类问题，我的顺序是先看输入，再看技能内部，最后看输出解析。先确认输入：调度层传给技能的参数，和技能实际收到的参数，是不是一致的？中间有没有被序列化/反序列化搞坏？我遇到过一次，上下文对象里的一个列表在传递过程中被转成了字符串，技能收到的是字符串而不是列表，行为自然不对。再看技能内部：如果技能内部也调用了模型，那就要检查模型这次是不是"发挥失常"。同一个提示词，模型在不同时候的输出可能不同。这时候要看技能有没有对模型输出做校验，校验失败时有没有明确的错误信息。最后看输出解析：技能返回的结构，和调度层期望的结构是否匹配？字段名有没有拼错？类型对不对？这类问题在动态语言里特别常见，因为不会在编译期报错。6.2 上下文膨胀导致的"越跑越慢"项目跑一段时间后，你会发现响应越来越慢，token 消耗越来越高。八成是上下文在膨胀。排查方法是在每个技能调用前后打印上下文的字段和大小。你会看到某些字段在无限增长，比如"历史消息"列表从来没被清理过，或者某个技能每次都往上下文里追加而不是覆盖。解决办法是给上下文定义生命周期。哪些字段是全局的（整个任务期间保留），哪些是临时的（用完即弃），哪些是滚动的（只保留最近 N 条）。这个设计要在架构阶段就想清楚，后期补会很痛苦。6.3 技能之间的"隐性耦合"技能本该是独立的，但实际中经常出现隐性耦合。比如技能 B 假设技能 A 一定在它之前运行过，所以直接读 A 写的字段。如果某天流程调整，A 没跑，B 就崩了。这种耦合不会在代码里显式体现，所以特别隐蔽。我的应对办法是让每个技能显式声明自己的前置依赖，调度层在调用前检查依赖是否满足。不满足就报错，而不是让技能在运行时莫名其妙地失败。另一个办法是给技能写独立的测试，测试时只提供该技能需要的输入，不依赖其他技能。如果这个测试跑不通，说明技能有隐性依赖。7. 从能跑到好用：几个提升稳定性的实操技巧7.1 给技能加"自检"环节技能执行完，不要直接返回结果，先做一次自检。自检的内容包括：输出结构是否符合契约、关键字段是否为空、数值是否在合理范围内。自检不通过就按失败处理，而不是把脏数据传给下游。这个环节看起来多余，但能拦住大量"看起来成功其实失败"的情况。我见过太多因为一个空字段一路传到底、最后在用户面前才暴露的问题。7.2 用"影子运行"验证新技能新技能上线前，可以先让它"影子运行"：在真实流程里调用它，但不用它的结果，只记录它的输出，和现有方案对比。跑一段时间，确认它的表现稳定、结果合理，再正式切换。这种方式比单元测试更接近真实场景，又不会影响线上。代价是要多维护一套对比逻辑，但对于核心技能，这个投入是值得的。7.3 给调度决策留"后悔药"动态调度下，模型可能选错技能。如果选错了就直接执行，可能产生副作用（比如发了一封不该发的邮件）。我的做法是对高风险技能加确认环节：调度层决定调用后，先不执行，而是把"打算调用哪个技能、传什么参数"展示出来，确认无误再执行。这个确认可以是人工的，也可以是自动的规则校验。关键是给系统一个"反悔"的机会，而不是一路执行到底。7.4 记录完整的调用链路每个任务从开始到结束，完整记录调用了哪些技能、每个技能的输入输出、耗时、成功失败。这份链路日志在排查问题时价值极高，因为你能完整复现一次任务的执行过程。日志的粒度要平衡。太粗，排查时信息不够；太细，日志量大到没法看。我的经验是记录技能的输入输出摘要和关键中间状态，完整数据按需采样。8. 关于 agent-skills 这套思路，我自己的几点体会做了几个基于技能化架构的智能体项目之后，我最大的体会是：这套思路的价值不在于技术有多新，而在于它强迫你把"智能体到底能做什么"这件事想清楚。在单体提示词时代，很多能力边界是模糊的，因为反正都塞在一起。一旦要拆成技能，你就必须回答"这个技能的输入是什么、输出是什么、什么时候用、失败了怎么办"——这些问题想清楚了，系统自然就稳了。第二个体会是不要过度设计。我见过有人一上来就设计了一套复杂的技能注册、发现、编排框架，结果项目本身只有三个技能。技能化的收益来自规模，技能少的时候，简单直接反而更好。先跑起来，等能力多到管不过来了再拆，这个顺序不能反。第三个体会是技能描述的质量决定一切。动态调度下，模型选技能的依据就是描述。描述写得好，系统就聪明；描述写得烂，再好的架构也白搭。花在打磨技能描述上的时间，回报率比花在优化调度算法上高得多。最后一个，也是我觉得最容易被忽略的：给技能留出"我不知道"的出口。很多技能被设计成"必须返回一个结果"，于是模型在不确定的时候也会硬编一个答案出来。更好的设计是允许技能返回"无法处理"，让调度层去决定是换个技能、还是向用户澄清。承认不知道，比编一个错误答案有价值得多。