几个月前我把手头一个Agent项目推倒重写原因很简单功能越加越多但模型经常在几个动作之间反复横跳一会调数据库一会写文件甚至把两个互不相关的业务逻辑硬拼在一起。后来我注意到社区里讨论agent-skills概念的人越来越多核心思路是把Agent的“能力”拆成一个个可独立定义、可单独测试、可动态加载的技能模块。按照这个思路重构之后整个系统的稳定性和可维护性明显上了一个台阶。这篇文章就结合我的实践聊聊agent-skills到底该怎么设计、怎么落地以及哪些坑一旦踩进去就很难爬出来。1. 从一把梭到技能拆解我为什么重写agent-skills1.1 单体Agent的痛点先还原一下大多数Agent项目的原始形态。最简单的做法是给大模型一个系统提示词把所有工具函数都写进函数列表然后让模型自己选。项目初期工具只有两三个问题不大。但只要工具数量超过十个麻烦就来了模型经常选错工具尤其是工具名称相似、描述写得含糊的时候。每个工具的执行逻辑都写在同一个文件里改一个功能可能影响其他功能。新加一个工具要重新跑全量回归因为工具之间的隐式耦合根本说不清。日志里全是“AI正在思考”但你永远不知道它下一步要调用什么出问题也难复现。我当时的项目里有一个工具叫send_notification既能发短信又能发邮件参数里用channel字段区分。结果模型经常把channel写成sms_email导致推送系统收到无法识别的渠道名。后来我把所有功能全拆开做成send_sms和send_email两个独立技能问题立刻消失。这件事让我意识到工具的“技能化”不是换个名字的事而是要从接口设计、描述方式、测试方法上彻底重构。1.2 Skills到底解决什么问题agent-skills的核心是把Agent的能力从“一堆松散的函数”变成“一组有明确边界、自描述、可复用的技能包”。每个技能包至少包含三样东西技能元信息名称、版本、用途、适用场景。入参和出参的schema严格定义模型可以传入什么、能拿到什么。执行逻辑实际干活的代码或脚本。在系统层面Agent不再直接面对几十个函数而是面对一个技能注册中心。模型先根据用户意图选择要加载的技能列表再在选中的技能范围内决定具体调用方式。这相当于在模型和底层操作之间加了一层缓冲区让决策和动作分离。我最直观的感受是之前模型像是一个没有键盘的钢琴家所有琴键都摆在面前但它不知道哪些琴键能一起按。技能化之后每个技能像一张乐谱模型只需要决定演奏哪首曲子至于音阶怎么跑那是乐谱内部的事。2. 技能库的目录结构与协议设计2.1 一个技能就是一个文件夹在设计agent-skills的仓库结构时我参考了传统Unix命令的设计哲学每个命令做一件事做好一件事。一个技能对应一个独立目录目录内包含固定的文件布局skills/ ├── weather_query/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ ├── requirements.txt │ └── tests/ │ └── test_success.py ├── send_email/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ ├── requirements.txt │ └── tests/ │ └── test_validate_recipient.py ├── calendar_create_event/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ └── ... └── registry.json这个结构的最大好处是每个技能可以独立开发、独立测试、独立部署。团队里不同的人可以同时修改不同技能合并时基本不会有冲突。而且后续做权限控制时只需要按目录粒度配置不用把权限字符串写进代码里。2.2 SKILL.md让LLM自己看懂技能说明书很多人在做工具描述时只写一句话比如“查询天气”。但大模型对这种描述的利用效率极低。我的经验是每个技能必须有一份完整的SKILL.md既给人读也给模型读。以weather_query为例我的SKILL.md开头是这样写的# weather_query 查询指定城市在指定日期的天气信息包括温度、湿度、降水概率和风力等级。 ## 使用场景 - 用户问“明天北京冷吗”“上海接下来三天会下雨吗” - 用户要求规划周末出行时涉及天气判断 - 用户想要决定穿什么衣服、要不要带伞 ## 使用限制 - 不处理历史天气数据只支持未来1-7天预报 - 不处理跨城市对比一次查询只能指定一个城市 - 如果日期超过7天范围直接返回错误提示不要尝试近似计算 ## 注意事项 - 城市名推荐使用中文全称如“北京市”“上海市” - 日期格式必须是YYYY-MM-DD - 当查询的城市不在支持列表时返回支持的省份列表供用户选择为什么写这么细因为模型在进行工具选择时本质上是在做“意图匹配”。描述越具体匹配的准确率越高。特别是“使用限制”和“注意事项”这两块能极大减少模型自己脑补的情况。比如我之前没有写“不处理历史天气”模型就会在用户问“去年冬天下了多少雪”时硬着头皮调用天气接口然后返回一个空数据再编一段看起来合理的解释。2.3 入参出参的约束设计每个技能还需要一个机器可读的schema.json用来约束模型生成参数的格式。我用的schema不是简单的JSON Schema而是额外增加了一些字段帮助系统做前置校验。{ name: weather_query, version: 1.3.0, input_schema: { type: object, properties: { city: { type: string, description: 城市中文名称如北京市, examples: [北京市, 上海市, 广州市], required: true }, date: { type: string, description: 查询日期格式YYYY-MM-DD, pattern: ^\\d{4}-\\d{2}-\\d{2}$, required: true }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, required: false } } }, output_schema: { type: object, properties: { temperature: {type: number}, humidity: {type: number}, precipitation_probability: {type: number}, wind_level: {type: string} } } }这里有一个容易被忽略的细节examples字段。大模型在生成参数时对枚举值、格式的把握并不稳定但给它一两个参考例子之后准确率会显著提升。比如city字段如果没有例子模型有时会输出拼音“beijing”而不是“北京市”。有了例子生成结果就符合预期了。3. 让Agent学会调用技能编排与路由3.1 技能注册与发现技能目录建好了下一步是让Agent知道有哪些技能可用。我在registry.json里维护一个技能列表启动时加载到内存然后提供给大模型作为上下文的候选。{ skills: [ {name: weather_query, version: 1.3.0, category: information}, {name: send_email, version: 2.0.1, category: communication}, {name: calendar_create_event, version: 1.1.0, category: calendar} ] }注册中心还负责技能的健康检查。每个技能在启动时可以暴露一个/health端点返回“ok”或者失败信息。如果某个技能依赖的外部API挂了注册中心会把它的状态标记为不可用然后通知Agent不要尝试调用。这一点很关键否则模型会选择那个技能然后硬等接口超时白白浪费十几秒。3.2 基于embedding的语义路由技能多了以后把全量技能描述都塞给大模型是不现实的。token数量会爆炸模型也会被无关信息干扰。所以我设计了一个语义路由层先把每个技能的描述嵌入成向量然后对用户当前问题也做向量化通过余弦相似度召回最相关的3到5个技能再把这些技能的描述交给大模型。具体实现可以用sentence-transformers或者OpenAI的embedding接口我倾向于用轻量级本地模型比如text2vec系列既省成本又响应快。召回逻辑不算复杂import numpy as np from sentence_transformers import SentenceTransformer model SentenceTransformer(text2vec-base-chinese) def build_skill_index(registry): docs [] skill_names [] for skill in registry[skills]: doc f{skill[name]}: {skill[description]} docs.append(doc) skill_names.append(skill[name]) embeddings model.encode(docs, normalize_embeddingsTrue) return dict(zip(skill_names, embeddings)) def retrieve_skills(question, index, top_k5): q_emb model.encode([question], normalize_embeddingsTrue)[0] scores {name: np.dot(q_emb, emb) for name, emb in index.items()} ranked sorted(scores.items(), keylambda x: x[1], reverseTrue) return [name for name, score in ranked[:top_k]]这里有个经验不要把top_k设得太高。我试过召回8个技能结果大模型在决策时还是会犹豫因为候选里有两个语义接近的技能比如“查天气”和“查气温”模型可能同时选两个。top_k在3到5之间比较合适既能覆盖大部分意图又不会制造选择困难。3.3 失败回退与多技能组合路由层只能解决“选哪个技能”的问题但实际对话经常需要多个技能协作。比如用户说“明天去杭州查一下天气顺便帮我把会议改到下午。”这句话里包含天气查询和日历修改两个意图。我采用的方案是把路由结果告诉大模型但不强制它只能用一个技能。模型可以在一次回复中输出多个技能调用系统按顺序执行再把每个结果合并成最终回答。这个过程中比较重要的是执行顺序。通常先执行只读技能查天气、查日历再执行写操作改日程、发邮件避免先写入后查询造成数据不一致。如果某个技能执行失败比如天气接口返回500系统不能直接告诉用户“失败”也不能让模型自己乱猜。正确做法是捕获异常后把错误信息作为“中间结果”回传给模型让模型决定是换一个技能、换一种参数还是明确告知用户失败原因。实测下来这个回退机制能挽回大约20%的对话失败场景。4. 落盘实测从零实现一个天气查询技能4.1 技能编写与测试理论知识讲完来点实际的。我全新实现了一个weather_query技能从目录创建到接入Agent的完整流程分享每一步的关键操作。首先创建技能目录里面放好SKILL.md、schema.json、main.py。main.py的核心是一个run(params)函数import datetime import requests def run(params: dict) - dict: city params.get(city) date params.get(date) unit params.get(unit, celsius) if not city or not date: raise ValueError(city and date are required) try: date_obj datetime.datetime.strptime(date, %Y-%m-%d) except ValueError: raise ValueError(date must be in YYYY-MM-DD format) if date_obj datetime.date.today(): raise ValueError(only supports future dates within 7 days) url https://api.weather.example.com/v1/forecast params {city: city, date: date, unit: unit} resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() data resp.json() return { temperature: data[temp], humidity: data[humidity], precipitation_probability: data[pop], wind_level: data[wind] }写完之后不要直接接Agent先写几个单元测试测试用例覆盖正常请求、非法日期、超范围日期、接口超时等情况。这一步看起来繁琐但能省下后面联调的大量精力。4.2 集成到Agent主流程技能测通后把它注册到registry.json然后修改Agent的主循环。我采用的是一个比较清晰的循环结构获取用户输入。向量化输入召回候选技能。把候选技能描述、schema、用户输入一起传给大模型。模型返回结构化指令可能包含技能调用。系统执行技能调用把结果回填给模型。模型生成最终回答。伪代码如下def agent_loop(user_input: str): question user_input candidates retrieve_skills(question, skill_index) messages build_prompt(question, candidates) while True: response llm.chat(messages) if response.has_tool_calls(): results [] for call in response.tool_calls: skill registry.get(call.skill_name) try: result skill.run(call.arguments) results.append({skill: call.skill_name, ok: True, data: result}) except Exception as e: results.append({skill: call.skill_name, ok: False, error: str(e)}) messages.append(assistant_with_tools(response)) messages.append(tool_results(results)) else: return response.text这个循环看起来简单但有一个容易踩的坑当技能执行失败时模型可能会陷入无限循环反复用同样的参数调用同一个技能。我加了一个计数器同一个技能连续失败3次就强制终止并且告诉用户“这个功能暂时不可用”。4.3 实测表现与异常处理我用一组真实对话做了测试结果如下以“明天北京会不会下雨”为例路由层召回了weather_query模型正确调用返回温度、湿度、降水概率最终回答也很自然。但下面这种问题就露馅了“后天南京天气怎么样适合户外跑步吗”模型正确调用了天气技能但返回结果里没有“是否适合跑步”的判断。后来我意识到应该让技能返回更多维度比如风速、空气质量指数然后在SKILL.md里增加一条“根据天气数据给出活动建议”的示例模型就会自动基于结果做推理。还有一次用户问“北京一周的天气趋势”模型一次性调用了七天天气查询但七天对应七个技能调用系统需要批量执行。我一开始的代码是串行请求接口响应极慢。后来改成asyncio.gather并发请求才把整体延迟从6秒降到1.5秒。所以如果你设计的技能可能被多次调用一定要考虑并发执行的能力。5. 我踩过的坑技能粒度的取舍与版本管理5.1 粒度太细 vs 太粗技能拆分的粒度是最难把握的事情。我一开始把“发送短信”和“发送邮件”分开后来又拆出“发送验证码短信”“发送通知短信”“发送营销短信”结果技能数量爆炸路由经常选错。因为“发送验证码短信”和“发送通知短信”在语义上太接近了模型很难区分。后来我调整了策略外部操作接口如同一个API的权限层级如果一致就把它们合并成一个技能如果行为差异足够大比如“查询天气”和“下单”才拆开。技能粒度应该以“用户意图是否可区分”为标准而不是以“函数功能是否单一”为标准。再举个例子日历相关的“创建事件”“删除事件”“查看日程”这三个操作虽然对应不同API但用户意图都是“管理日历”我认为不应该拆成三个独立技能而是应该做成一个calendar_manage技能内部用action参数区分。这样路由只需要判断用户是否要操作日历不用去猜用户是想创建还是删除。内部动作的判断交给模型在更小的参数空间里完成正确率会更高。5.2 技能版本与兼容性技能是会迭代的。接口返回字段改了或者入参校验逻辑变了都可能导致已上线的Agent行为异常。我吃过一个亏weather_query技能从v1.0升级到v1.1时把temperature从摄氏温度字符串改成了浮点数然后忘记更新output_schema。结果Agent在执行后续基于该结果的逻辑时把字符串拼进了SQL直接报错。现在我的做法是每个技能带version字段格式遵循语义化版本。改动不兼容的字段时保留旧版本一段时间并标记为deprecated。注册中心里可以同时存在多版本技能但默认路由只指向最新稳定版。在CI/CD流程中加入技能版本diff检查一旦发现schema变化必须更新对应测试用例。5.3 权限与安全边界技能化做得好权限控制也能做得更细。比如“查询天气”是只读技能而“发送邮件”是写操作两者的权限级别不同。我在技能目录里增加了一个permission字段注册中心根据当前用户的会话权限动态决定哪些技能出现在候选列表里。这里有个安全细节技能的入参不能直接被拼进SQL或shell命令。预防注入的手段和传统后端一样使用参数化查询或subprocess的列表参数而不是字符串拼接。另外技能的执行环境最好是隔离的比如用Docker容器或者至少是独立的虚拟环境防止某个恶意技能读取系统文件。我还给技能增加了审计日志。每次技能调用都会记录哪个会话ID、什么时间、传入参数、执行结果、耗时。这些日志不仅方便排查问题还能用来做数据统计比如哪些技能常被调用哪些技能经常报错从而指导后续优化。6. 更进一步动态加载、技能市场与闭环优化6.1 热插拔式技能加载如果你做的Agent是长期运行的技能不可能每次改完都重启服务。更合理的方案是支持动态加载注册中心监听技能目录的文件变化当某个SKILL.md或main.py被修改时重新加载该技能而不影响其他技能。我用的是watchdog库加一个简单的加载器from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler class SkillReloadHandler(FileSystemEventHandler): def on_modified(self, event): path event.src_path if path.endswith(main.py) or path.endswith(SKILL.md): skill_name path.split(/)[-2] registry.reload(skill_name)这个功能非常实用。我在调试新技能时只需要修改文件Agent系统过几秒就自动使用新版本省去了手动重启容器的流程。但注意reload必须有版本管理配套否则修改过程中可能产生中间态导致注册中心读到半份文件。6.2 构建技能市场与复用当技能库越来越大你会发现很多技能是可复用的。比如“读取网页内容”技能“获取RSS订阅更新”技能几乎每个Agent都用得上。这时就可以搭一个内部的技能市场把技能打包成zip或git仓库包含SKILL.md、schema.json、main.py其他人直接pull下来就能用。我在团队里做了一个简单的目录把技能按领域分类信息获取、日程管理、沟通协作、数据分析、代码执行。每个技能有独立的stars数量类似GitHub的star机制用来反映实际使用率。这样团队新成员上手时优先选用高star技能避免重复造轮子。技能市场还促进了不同项目之间的交流。以前每个Agent项目都各自维护一套工具函数现在大家都在贡献公共技能比如“OCR识别图片”“PDF转文本”“查询汇率”“翻译文本”等。这些技能通过模块化封装内部使用了什么API外部的人根本不用关心只要符合技能协议就能被任何Agent调用。6.3 从日志中学习技能调用的闭环优化最后说一个比较容易忽略的点技能运行日志是你优化整个Agent系统最有价值的材料。我每周会跑一次日志分析统计各技能的调用频次、成功率、平均耗时、错误类型。有一次分析发现calendar_create_event技能成功率只有78%错误大多出现在“时间冲突”场景。我看了日志原来模型把时间描述“明天下午3点”传成了“下午3:00:00”然后技能内部的时间解析逻辑不认识带冒号的格式。我修改了解析逻辑兼容多种时间表达成功率立刻升到96%。还有一次我发现weather_query技能被调用的频率特别高但实际用户并不都是问天气很多人是在问“适合穿什么衣服”。于是我把这个意图拆到另一个技能clothing_suggestion里它内部会先调天气API再结合穿衣指数从而分担了主技能的负载。技能日志还能反馈出模型能力的变化。比如某个大模型版本的指令遵循能力下降日志中就会出现更多技能调用次数的暴增或者模型反复修正参数的情况。这时候你就知道要调整提示词或者切换模型版本了。写在最后的一点个人体会重新设计agent-skills体系之后我最深的感受是AI应用开发和传统软件开发最大的不同在于你面对的是一个“概率性调用者”你无法逼它保证不犯错但你可以通过设计优质技能来降低犯错概率。技能描述写得清楚它的决策就更容易正确schema定义得严格它的参数就更容易合法测试覆盖到位它踩坑之后就能更快修复。这一切都没有什么神奇魔法就是把工程基本功老老实实搬过来再额外针对大模型的行为特征做一层适配。如果你也正准备整理自己的Agent项目我的建议是先别急着写代码把你现有的所有工具函数列出来挨个问自己三个问题——它的用户意图是什么它应该接收什么样的参数它能返回什么结果每个问题都想清楚了再开始动手。agent-skills这条路最大的价值不在于让系统看起来更酷而在于让系统真正变得可控。这套思路实践下来大概用了三周时间但让后续每一个新技能的接入时间从一两天压缩到一小时内这笔账怎么算都是值的。
几个月前我把手头一个Agent项目推倒重写原因很简单功能越加越多但模型经常在几个动作之间反复横跳一会调数据库一会写文件甚至把两个互不相关的业务逻辑硬拼在一起。后来我注意到社区里讨论agent-skills概念的人越来越多核心思路是把Agent的“能力”拆成一个个可独立定义、可单独测试、可动态加载的技能模块。按照这个思路重构之后整个系统的稳定性和可维护性明显上了一个台阶。这篇文章就结合我的实践聊聊agent-skills到底该怎么设计、怎么落地以及哪些坑一旦踩进去就很难爬出来。1. 从一把梭到技能拆解我为什么重写agent-skills1.1 单体Agent的痛点先还原一下大多数Agent项目的原始形态。最简单的做法是给大模型一个系统提示词把所有工具函数都写进函数列表然后让模型自己选。项目初期工具只有两三个问题不大。但只要工具数量超过十个麻烦就来了模型经常选错工具尤其是工具名称相似、描述写得含糊的时候。每个工具的执行逻辑都写在同一个文件里改一个功能可能影响其他功能。新加一个工具要重新跑全量回归因为工具之间的隐式耦合根本说不清。日志里全是“AI正在思考”但你永远不知道它下一步要调用什么出问题也难复现。我当时的项目里有一个工具叫send_notification既能发短信又能发邮件参数里用channel字段区分。结果模型经常把channel写成sms_email导致推送系统收到无法识别的渠道名。后来我把所有功能全拆开做成send_sms和send_email两个独立技能问题立刻消失。这件事让我意识到工具的“技能化”不是换个名字的事而是要从接口设计、描述方式、测试方法上彻底重构。1.2 Skills到底解决什么问题agent-skills的核心是把Agent的能力从“一堆松散的函数”变成“一组有明确边界、自描述、可复用的技能包”。每个技能包至少包含三样东西技能元信息名称、版本、用途、适用场景。入参和出参的schema严格定义模型可以传入什么、能拿到什么。执行逻辑实际干活的代码或脚本。在系统层面Agent不再直接面对几十个函数而是面对一个技能注册中心。模型先根据用户意图选择要加载的技能列表再在选中的技能范围内决定具体调用方式。这相当于在模型和底层操作之间加了一层缓冲区让决策和动作分离。我最直观的感受是之前模型像是一个没有键盘的钢琴家所有琴键都摆在面前但它不知道哪些琴键能一起按。技能化之后每个技能像一张乐谱模型只需要决定演奏哪首曲子至于音阶怎么跑那是乐谱内部的事。2. 技能库的目录结构与协议设计2.1 一个技能就是一个文件夹在设计agent-skills的仓库结构时我参考了传统Unix命令的设计哲学每个命令做一件事做好一件事。一个技能对应一个独立目录目录内包含固定的文件布局skills/ ├── weather_query/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ ├── requirements.txt │ └── tests/ │ └── test_success.py ├── send_email/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ ├── requirements.txt │ └── tests/ │ └── test_validate_recipient.py ├── calendar_create_event/ │ ├── SKILL.md │ ├── schema.json │ ├── main.py │ └── ... └── registry.json这个结构的最大好处是每个技能可以独立开发、独立测试、独立部署。团队里不同的人可以同时修改不同技能合并时基本不会有冲突。而且后续做权限控制时只需要按目录粒度配置不用把权限字符串写进代码里。2.2 SKILL.md让LLM自己看懂技能说明书很多人在做工具描述时只写一句话比如“查询天气”。但大模型对这种描述的利用效率极低。我的经验是每个技能必须有一份完整的SKILL.md既给人读也给模型读。以weather_query为例我的SKILL.md开头是这样写的# weather_query 查询指定城市在指定日期的天气信息包括温度、湿度、降水概率和风力等级。 ## 使用场景 - 用户问“明天北京冷吗”“上海接下来三天会下雨吗” - 用户要求规划周末出行时涉及天气判断 - 用户想要决定穿什么衣服、要不要带伞 ## 使用限制 - 不处理历史天气数据只支持未来1-7天预报 - 不处理跨城市对比一次查询只能指定一个城市 - 如果日期超过7天范围直接返回错误提示不要尝试近似计算 ## 注意事项 - 城市名推荐使用中文全称如“北京市”“上海市” - 日期格式必须是YYYY-MM-DD - 当查询的城市不在支持列表时返回支持的省份列表供用户选择为什么写这么细因为模型在进行工具选择时本质上是在做“意图匹配”。描述越具体匹配的准确率越高。特别是“使用限制”和“注意事项”这两块能极大减少模型自己脑补的情况。比如我之前没有写“不处理历史天气”模型就会在用户问“去年冬天下了多少雪”时硬着头皮调用天气接口然后返回一个空数据再编一段看起来合理的解释。2.3 入参出参的约束设计每个技能还需要一个机器可读的schema.json用来约束模型生成参数的格式。我用的schema不是简单的JSON Schema而是额外增加了一些字段帮助系统做前置校验。{ name: weather_query, version: 1.3.0, input_schema: { type: object, properties: { city: { type: string, description: 城市中文名称如北京市, examples: [北京市, 上海市, 广州市], required: true }, date: { type: string, description: 查询日期格式YYYY-MM-DD, pattern: ^\\d{4}-\\d{2}-\\d{2}$, required: true }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, required: false } } }, output_schema: { type: object, properties: { temperature: {type: number}, humidity: {type: number}, precipitation_probability: {type: number}, wind_level: {type: string} } } }这里有一个容易被忽略的细节examples字段。大模型在生成参数时对枚举值、格式的把握并不稳定但给它一两个参考例子之后准确率会显著提升。比如city字段如果没有例子模型有时会输出拼音“beijing”而不是“北京市”。有了例子生成结果就符合预期了。3. 让Agent学会调用技能编排与路由3.1 技能注册与发现技能目录建好了下一步是让Agent知道有哪些技能可用。我在registry.json里维护一个技能列表启动时加载到内存然后提供给大模型作为上下文的候选。{ skills: [ {name: weather_query, version: 1.3.0, category: information}, {name: send_email, version: 2.0.1, category: communication}, {name: calendar_create_event, version: 1.1.0, category: calendar} ] }注册中心还负责技能的健康检查。每个技能在启动时可以暴露一个/health端点返回“ok”或者失败信息。如果某个技能依赖的外部API挂了注册中心会把它的状态标记为不可用然后通知Agent不要尝试调用。这一点很关键否则模型会选择那个技能然后硬等接口超时白白浪费十几秒。3.2 基于embedding的语义路由技能多了以后把全量技能描述都塞给大模型是不现实的。token数量会爆炸模型也会被无关信息干扰。所以我设计了一个语义路由层先把每个技能的描述嵌入成向量然后对用户当前问题也做向量化通过余弦相似度召回最相关的3到5个技能再把这些技能的描述交给大模型。具体实现可以用sentence-transformers或者OpenAI的embedding接口我倾向于用轻量级本地模型比如text2vec系列既省成本又响应快。召回逻辑不算复杂import numpy as np from sentence_transformers import SentenceTransformer model SentenceTransformer(text2vec-base-chinese) def build_skill_index(registry): docs [] skill_names [] for skill in registry[skills]: doc f{skill[name]}: {skill[description]} docs.append(doc) skill_names.append(skill[name]) embeddings model.encode(docs, normalize_embeddingsTrue) return dict(zip(skill_names, embeddings)) def retrieve_skills(question, index, top_k5): q_emb model.encode([question], normalize_embeddingsTrue)[0] scores {name: np.dot(q_emb, emb) for name, emb in index.items()} ranked sorted(scores.items(), keylambda x: x[1], reverseTrue) return [name for name, score in ranked[:top_k]]这里有个经验不要把top_k设得太高。我试过召回8个技能结果大模型在决策时还是会犹豫因为候选里有两个语义接近的技能比如“查天气”和“查气温”模型可能同时选两个。top_k在3到5之间比较合适既能覆盖大部分意图又不会制造选择困难。3.3 失败回退与多技能组合路由层只能解决“选哪个技能”的问题但实际对话经常需要多个技能协作。比如用户说“明天去杭州查一下天气顺便帮我把会议改到下午。”这句话里包含天气查询和日历修改两个意图。我采用的方案是把路由结果告诉大模型但不强制它只能用一个技能。模型可以在一次回复中输出多个技能调用系统按顺序执行再把每个结果合并成最终回答。这个过程中比较重要的是执行顺序。通常先执行只读技能查天气、查日历再执行写操作改日程、发邮件避免先写入后查询造成数据不一致。如果某个技能执行失败比如天气接口返回500系统不能直接告诉用户“失败”也不能让模型自己乱猜。正确做法是捕获异常后把错误信息作为“中间结果”回传给模型让模型决定是换一个技能、换一种参数还是明确告知用户失败原因。实测下来这个回退机制能挽回大约20%的对话失败场景。4. 落盘实测从零实现一个天气查询技能4.1 技能编写与测试理论知识讲完来点实际的。我全新实现了一个weather_query技能从目录创建到接入Agent的完整流程分享每一步的关键操作。首先创建技能目录里面放好SKILL.md、schema.json、main.py。main.py的核心是一个run(params)函数import datetime import requests def run(params: dict) - dict: city params.get(city) date params.get(date) unit params.get(unit, celsius) if not city or not date: raise ValueError(city and date are required) try: date_obj datetime.datetime.strptime(date, %Y-%m-%d) except ValueError: raise ValueError(date must be in YYYY-MM-DD format) if date_obj datetime.date.today(): raise ValueError(only supports future dates within 7 days) url https://api.weather.example.com/v1/forecast params {city: city, date: date, unit: unit} resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() data resp.json() return { temperature: data[temp], humidity: data[humidity], precipitation_probability: data[pop], wind_level: data[wind] }写完之后不要直接接Agent先写几个单元测试测试用例覆盖正常请求、非法日期、超范围日期、接口超时等情况。这一步看起来繁琐但能省下后面联调的大量精力。4.2 集成到Agent主流程技能测通后把它注册到registry.json然后修改Agent的主循环。我采用的是一个比较清晰的循环结构获取用户输入。向量化输入召回候选技能。把候选技能描述、schema、用户输入一起传给大模型。模型返回结构化指令可能包含技能调用。系统执行技能调用把结果回填给模型。模型生成最终回答。伪代码如下def agent_loop(user_input: str): question user_input candidates retrieve_skills(question, skill_index) messages build_prompt(question, candidates) while True: response llm.chat(messages) if response.has_tool_calls(): results [] for call in response.tool_calls: skill registry.get(call.skill_name) try: result skill.run(call.arguments) results.append({skill: call.skill_name, ok: True, data: result}) except Exception as e: results.append({skill: call.skill_name, ok: False, error: str(e)}) messages.append(assistant_with_tools(response)) messages.append(tool_results(results)) else: return response.text这个循环看起来简单但有一个容易踩的坑当技能执行失败时模型可能会陷入无限循环反复用同样的参数调用同一个技能。我加了一个计数器同一个技能连续失败3次就强制终止并且告诉用户“这个功能暂时不可用”。4.3 实测表现与异常处理我用一组真实对话做了测试结果如下以“明天北京会不会下雨”为例路由层召回了weather_query模型正确调用返回温度、湿度、降水概率最终回答也很自然。但下面这种问题就露馅了“后天南京天气怎么样适合户外跑步吗”模型正确调用了天气技能但返回结果里没有“是否适合跑步”的判断。后来我意识到应该让技能返回更多维度比如风速、空气质量指数然后在SKILL.md里增加一条“根据天气数据给出活动建议”的示例模型就会自动基于结果做推理。还有一次用户问“北京一周的天气趋势”模型一次性调用了七天天气查询但七天对应七个技能调用系统需要批量执行。我一开始的代码是串行请求接口响应极慢。后来改成asyncio.gather并发请求才把整体延迟从6秒降到1.5秒。所以如果你设计的技能可能被多次调用一定要考虑并发执行的能力。5. 我踩过的坑技能粒度的取舍与版本管理5.1 粒度太细 vs 太粗技能拆分的粒度是最难把握的事情。我一开始把“发送短信”和“发送邮件”分开后来又拆出“发送验证码短信”“发送通知短信”“发送营销短信”结果技能数量爆炸路由经常选错。因为“发送验证码短信”和“发送通知短信”在语义上太接近了模型很难区分。后来我调整了策略外部操作接口如同一个API的权限层级如果一致就把它们合并成一个技能如果行为差异足够大比如“查询天气”和“下单”才拆开。技能粒度应该以“用户意图是否可区分”为标准而不是以“函数功能是否单一”为标准。再举个例子日历相关的“创建事件”“删除事件”“查看日程”这三个操作虽然对应不同API但用户意图都是“管理日历”我认为不应该拆成三个独立技能而是应该做成一个calendar_manage技能内部用action参数区分。这样路由只需要判断用户是否要操作日历不用去猜用户是想创建还是删除。内部动作的判断交给模型在更小的参数空间里完成正确率会更高。5.2 技能版本与兼容性技能是会迭代的。接口返回字段改了或者入参校验逻辑变了都可能导致已上线的Agent行为异常。我吃过一个亏weather_query技能从v1.0升级到v1.1时把temperature从摄氏温度字符串改成了浮点数然后忘记更新output_schema。结果Agent在执行后续基于该结果的逻辑时把字符串拼进了SQL直接报错。现在我的做法是每个技能带version字段格式遵循语义化版本。改动不兼容的字段时保留旧版本一段时间并标记为deprecated。注册中心里可以同时存在多版本技能但默认路由只指向最新稳定版。在CI/CD流程中加入技能版本diff检查一旦发现schema变化必须更新对应测试用例。5.3 权限与安全边界技能化做得好权限控制也能做得更细。比如“查询天气”是只读技能而“发送邮件”是写操作两者的权限级别不同。我在技能目录里增加了一个permission字段注册中心根据当前用户的会话权限动态决定哪些技能出现在候选列表里。这里有个安全细节技能的入参不能直接被拼进SQL或shell命令。预防注入的手段和传统后端一样使用参数化查询或subprocess的列表参数而不是字符串拼接。另外技能的执行环境最好是隔离的比如用Docker容器或者至少是独立的虚拟环境防止某个恶意技能读取系统文件。我还给技能增加了审计日志。每次技能调用都会记录哪个会话ID、什么时间、传入参数、执行结果、耗时。这些日志不仅方便排查问题还能用来做数据统计比如哪些技能常被调用哪些技能经常报错从而指导后续优化。6. 更进一步动态加载、技能市场与闭环优化6.1 热插拔式技能加载如果你做的Agent是长期运行的技能不可能每次改完都重启服务。更合理的方案是支持动态加载注册中心监听技能目录的文件变化当某个SKILL.md或main.py被修改时重新加载该技能而不影响其他技能。我用的是watchdog库加一个简单的加载器from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler class SkillReloadHandler(FileSystemEventHandler): def on_modified(self, event): path event.src_path if path.endswith(main.py) or path.endswith(SKILL.md): skill_name path.split(/)[-2] registry.reload(skill_name)这个功能非常实用。我在调试新技能时只需要修改文件Agent系统过几秒就自动使用新版本省去了手动重启容器的流程。但注意reload必须有版本管理配套否则修改过程中可能产生中间态导致注册中心读到半份文件。6.2 构建技能市场与复用当技能库越来越大你会发现很多技能是可复用的。比如“读取网页内容”技能“获取RSS订阅更新”技能几乎每个Agent都用得上。这时就可以搭一个内部的技能市场把技能打包成zip或git仓库包含SKILL.md、schema.json、main.py其他人直接pull下来就能用。我在团队里做了一个简单的目录把技能按领域分类信息获取、日程管理、沟通协作、数据分析、代码执行。每个技能有独立的stars数量类似GitHub的star机制用来反映实际使用率。这样团队新成员上手时优先选用高star技能避免重复造轮子。技能市场还促进了不同项目之间的交流。以前每个Agent项目都各自维护一套工具函数现在大家都在贡献公共技能比如“OCR识别图片”“PDF转文本”“查询汇率”“翻译文本”等。这些技能通过模块化封装内部使用了什么API外部的人根本不用关心只要符合技能协议就能被任何Agent调用。6.3 从日志中学习技能调用的闭环优化最后说一个比较容易忽略的点技能运行日志是你优化整个Agent系统最有价值的材料。我每周会跑一次日志分析统计各技能的调用频次、成功率、平均耗时、错误类型。有一次分析发现calendar_create_event技能成功率只有78%错误大多出现在“时间冲突”场景。我看了日志原来模型把时间描述“明天下午3点”传成了“下午3:00:00”然后技能内部的时间解析逻辑不认识带冒号的格式。我修改了解析逻辑兼容多种时间表达成功率立刻升到96%。还有一次我发现weather_query技能被调用的频率特别高但实际用户并不都是问天气很多人是在问“适合穿什么衣服”。于是我把这个意图拆到另一个技能clothing_suggestion里它内部会先调天气API再结合穿衣指数从而分担了主技能的负载。技能日志还能反馈出模型能力的变化。比如某个大模型版本的指令遵循能力下降日志中就会出现更多技能调用次数的暴增或者模型反复修正参数的情况。这时候你就知道要调整提示词或者切换模型版本了。写在最后的一点个人体会重新设计agent-skills体系之后我最深的感受是AI应用开发和传统软件开发最大的不同在于你面对的是一个“概率性调用者”你无法逼它保证不犯错但你可以通过设计优质技能来降低犯错概率。技能描述写得清楚它的决策就更容易正确schema定义得严格它的参数就更容易合法测试覆盖到位它踩坑之后就能更快修复。这一切都没有什么神奇魔法就是把工程基本功老老实实搬过来再额外针对大模型的行为特征做一层适配。如果你也正准备整理自己的Agent项目我的建议是先别急着写代码把你现有的所有工具函数列出来挨个问自己三个问题——它的用户意图是什么它应该接收什么样的参数它能返回什么结果每个问题都想清楚了再开始动手。agent-skills这条路最大的价值不在于让系统看起来更酷而在于让系统真正变得可控。这套思路实践下来大概用了三周时间但让后续每一个新技能的接入时间从一两天压缩到一小时内这笔账怎么算都是值的。
