1. 从“agent-skills”这个命名说起：它到底在解决什么问题
第一次看到agent-skills这个命名，我的直觉是：这大概率不是一个具体的业务系统，而是一套围绕“智能体能力”做抽象、封装和复用的工程方案。事实也确实如此。在当前的智能体开发实践中，大家普遍面临一个尴尬的局面——模型本身越来越强，但真正落地到具体任务时，表现却参差不齐。原因不在于模型不够聪明，而在于它缺少一套可组合、可复用、可验证的“技能层”。
agent-skills要解决的，正是这个“技能层”的缺失问题。你可以把它理解成一个智能体的“技能库”或者“能力中间件”：把那些高频、通用、有明确输入输出的操作，从散落在各个提示词和工具调用里的碎片逻辑，提炼成一个个独立、可测试、可编排的技能单元。这样一来，智能体在面对复杂任务时，不再是靠一段超长提示词硬扛，而是像搭积木一样，按需调用不同的技能模块。
这个思路的价值在于三点。第一，可维护性。当某个技能的行为需要调整时，你只需要改那一个技能，而不是去翻几百行的提示词。第二，可测试性。每个技能都有明确的输入输出契约，可以单独写测试用例，这在智能体开发里是极其稀缺的。第三，可组合性。技能之间可以串联、并联、条件分支，形成更复杂的工作流，而不需要每次都从零设计。
适合读这篇内容的人，我大致分三类：一是正在做智能体应用开发、被提示词维护折磨的工程师；二是想给自己的产品加上“智能体能力”但不知道从哪下手的开发者；三是对智能体架构感兴趣、想了解工程化落地思路的技术爱好者。不管你是哪一类，接下来的内容都会围绕“怎么设计、怎么实现、怎么避坑”展开，尽量把我在实际项目里踩过的坑和总结的经验都摊开讲。
2. 技能抽象的核心设计：为什么不能把技能写成函数那么简单
2.1 技能不是函数，它比函数多了“语义”和“容错”
很多人第一反应是：技能不就是函数吗？输入参数，返回结果，有什么难的。我一开始也这么想，直到真正动手才发现，智能体技能和普通函数有本质区别。
普通函数的调用方是代码，参数类型、数量、顺序都是确定的，传错了直接报错。但智能体技能的调用方是模型，模型是根据自然语言描述来决定调用哪个技能、传什么参数的。这意味着技能必须自带“语义描述”，让模型能理解它是干什么的、什么时候该用、参数该怎么填。同时，模型传参不可能像代码那么精确，可能多传、少传、类型不对、格式不对，所以技能内部必须有容错和参数归一化逻辑。
我在一个模拟项目里做过对比：把同一个“查询天气”功能分别写成普通函数和智能体技能。普通函数版本，模型调用时经常因为参数名不匹配或者格式不对而失败；技能版本加上语义描述和参数校验后，成功率从不到六成提升到了九成以上。这个差距就是“语义层”带来的。
2.2 技能描述的三层结构：意图、参数、约束
一个设计良好的技能描述，我习惯把它拆成三层。
第一层是意图描述，用一两句自然语言说清楚这个技能解决什么问题。比如“根据城市名称查询当前天气状况”，而不是“调用天气API”。前者是模型能理解的语义，后者是工程实现细节，模型不关心也不该关心。
第二层是参数定义，每个参数要有名称、类型、是否必填、描述、默认值。这里有个容易忽略的点：参数的描述要写得足够具体，最好带上示例。比如“城市名称，如‘北京’、‘上海’”，比只写“城市名称”效果好很多。模型在填参时，示例能显著降低歧义。
第三层是约束与边界，说明这个技能在什么情况下不适用、有什么限制。比如“仅支持中国主要城市，不支持乡镇级别查询”。这一层很多人会省略，但实际用下来，它能有效减少模型在边界情况下的误调用。
2.3 技能注册与发现机制：让模型知道“有哪些技能可用”
技能写好了，还得让模型知道它们的存在。这就需要一个注册与发现机制。最简单的做法是在系统提示词里把所有技能列出来，但技能一多，提示词就会爆炸，而且模型在长列表里选择时准确率会下降。
我试过几种方案，最后比较稳定的是“分层注册”：把技能按领域分组，先让模型选领域，再在领域内选具体技能。比如先选“信息查询”领域，再选“天气查询”技能。这样每层的候选数量都控制在合理范围内，选择准确率明显提升。
另一种方案是“向量检索式发现”：把技能描述向量化，根据当前任务语义检索最相关的几个技能，再让模型从中选择。这种方式适合技能数量很大（几百个以上）的场景，但实现复杂度也更高，需要维护向量库和检索逻辑。对于大多数中小规模项目，分层注册已经够用了。
3. 技能执行引擎的实现细节：从调用到返回的完整链路
3.1 参数解析与校验：模型传参不可靠，必须做归一化
模型传过来的参数，你不能假设它是干净的。我遇到过各种情况：数字传成字符串、布尔值传成“true”字符串、数组传成逗号分隔的字符串、参数名大小写不一致、甚至把参数塞到嵌套对象里。所以技能执行引擎的第一步，就是参数解析与校验。
我的做法是定义一个参数规范，每个参数有类型、是否必填、默认值、以及一个归一化函数。引擎拿到原始参数后，先按规范做类型转换和格式清洗，再校验必填项和取值范围。校验不通过时，不是直接报错，而是返回一个结构化的错误信息，让模型知道哪里错了、该怎么改。这样模型有机会自我修正，重新调用。
这里有个经验：错误信息要写得对模型友好。比如“参数 city 缺失，请提供城市名称”比“KeyError: city”有用得多。模型看到前者能理解并补上，看到后者大概率就懵了。
3.2 执行隔离与超时控制：一个技能卡死不能拖垮整个智能体
技能执行可能涉及外部调用、计算、IO操作，任何一个环节都可能变慢或卡死。如果不做隔离和超时控制，一个技能卡住，整个智能体就挂在那里了。
我的做法是每个技能调用都放在独立的执行上下文里，设置超时时间。超时后强制中断，返回超时错误，让智能体决定是重试、换技能还是放弃。超时时间根据技能类型设定：纯计算类可以短一些，比如5秒；涉及外部调用的可以长一些，比如30秒。这个值需要根据实际场景调，没有万能数字。
另外，对于可能产生副作用的技能（比如写文件、发请求），要做好幂等设计或者补偿机制。模型可能会因为超时重试而重复调用，如果技能不幂等，就会出问题。
3.3 结果格式化：返回给模型的内容要“可读”且“可续”
技能执行完，结果怎么返回给模型，也是有讲究的。直接返回原始JSON，模型可能抓不住重点；返回太长，又会占用上下文。我的经验是返回一个“摘要+详情”的结构：摘要用自然语言概括核心结果，详情保留结构化数据供后续技能使用。
比如天气查询技能，摘要可以是“北京当前晴，气温25摄氏度，湿度40%”，详情里再放完整的天气数据。这样模型在决策时看摘要就够了，需要精确数据时再取详情。这种分层返回方式，在复杂工作流里特别有用，能有效控制上下文长度。
4. 技能编排与工作流：单个技能不够用，怎么串起来
4.1 串行编排：前一个技能的输出是后一个的输入
最简单的编排是串行：技能A执行完，结果传给技能B，B再传给C。这种模式适合有明确依赖关系的任务。实现上，需要一个上下文对象来传递中间结果，每个技能从上下文里取自己需要的参数，执行完再把结果写回上下文。
这里有个坑：上下文里的键名要统一规范，否则技能之间对不上。我建议用“技能名.输出名”的格式，比如“weather_query.result”，这样来源清晰，不容易冲突。
4.2 条件分支与循环：让智能体自己决定下一步
更复杂的场景需要条件分支和循环。比如“如果查询结果为空，就换一个技能重试；如果重试三次还失败，就报错退出”。这种逻辑如果写死在代码里，就失去了智能体的灵活性。更好的做法是把决策权交给模型：把当前状态和可用技能告诉模型，让模型决定下一步调用哪个技能。
但这样也有风险：模型可能陷入死循环，或者做出不合理的决策。所以需要加一些保护机制，比如最大步数限制、重复调用检测、以及关键节点的强制校验。我在一个模拟项目里设置了最大20步的限制，超过就强制终止并返回当前结果，实际用下来很少触发，但有了这个兜底心里踏实。
4.3 并行编排：独立技能同时执行，缩短总耗时
有些技能之间没有依赖关系，可以并行执行。比如同时查询多个城市的数据，或者同时调用多个信息源做交叉验证。并行执行能显著缩短总耗时，但实现上要注意结果聚合和错误处理。
结果聚合要定义好合并策略：是取第一个成功的结果，还是全部返回，还是做加权融合。错误处理要决定：一个技能失败了，是整体失败，还是忽略失败继续等其他技能。这些策略要根据业务场景来定，没有标准答案。
5. 实测中的坑与应对：那些文档里不会写的经验
5.1 技能描述写得太“工程化”，模型理解不了
我见过很多技能描述，写的是“调用XX接口，传入YY参数，返回ZZ字段”。这种描述对人来说很清楚，但对模型来说，它不知道这个技能在业务上意味着什么。模型需要的是“这个技能能帮我完成什么任务”，而不是“这个技能内部怎么实现”。
改法很简单：把描述从“实现视角”切换到“任务视角”。比如“调用天气API获取数据”改成“查询指定城市的当前天气状况，包括温度、湿度、天气现象”。后者模型一看就知道什么时候该用。
5.2 参数默认值设得太随意，导致模型“偷懒”
参数有默认值本来是好事，能减少模型填参负担。但如果默认值设得不合理，模型会倾向于不填参数，直接用默认值，导致结果不符合预期。比如一个“查询订单”技能，时间范围默认是“最近7天”，模型可能就不填时间，永远只查最近7天。
我的做法是：对于关键参数，不设默认值，强制模型填写；对于次要参数，设默认值但要在描述里说明“不填则使用默认值XX”。这样模型知道哪些参数重要、哪些可以省略。
5.3 技能粒度太粗或太细，都会出问题
技能粒度是个需要反复调的事。太粗，一个技能干太多事，模型难以准确调用，而且复用性差；太细，技能数量爆炸，模型选择困难，而且编排复杂度上升。
我的经验是：一个技能对应一个“原子操作”，但这个“原子”是业务语义上的原子，不是技术实现上的原子。比如“发送邮件”是一个原子操作，不需要再拆成“填写收件人”“填写主题”“填写正文”。但“处理订单”就太粗了，应该拆成“查询订单”“取消订单”“修改订单”等。
5.4 错误处理不能只靠模型“自觉”
模型在面对错误时，有时候会“假装没看到”继续往下走，有时候会反复重试同一个失败的操作。所以错误处理不能完全交给模型，引擎层面要有强制机制。比如连续两次调用同一个技能都失败，就禁止再次调用该技能；或者关键技能失败时，直接终止流程并返回错误。
6. 技能复用与版本管理：让技能库能持续演进
6.1 技能版本化：改了技能，不能影响已有工作流
技能一旦被多个工作流引用，就不能随便改。改了一个参数名，可能好几个工作流就挂了。所以技能需要版本管理。我的做法是每个技能有版本号，工作流引用技能时指定版本。新版本发布后，旧版本继续保留一段时间，等所有工作流都迁移完再下线。
版本号用语义化版本：主版本号变表示不兼容的改动，次版本号变表示新增功能但兼容，修订号变表示修复bug。这样引用方一看版本号就知道要不要适配。
6.2 技能组合的复用：把常用编排也封装成“复合技能”
单个技能可以复用，技能组合也可以复用。比如“查询天气并推荐穿衣”这个组合，可能在多个场景里都会用到。与其每次都重新编排，不如把它封装成一个“复合技能”，对外暴露一个统一的接口，内部还是调用那些原子技能。
复合技能的好处是降低了编排的复杂度，坏处是灵活性降低。所以我的原则是：高频且稳定的组合才封装成复合技能，低频或易变的组合保持原子编排。
6.3 技能库的测试与回归：每次改动都要跑一遍全量用例
技能库大了之后，改一个技能可能影响其他技能。所以需要一套测试与回归机制。每个技能都要有单元测试，覆盖正常情况、边界情况、异常情况。每次技能变更后，跑一遍全量测试，确保没有破坏已有功能。
测试用例的输入输出要固化下来，作为回归基线。新版本如果输出和基线不一致，要么是bug，要么是有意变更，都需要人工确认。这套机制在技能数量超过二三十个之后，就变得非常必要了。
7. 从零搭建一个最小可用技能系统的实操路径
7.1 第一步：定义技能规范，哪怕只有三个技能
不要一上来就追求大而全。先定义好技能规范，然后写三个最简单的技能，把整条链路跑通。比如“获取当前时间”“计算两个数之和”“返回一句问候语”。这三个技能足够验证注册、发现、调用、返回的完整流程。
规范要包括：技能描述格式、参数定义格式、返回值格式、错误格式。这些格式一旦定下来，后面所有技能都按这个来，一致性就有了保障。
7.2 第二步：实现执行引擎，重点做参数校验和超时
执行引擎是核心，但第一版不需要太复杂。重点做两件事：参数校验和超时控制。参数校验保证模型传参不规范时能给出友好错误；超时控制保证一个技能卡死不会拖垮全局。这两件事做好了，系统的基本稳定性就有了。
7.3 第三步：接入模型，用真实任务验证
引擎跑通后，接入模型做真实任务验证。从简单任务开始，比如“现在几点了”“帮我算一下35加47等于多少”。观察模型是否能正确选择技能、正确填参、正确处理返回结果。有问题就调整技能描述或参数定义，反复迭代。
这个阶段最容易发现技能描述的问题。模型选错技能，往往是描述不够清晰；模型填错参数，往往是参数描述不够具体。根据实际表现来优化，比凭空设计有效得多。
7.4 第四步：逐步增加技能，同步补充测试
验证通过后，逐步增加技能。每增加一个技能，同步补充测试用例。技能数量到十个左右时，就要考虑分层注册了；到二三十个时，就要考虑版本管理和回归测试了。不要等到问题爆发才补，那时候成本会高很多。
8. 技能系统的性能与成本考量：别让技能调用变成烧钱机器
8.1 技能调用的token开销：描述越长，成本越高
每个技能的描述都会占用提示词的token。技能多了之后，光技能描述就可能吃掉几千token。每次调用都要带上这些描述，成本会累积。所以技能描述要精炼，去掉冗余信息，保留核心语义。
我的做法是：技能描述控制在50字以内，参数描述控制在20字以内。如果确实需要更多说明，放到单独的文档里，提示词里只放摘要。这样能在保证模型理解的前提下，尽量降低token开销。
8.2 缓存与复用：相同调用不要重复执行
有些技能调用是幂等的，相同参数的结果可以缓存。比如“查询城市信息”，同一个城市查多次，结果是一样的。加一层缓存，能显著减少外部调用和计算开销。
缓存的key用技能名加参数哈希，value是执行结果。缓存有效期根据数据变化频率设定：变化快的设短一些，变化慢的设长一些。缓存命中时直接返回，不走执行引擎，既快又省。
8.3 批量处理：能合并的调用就合并
有些场景下，多个技能调用可以合并成一次。比如同时查询多个城市天气，与其调用五次“天气查询”技能，不如调用一次“批量天气查询”技能，传入城市列表。这样减少了调用次数，也减少了模型决策的轮次，整体效率更高。
批量技能的参数设计要注意：输入是列表，输出也是列表，且顺序要对应。错误处理要支持部分成功：某些城市查询失败，不影响其他城市返回结果。
9. 智能体技能化的边界：什么该做成技能，什么不该
9.1 适合做成技能的场景：高频、稳定、有明确契约
不是所有操作都适合做成技能。适合做成技能的，通常满足三个条件：高频使用、行为稳定、输入输出有明确契约。比如“查询数据库”“发送通知”“格式转换”这类操作，做成技能后复用价值很高。
反过来，一次性、易变、契约模糊的操作，做成技能反而增加维护负担。比如某个特定活动的临时逻辑，做完就完了，没必要封装成技能。
9.2 不适合做成技能的场景：需要复杂推理或主观判断
有些任务需要复杂推理或主观判断，比如“写一篇营销文案”“评估一段代码的质量”。这类任务很难定义明确的输入输出契约，也不容易测试。对于这类任务，更适合用提示词模板或者专门的微调模型，而不是技能。
技能的本质是“确定性的能力封装”，它擅长处理那些逻辑明确、结果可预期的事情。把不确定的事情硬塞进技能框架，只会让系统变得脆弱。
9.3 技能与提示词的边界：能确定就别用提示词
在实际项目里，技能和提示词往往是混用的。我的原则是：能用技能解决的，就别用提示词。因为技能可测试、可复用、可版本管理，而提示词是黑盒，改一处可能影响多处。
比如“从文本里提取日期”这个任务，用提示词也能做，但结果不稳定。做成技能后，可以用正则加规则引擎，结果确定且可测试。模型只需要决定“什么时候调用这个技能”，不需要自己去做提取，整体可靠性就上去了。
10. 我在实际项目里总结的几条硬经验
第一条，技能描述是给模型看的，不是给人看的。写描述的时候，要站在模型的角度想：它看到这句话，能不能理解这个技能是干什么的、什么时候该用。人觉得清楚不够，模型觉得清楚才行。
第二条，参数校验要严，错误提示要软。校验规则可以严格，但返回给模型的错误信息要友好、可操作。模型看到“参数格式错误”可能不知道怎么改，看到“日期格式应为YYYY-MM-DD，如2024-01-15”就知道怎么改了。
第三条，技能数量超过二十个，就必须做分层或检索。不然模型在长列表里选择，准确率会明显下降。分层注册是最简单的方案，向量检索适合更大规模，但实现成本更高。
第四条，每个技能都要有测试，没有测试的技能等于没有技能。技能的行为必须可验证，否则改一处坏一处，最后没人敢动。测试用例要覆盖正常、边界、异常三种情况，每次变更后全量回归。
第五条，技能系统不是越复杂越好，够用就行。我见过一些项目，技能框架做得极其复杂，支持各种编排模式、各种高级特性，结果实际用到的不到两成，维护成本却很高。从最小可用开始，按需演进，比一开始就设计大框架更靠谱。
最后再分享一个小技巧：如果你不确定一个操作该不该做成技能，就先把它写成提示词，观察它在实际任务里被调用的频率和稳定性。如果高频且稳定，再封装成技能；如果低频或易变，就继续用提示词。让实际需求驱动技能化，而不是为了技能化而技能化。
