我一直觉得，AI代理能不能从“玩具”变成“生产工具”，关键往往不在模型本身多聪明，而在它手里到底有多少“趁手的家伙”。模型是大脑，技能就是手脚。拿不到数据、调不动API、不知道该按什么流程办事，再强的推理能力也施展不开。这篇就围绕agent-skills这个主题，把我自己从零开始搭建代理技能体系的过程、踩过的坑、以及最后沉淀下来的方法论做一次完整复盘。不管你是刚接触代理开发，还是已经在自己项目里折腾过一阵子，这里面的大部分经验应该都能直接用上。
1. 为什么“技能”才是代理真正落地的胜负手
一开始我做代理项目时，思路特别单纯：塞给一个大模型足够长的系统提示词，把业务规则全写进去，再给它接上几个函数，感觉就能跑通了。结果真正放到真实场景里，立刻原形毕露。提示词写得再花哨，模型还是会在中间步骤上犯迷糊；函数接口堆得再多，遇到没见过的边界情况就抓瞎。后来我才意识到，问题出在我一直把注意力放在“让模型变得更聪明”上，却忽略了“让模型有更多可复用的能力”。
所谓agent-skills，本质就是把代理在完成某一类任务时需要用到的操作流程、调用工具的方法、以及处理异常的经验，拆解成一个个独立的、可组合的、能被模型按需调用的技能模块。一个技能不是简单封装一个函数，而是“指令模板+执行逻辑+参数约束+结果处理”的集合。类比一下：函数是螺丝刀，技能是“换一颗螺丝的完整操作规范”。螺丝刀告诉你哪个方向拧，技能告诉你先拆哪颗、再动哪颗、遇到滑牙了怎么办。
我最初在这个环节上的设计失误，是试图让一个“全能技能”覆盖所有场景。比如我写过一个所谓的“数据获取技能”，既想让它处理文件读取，又想让它接管数据库查询，还想让它包揽网页抓取。结果每次调用都要传入七八个参数，模型根本搞不清楚该填什么。更麻烦的是，出错时我根本定位不了到底哪一段逻辑出了问题。后来把大技能拆成“读配置文件”“查数据库表结构”“抓取指定URL正文”这些小技能之后，整个代理的稳定性和可维护性一下就上来了。从此我把“单一职责”当成了拆技能的铁律，宁可多建几个模块，也别让一个模块承担多重模糊使命。
2. 技能定义的最小可用结构：从任务描述到代码实现
第一步就是为技能建立统一的数据结构。我采用了一套相当精简的定义方式，并且在实际项目中反复调整后，发现它确实够用。
技能定义一般包含四块核心信息：技能名称、技能描述、参数清单、执行逻辑。技能名称必须做到“一看名字就知道它管什么事”，比如“读取MySQL表结构”就比“数据库工具”“数据服务”清晰得多。技能描述要写清“该技能适合处理什么场景、不适合处理什么场景”，这一块直接决定了模型会不会在错误的地方调用它。参数清单则不仅包括每个参数的类型和含义，还要写清楚参数之间的依赖关系，比如哪些参数互斥、哪些必须同时出现。
比较容易被忽视的是执行逻辑。它不是让你把Python代码都塞进这层，而是指“当技能被选中后，代理应该如何一步步调用底层能力”。举个例子，我写过一个“批量重命名服务器文件”的技能，它的执行逻辑不是简单地调用一个rename函数，而是先校验目标路径是否存在、再确认是否有写入权限、然后模拟执行一遍返回影响文件清单、获得确认后才真正执行。这套逻辑写在技能定义里，模型在执行时就会自动按顺序走，而不是直接莽撞地发出修改操作。
这里有个关键设计：技能描述应该是由模型可读的，而不是给人看的。我踩过一个大坑，最初我用说明文档的语气写技能描述，比如“本技能用于获取系统当前时间”。模型拿到这种描述后，经常在根本不需要时间判断的场景里莫名其妙去调用时间技能。后来我改成“仅在需要向用户展示当前日期、或计算倒计时等情况时调用，任何‘根据当前时间推测’的场景都不要用这个技能”，误调率立刻降了四成。写技能描述时，你要站在模型的视角去思考“这句话会不会让我联想起某个不该调用它的场景”，而不是站在开发者视角去解释“这个功能多有用”。
2.1 参数约束设计的三个层次
参数约束是我整个技能体系里最薄弱的起点，现在则是受益最大的改进点。我给参数约束分成了三层，每层解决不同纬度的问题。
第一层是“类型和范围约束”。参数名、类型、取值范围、是否必填，这层最容易实现，直接在定义时用类型标注和枚举值就能卡住。第二层是“语义约束”。这层解决的问题是“参数本身合法，但组合起来不合理”。举个例子，一个“查询订单”技能里有两个参数，“按用户ID查”和“按订单号查”是两种查询模式，但模型经常两个都填上，导致后台根本不知道该走哪个索引。语义约束的做法是在技能描述里写明“本技能只支持单一查询维度，如果同时给了两个不同维度的参数，请只保留一个并明确告知调用方”。这层约束依靠的是描述语言的精确性，而不是硬编码。第三层是“外部环境约束”。有些参数执行前必须符合外部系统的状态，比如文件技能要求目标文件不能被占用。这一层我把校验逻辑写进执行代码，一旦检测失败就返回结构化错误码，同时附上给模型看的修正建议，让它下一轮能自动调整调用方式。
参数约束不是设计得越严格越好。我最初希望把所有可能的风险都堵死在参数校验里，结果模型在真实对话里经常因为找不到“完全符合规则”的参数组合而反复询问用户，体验极其拖沓。后来我调整策略：凡是可由模型自行推导的缺失参数，都允许默认值或启发式填充；凡是可能引起不可逆操作的参数，才必须显式明确。比如删除任务ID一定要强制传入，而像“是否显示日志”“超时时间”这类非关键项直接给默认值就行。
2.2 技能注册表：让模型知道“你会什么”
模型要能正确使用技能，前提是它知道“你有哪些技能可以用”。因此技能注册表的设计直接决定调用准确率。我刚开始做的时候，就是把所有技能描述一股脑塞进系统提示词里，结果提示词越来越长，模型反而出现了注意力分散问题，关键技能反而被淹没。
后来换成了分层注册表的思路。第一层是全局技能索引，只放技能名称和一句话简介，让模型形成一个大致的“目录感”。第二层是详细技能卡片，平时不进入上下文，只在其被初步选中时才由调度逻辑把完整定义加载进来。这相当于绕了一圈把“提示词过长”的问题转化成了“按需加载上下文”的问题。实现上我写了一个简单的加载器：模型的回复里如果出现意图调用某个技能的标记，系统就自动把对应技能卡片的完整参数和执行逻辑补充到后续请求里。这个机制跑通之后，上下文长度压力降了将近一半，技能调度准确性也明显提升。
技能注册表还需要一个容易被忽略的字段：技能之间依赖关系。比如“分析日志文件”依赖于“获取日志文件路径”，如果有技能组合场景，注册表里要显式声明顺序和约束。否则模型可能先让代理去分析，却不知道日志路径怎么来，然后就会自己编造一个不存在的路径。我在项目里加过一个“前置技能检查”的辅助函数，在模型发起技能调用时，先扫描它是否已经调用了前置技能，如果没有就自动补一次前置调用，很大程度上减少了这种“跳步”导致的问题。
3. 让调度器学会“什么时候该用哪个技能”
一个代理往往同时挂着几十个技能。如果调度策略不清晰，最常见的两个毛病是：要么模型在低风险场景频繁调用技能，显得很蠢；要么该用技能时它硬凭自己的内部知识凑合回答，显得更蠢。我花了很长时间才摸索出一套还算靠谱的调度权衡机制。
首先要明确一个基本出发点：技能调用不是越多越好，而是越准越好。我最初加技能监控看板时，一看调用次数特别高还挺开心，后来发现一半调用都是无效调用。比如用户问“这个文件多大”，模型愣是调用了一个“运行Shell命令”技能去执行ls -l，完全可以直接根据已有的文件元信息给出答案。后来我在技能描述里统一加了“适用场景和禁用的场景”两个二级标题，并且在调度逻辑中加入一个“最低成本匹配”原则：当多个技能都貌似可以完成任务时，优先选择参数最少、副作用最小、执行速度最快的那一个。这实际上模仿了人做工程决策时的直觉，机器一旦有了这个原则，行为会稳健得多。
调度机制里还有一个容易翻车的点：技能返回结果后，模型是否会自动反思并调整。我遇到过典型的场景：调用“查询库存”技能返回空列表。模型第一次反应是直接告诉用户“没货了”。但我希望它至少能判断一下——是不是参数传错了？是不是门店筛选条件太严格？后来我给技能返回结果附加了一个字段叫“可采取的修正建议”，由技能执行方基于一定的规则生成。比如库存查询空结果时，自动附加“您是否想取消门店筛选条件试试？”。模型看到修正建议后，会自然地形成追问或二次调用，整个交互的智能感立即提升。
这里也要提醒一句：不要指望调度器百分之百正确。我目前能做到的也就是把“关键路径上的调用准确率”控制在可接受范围内。什么样的调用属于关键路径？凡是涉及数据修改、资金变动、不可逆操作，我都在调度逻辑前加了一道显式确认门槛。模型必须先输出“准备调用技能X，参数为Y，影响为Z”的说明，再由外部校验模块决定放行还是拦截。给代理加上这层安全缓冲之后，很多因为模型幻觉引发的误操作都至少在外部被拦住了。
4. 实操案例拆解：一个多技能协同的信息收集代理
光讲概念和设计原则，不太容易有直观感受。我拿一个我自己跑过的案例来说：一个能在内网环境下完成“从多个数据库提取数据、汇总后生成日报”的代理。这个任务如果只靠一个技能硬扛，几乎不可能做好，但它恰好是展示多技能协同的好例子。
拆解下来，这个代理需要至少四类技能。第一类是“数据库连接管理器”，负责连通内网各个数据源，但它并不查具体业务数据，只负责建立连接、做连通性测试、返回连接状态。第二类是“表结构解析器”，输入库名和表名后，输出字段清单、主键和索引。第三类是“业务数据查询器”，依赖第二类的输出结果来完成实际查询，同时需要接收过滤条件、排序逻辑。第四类是“日报模板渲染器”，接收结构化数据后，将其填充进统一的日报模板，输出Markdown或HTML。
这四类技能必须以流水线的方式协作，而不是由模型随机跳来跳去。具体做法是，我在调度逻辑层用一个简单的状态机来定义流转路径：第一步，连接数据库；第二步，解析核心表结构；第三步，按预定查询条件拉取数据；第四步，渲染成日报。代理在执行过程中，每一步完成都会更新任务状态，并检查下一步的前置条件是否满足。如果某一步失败了，它会记录失败原因，尝试按预案降级，比如一个库连不上，就尝试备用只读副本；如果还是失败，就跳过该库并在日报里单独标记“数据缺失”。
有意思的是，这个案例里模型本身几乎不需要什么推理能力，它只需要在每一步按技能描述找到正确的调用入口。真正让整个链路跑顺的，是技能拆得足够干净，以及状态机里各个技能之间的衔接足够明确。这印证了我一直以来的感受：agent-skills的核心价值不是让模型更聪明，而是让模型的每一步行动都被结构化的能力支撑着，每一步都有据可依、有错可返、有方可补。
为了让这个案例更可复现，我把关键调用过程做成了伪代码。实际项目里我用的是类似这种逻辑：
{ "task": "生成每日销售日报", "workflow": [ { "skill": "connect_database", "params": { "env": "prod", "timeout": 10 } }, { "skill": "parse_table_schema", "params": { "table": "order_summary", "db": "analytics" } }, { "skill": "query_business_data", "params": { "fields": ["date", "revenue", "orders"], "filters": { "date": "yesterday" } } }, { "skill": "render_daily_report", "params": { "format": "markdown", "include_missing_data": true } } ], "error_policy": { "connect_database": ["retry_with_readonly", "skip_and_mark_missing"], "query_business_data": ["adjust_filter", "skip_table"] } }这份配置并不是给模型当提示词用的，而是由调度器直接执行的状态机定义。每个步骤的“skill”字段指向技能注册表里的具体卡片，运行时才会加载完整参数和执行函数。这样做最大的好处是：流程调整不需要改模型、改提示词，只需要改这份JSON配置。我后来接新的报表需求时，基本都是复制一份配置改改查询条件和渲染模板就行，开发效率高了不少。
4.1 技能调用过程中的错误处理经验
绕不开的话题就是错误处理。技能执行时出错不是意外，而是常态。我早期的做法是技能出错后直接返回原始错误堆栈，让模型看。结果模型经常被大段异常信息带偏，回复里也开始出现“FileNotFoundError”这种技术名词，用户体验很糟。
后来我规定所有技能返回的错误都必须是三层嵌套结构：第一层是“用户可读信息”，用自然语言描述发生了什么；第二层是“模型可读信息”，说明出错可能原因，并给出下一步动作建议；第三层是“开发者日志”，才是原始异常信息。这个设计落地之后，模型面对错误时的表现好了很多。它不会再把异常堆栈生硬地抛给用户，而且能顺着“模型可读信息”里的建议自动调整调用方式。这个结构强烈推荐给所有做代理技能的人。
再有就是超时问题。代理技能如果长时间不返回，整个对话就会被卡死。我给所有技能的执行函数都加了统一超时控制，并定义了“慢技能”与“快技能”两类。快技能比如读取当前时间、计算器这类，要求500毫秒内返回；慢技能比如批量文件扫描、数据聚合，最多允许30秒，但超过5秒必须返回进度状态。进度状态虽然不是最终结果，却能让模型可以继续跟用户周旋，不至于干等。这个设计来自于我真实踩过的一次事故：某个代理调用了一个耗时的数据导入技能，整整6分钟没有任何反馈，用户以为系统崩了，直接退出了对话。
4.2 如何通过“技能测试集”提升代理表现
很多时候，代理表现不稳，不是因为模型不行，而是技能调用路径没有被充分验证。我后来养成一个习惯：为每个技能配一个“最小测试集”，包含三到五种典型调用场景，每次调整技能定义后跑一遍。这听起来像是软件工程里的单元测试，但和传统单测不一样，测试集更关注“模型是否会在正确的场景下调用技能、并在错误场景下正确拒绝”。
举个例子，我给“获取用户邮箱”技能配的测试集里有这样几条：用户明确提供邮箱时是否调用；用户只提供了手机号时是否主动询问邮箱；用户问“我以前留的哪个邮箱”时是否调取历史记录；用户问“帮我发邮件”时是否同时调用发件技能和收件人查询技能。这些测试不检查代码逻辑，而是检查决策逻辑。跑测试集时，我实际上是模拟真实用户对话，让代理自由发挥，然后人工看它的调用路径是否符合预期。每轮测试后，我都会把暴露出来的问题分类。如果问题出在技能描述不清，就改描述；如果出在参数约束不够，就加约束；如果出在调度顺序不对，就修状态机配置。这套循环做完三轮之后，代理在我业务场景里的稳定度提升了非常明显，至少不会再出现“该查数据库时凭空编数据”这类低级失误。
5. 进阶优化：动态技能学习与自我更新机制
做到上面这些，其实代理已经可以胜任不少固定流程的任务了。但如果想让技能体系具备成长性，还得考虑“动态技能学习”。这个方向我尝试了一些初步的方案，效果有待验证，但思路值得分享。
所谓动态技能学习，是指代理在运行过程中，能从失败的调用或用户反馈中自动提炼出新的技能或修正旧的技能描述。举个粗糙但有效的尝试：我给每次技能调用都埋了一个“用户纠偏”通道。如果用户对代理的回复不满意，并说了一句“不是这样，你应该先检查备份目录再恢复”，我就会记录下这个纠正信号。之后经过一系列格式化的处理，从这句话里抽取“检查备份目录”和“恢复数据”的动作，并尝试生成一个新的技能草稿，叫“数据恢复前置检查”。草稿会进入人工审核队列，我确认后才会正式注册为可用技能。
这种方式并非深度学习意义上的“学习”，它更多是一个经验沉淀的自动化过程。它依赖一个前提：代理的每次执行过程都被完整记录，且格式规范、可检索。我在项目里规定，每个技能调用都必须附带全局唯一的调用ID，上下文ID、执行时间、输入参数快照、输出结果摘要、错误信息都要以结构化日志形式存储。这样当某个技能特别容易在特定步骤出错时，日志分析就能提示我优先优化哪一块。这个机制跑了一个多月以后，我基本上不再靠拍脑袋决定下一个要优化的技能，日志会告诉我问题集中在哪。
还要提一个反面教训：动态更新技能描述这件事，最好不要让模型自己直接改注册表。我曾经让模型在发现技能描述不适配时自主修改描述内容，结果它把几个技能的描述改得花团锦簇、但实际行为和描述完全对不上，调度混乱了很久。后来我改成：模型只能提交“修改建议”，附带理由和证据（比如哪次调用产生了误判），真正落到注册表里的变更必须经过代码层审查。这个“人机协作”的度，我建议所有做类似功能的人都认真拿捏一下。
6. agent-skills在落地中容易遇到的五个坑和对应的避开方法
每一种技术方案做到最后，都会沉淀出一些“早踩早明白”的坑。这里我把agent-skills项目里最常见的五个坑列出来，每个坑都附带我的对应解法。
第一个坑：技能描述过于抽象。比如写“该技能处理用户请求”，模型根本不知道什么时候该调用它。解法是描述必须三维化：适用前置条件、执行动作、预期产出。最好还能带上一个示例，哪怕只有一句话，模型理解起来都会快很多。
第二个坑：技能参数设计过宽或过窄。过宽导致模型给出大量无效参数，过窄导致它经常没法组装出有效调用。解法是我前面提到的三层约束体系，以及给参数都提供“合理默认值+允许空值”的兜底逻辑。
第三个坑：技能之间边界模糊。“读取用户资料”和“获取用户历史订单”如果描述不到位，模型很容易搞混。解法除了写清边界外，还会在注册表里给相近技能加“与XX技能的区别”字段，它在内部实现上会有效帮助模型做区分。
第四个坑：忽略了技能执行的副作用。比如“格式化文件”这类技能一旦被执行，后患无穷。解法是在调度层加副作用标记，技能注册表里明确标注“是否有写操作”“是否不可逆”，并在执行前强制执行二次确认流程。
第五个坑：没有记录技能调用的完整链路。如果每个技能只返回结果而不留调用过程细节，代理出问题时根本无从排查。解法是从第一天就坚持结构化日志，所有技能调用的输入、输出、耗时、错误信息都进留档库，后续做优化时才不会靠猜。
这些坑单独看都不算致命，但叠加起来足以让一个代理项目从“可用”退化成“玩具”。每一条我都付出过实际代价才总结出来，现在写在这里，希望后来者能少走几步弯路。
7. 工具层面的选型建议：从写死代码到声明式技能配置
最后一个部分聊聊工具和配置方式。刚开始做技能系统时，我用的是纯代码方式，每个技能背后一个函数，然后把技能描述写进docstring，用一个装饰器把描述收集起来。这种方式简单、直接，但扩展性很差，每加一个技能都要重新发布代码，而且无法让业务人员参与维护技能描述。
后来我改成声明式技能配置的思路：技能列表与执行逻辑分离。技能名称、描述、参数、默认值、执行入口全部用一份结构化配置（JSON或YAML）描述，后台启动时读取配置并动态注册。执行逻辑仍然保留在代码里，但代码映射是通过配置里的“handler关键字”来完成的。这样做的直接收益是：我可以在不改变任何代码逻辑的情况下，修改技能描述、调整参数约束、甚至重新组织技能的调用顺序。
如果让我推荐具体体验较好的方案，我会优先选择一套支持“技能定义热更新”的框架。所谓热更新，不是要你在生产环境里改完立刻生效，而是说配置与逻辑分离后，你可以先在一个独立的测试环境里加载配置、跑测试集、验证效果，再通过发布流程同步到生产。我现在的做法是把技能注册表单独做成一个服务，提供一套简单的增删改查接口，代理启动时从服务拉取完整技能列表。这样技能的定义、审核、发布和召回都可以像对待数据一样管理，而不是像对待代码一样管理。对于团队协作来说，这种模式也能让非核心开发人员参与技能维护，他们只需要理解配置语法，不需要深入理解内部执行细节。
还有一个容易被忽略的点是技能版本管理。技能的描述和参数约束一旦变更，会影响正在运行的代理。如果没有任何版本概念，上一次调用还在用老描述，下一次调用就换成了新描述，模型行为很容易出现跳跃。我在技能注册表里加了“生效版本号”字段，每次变更都生成新版本，代理的每个对话都固定使用对话开始时的技能版本快照。这保证了同一个对话内，代理的技能视野是一致的，不会出现前后矛盾的调用行为。实践下来，版本固化机制维护成本很低，却避掉了不少“诡异故障”。
到这里，agent-skills在我项目里的摸索经历基本分享完了。从只把技能当配置，到把它当成一套需要设计、测试和运维的系统，这个过程我花了不少时间。每次调整技能定义结构、每次给参数约束加一层校验，都能感觉到代理稳定度往前进一点。手里工具顺了，模型本来应有的聪明劲才能真正发挥出来。
