从去年开始我一直在折腾 AI Agent 相关的项目试过 LangChain、AutoGPT 这类框架也自己手搓过 workflow但真正让我感觉Agent 从玩具变成工具的关键节点是开始认真设计 agent-skills 体系之后。这东西说白了就是给 Agent 装上可复用的技能包让它在面对不同任务时能调用最合适的处理能力而不是每次都从零开始思考。写这篇文章不打算给你堆概念而是想把我踩过的坑、验证过的设计思路、以及一套能直接落地的 agent-skills 实现方案完整讲清楚。如果你正在做 Agent 应用开发或者准备给自己的 AI 产品加技能扩展能力这篇文章应该能帮你少走不少弯路。1. agent-skills 是什么以及为什么它不是插件那么简单1.1 从会聊天到会干活的关键一跃早期的大模型应用核心是一个对话接口你问它答它用参数里的知识来推理。这个阶段的能力边界很清楚模型再强也拿不到实时数据没法操作外部系统更没法执行多步骤的物理或数字世界动作。Agent 的出现本质上是把大模型推理和外部动作执行之间架了一座桥。而 agent-skills 就是这座桥上一个个成体系的功能模块——比如一个 skill 可以负责查天气,另一个负责管理日历还有一个负责写 SQL 查数据库。每个 skill 内部有清晰的输入输出定义、有执行逻辑、有错误处理、甚至还有自己专属的提示词和工具函数。很多人第一次接触这个概念会把它和插件画等号。其实两者有本质区别插件系统大多是被动调用用户点了某个功能插件就执行对应动作而 agent-skills 是让 Agent 根据当前任务目标自主判断该用哪个技能、按什么顺序组合技能。也就是说技能的调度权在 Agent 手里而不是在被调用的工具手里。这个调度权的转移才是 agent-skills 和传统插件最大的分水岭。1.2 一个 skill 的典型内部结构我在项目里定义的 skill并不是一个简单的函数而是一个包含四层结构的完整单元描述层一段给 Agent 看的自然语言说明描述这个技能什么时候该用、什么时候不该用、大概能干什么。这段描述的质量直接决定 Agent 会不会在错误的场景下误调这个技能。参数层明确的入参 schema包括参数名、类型、枚举取值、默认值、必填非必填。Agent 会基于这段 schema 从用户话术中抽取参数。执行层真正干活的代码逻辑可以是调用内部函数、请求外部 API、读写数据库甚至编排一组子动作。反馈层执行完之后的返回结果以及可能附带的调试信息、错误码、下次调用的优化建议。这里最容易翻车的地方在于参数层和描述层。很多团队把 skill 写成了一个内部函数Agent 压根不知道什么时候调它或者参数抽取得一塌糊涂。我后面会详细讲怎么写描述层和参数层这里先留个印象agent-skills 的难点不在写代码而在让 Agent 准确理解并使用这些代码。1.3 项目里 agent-skills 的适用场景从我实际做过的项目来看agent-skills 特别适合下面几类场景第一垂直行业的任务型助手。比如客服助手需要查订单、退换货、催发货这些动作拆成一个个 skillAgent 在对话里自动判断要调用哪个。第二个人效率工具。比如日程管理助手要能创建会议、查空闲时段、发邀请邮件每个动作对应一个 skill互相之间还能组合。第三数据分析类应用。Agent 负责理解用户的数据问题然后利用查表 skill画图 skill生成报告 skill一步步完成分析任务。反过来说如果你的应用只是单纯的内容生成、翻译、总结这类纯文本进、纯文本出的任务那 agent-skills 的收益不大直接用大模型的指令遵循能力就行。技能系统带来的复杂度和维护成本在这种场景下是纯负担。2. 整体设计怎么搭一套不至于失控的 agent-skills 体系2.1 先定边界技能是窄而深不是大而全我在第一个版本里犯过一个典型的错误想做一个全能助手所以在 skill 列表里塞了三十多个功能从查天气到写诗全都有。结果 Agent 在选择技能的时候频繁出错经常把帮我写一首关于雨的诗这个请求路由到查询天气的技能上。后来我把每个 skill 的边界收窄才意识到问题所在描述层的语义空间互相重叠Agent 根本分不清。设计 agent-skills 的第一原则就是每个技能只做一件足够明确的事。一个查天气的 skill就只查天气不要顺手把穿衣建议也放进去一个发邮件的 skill就只负责按收件人、主题、正文把邮件发出去不要试图理解邮件该不该发这种策略问题。用生活里的例子打比方一个好的技能体系像工具箱里的成套螺丝刀——每种规格一把用途明确而不是像瑞士军刀一个工具想包打天下。Agent 的调度能力还没有强到能从一堆边界模糊的工具里精准挑出正确选项所以人为把边界做清晰就是在帮 Agent 减负。2.2 分层设计核心技能、领域技能、通用技能为了让技能体系不至于一上来就变成一坨乱麻我习惯把技能分成三个层级来管理。核心技能是任何 Agent 都离不开的基础能力比如调用大模型做文本推理从自由文本中抽取结构化信息记忆读写。这些技能提供的是底座一般不需要业务方修改。领域技能是针对某一垂直场景设计的比如电商场景的查询订单状态计算退款金额医疗场景的解析化验单匹配药品禁忌。这一层是产品差异化的关键通常需要业务专家和大模型工程师一起定义。通用技能是跨场景复用的比如发送 HTTP 请求读写文件执行 Python 代码。它们本身不含业务逻辑但业务类技能经常会在执行层调用它们。这个分层的好处有三个。第一职责清楚不同团队可以各管一摊互不干扰。第二复用率高通用技能被多个领域技能调用不会重复造轮子。第三排查问题方便出 bug 时先定位是哪个层的哪个技能再往下追。2.3 调度策略让 Agent 自己选但别让它裸奔技能有了谁来决定调哪个这是 agent-skills 体系里最核心的架构决策。我见过三种做法第一种是完全靠 Agent 自主选择。把所有技能的描述和参数 schema 塞进上下文让大模型在每次任务里自己挑。优点是灵活缺点是技能多了以后上下文会被撑爆选择准确率也会下降。实测下来超过十五个技能再靠这种方式误调率明显上升。第二种是规则路由优先。先写一层硬编码规则根据关键词或用户意图把请求分到某一组技能。比如用户消息里出现订单物流发货直接路由到电商技能组。这种方式准确率高但僵化遇到没见过的说法就漏。第三种是混合式也是我现在推荐的做法。先用规则或一个轻量分类模型做粗粒度路由缩小到某几个候选技能再把候选技能的详细描述交给大模型做细粒度选择。相当于先粗筛再精挑既控制了上下文长度又保留了 Agent 的决策灵活性。2.4 几个关键设计决策的取舍在设计阶段就被反复问到的几个问题我直接给结论技能要不要支持嵌套调用要但别太深。我的项目里允许一个 skill 在内部调用其他 skill比如安排会议这个技能内部会调用查空闲时间和发送日历邀请两个子技能。但我会限制嵌套层级最多两层再深就说明技能拆得有问题调度链路太长也没法调试。技能状态要不要持久化看场景。有些技能就是无状态的输入输出就完了但像购物车管理这种必须有状态存储。我的方案是让技能显式声明自己是否有状态、用什么 key 作为状态标识由 Agent 运行框架统一管理状态生命周期而不是让每个技能自己维护一个全局变量——不然技能之间互相污染状态查 bug 查到怀疑人生。2.5 我踩过的设计坑过度泛化与过早抽象最后必须提醒一句设计 agent-skills 体系时别一上来就追求完美抽象。我见过有人花两周时间设计一套万能技能基类支持任意参数、任意返回类型、任意错误码结果真正接业务的时候有一半的功夫花在了如何把简单需求套进复杂基类上。我的做法是先按真实业务需求把技能写出来能跑通再说。等到三五个技能都稳定了再回头看看能不能抽公共逻辑。过早抽象在这个领域是最大的时间杀手因为你还没真正理解业务的变与不变抽象出来的东西大概率是错的。3. 核心实战从零实现一个可用的 agent-skill3.1 选定实现载体为什么我选 Python JSON Schema实际写代码之前先交代一下技术选型。我目前的主力方案是 Python原因很直接AI 生态里的工具库几乎都是 Python 优先从 langchain 到各类 embedding 工具Python 的接入成本最低。如果你所在团队是 Node 技术栈也不是不行只是部分 AI 相关库的可用性会差一些。技能的契约格式我统一用 JSON Schema 来定义。这个选择基于两点第一JSON Schema 是事实标准大模型对它的理解特别好因为训练语料里这种格式太常见了第二它自带了类型校验、必填校验、枚举校验能力能在参数进入执行层之前就把明显错误挡掉。一个典型的技能定义文件长这样{ name: get_weather, description: 查询指定城市当前天气情况。当用户询问天气、温度、降雨概率、空气质量时使用。如果用户没有明确城市不要使用该技能。, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海、广州。必须是用户明确提到的城市。 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 温度单位默认摄氏。华氏仅当用户明确要求时使用。 } }, required: [city] } }注意看 description 字段的写法我把什么时候该用、什么时候不该用、参数怎么抽取全写进去了。这就是前面说的让 Agent 准确理解技能的关键。3.2 描述层写作这是决定成败的隐藏功很多人觉得技能描述随便写两句就行大模型能看懂。我一开始也这么想直到看到 Agent 把帮我关一下客厅的灯路由到了查询电费账单的技能上我才开始认真研究描述层的写法。经验总结下来好的技能描述需要遵循几个原则第一开头一句话点明技能职责说清楚这个技能做什么。第二第二句话写清楚触发场景罗列常见的用户表达方式。第三必须写负面约束明确什么时候不要用这个技能。第四参数描述要写怎么从用户话术中抽取尤其要说明什么情况不能抽。举我踩过坑的真实例子最早我写查天气的描述是查询天气信息结果 Agent 在用户聊到今天适合穿什么时也会调用它因为这句话里没有天气两个字。改成查询指定城市当前天气情况以及温度、降雨概率等。当用户询问天气、温度、是不是要下雨、空气怎么样时使用。但用户询问穿衣建议、出行建议时不使用这属于建议类技能之后误调率才降下来。参数抽取也要写清楚。比如城市参数我会在 description 里写必须是用户明确提到的城市名如果用户说家里或我这里不要默认取北京而应追问用户位置。这句话是为了防止 Agent 自己脑补参数值。3.3 执行层实现技能核心逻辑的通用模板描述层定义好了执行层就是把 JSON 参数变成实际动作。每个技能的执行层我建议统一遵循同一个模板便于后续维护def get_weather_executor(parameter: dict, context: dict) - dict: # 第一步参数校验 city parameter.get(city) unit parameter.get(unit, celsius) if not city: return {error: missing_parameter, message: 缺少城市参数} # 第二步业务执行 try: result weather_api.query(citycity, unitunit) except WeatherAPIError as e: return {error: api_error, message: f天气服务异常: {str(e)}} # 第三步结果整理 return { code: 0, data: { city: city, temperature: result[temp], condition: result[condition] } }模板里有几个约定要说一下。返回结构统一带上 code 和 datacode 为 0 表示成功非 0 表示各类错误。这样 Agent 在执行完技能后可以快速判断结果是否可用失败时把 error 信息拿给用户看或者转给其他技能处理。context 参数是一个运行时上下文对象里面装着用户 ID、会话 ID、历史消息摘要、共享存储句柄等。这个 context 由 Agent 运行时框架注入技能本身不需要自己管理会话状态也禁止直接把东西写进全局变量——否则两个用户同时在用互相串数据就麻烦了。3.4 技能注册与加载机制技能写好之后怎么让 Agent 运行时发现它们我采用的方案是一个中心化的技能注册表。每个技能在开发完成后需要向注册表提交自己的 JSON Schema 和执行器函数入口。注册表本质上就是一个目录结构加一个索引文件我把所有技能定义放在 skills/ 目录下每个技能一个子目录里面包含 skill.json描述、参数和 main.py执行器。启动时注册表遍历目录把所有技能加载成一个字典key 是技能名value 是对应的执行函数和描述信息。def load_skills(base_dir: str ./skills) - dict: skills {} for skill_dir in Path(base_dir).iterdir(): if not skill_dir.is_dir(): continue config_path skill_dir / skill.json main_path skill_dir / main.py if not config_path.exists() or not main_path.exists(): logging.warning(fskill {skill_dir.name} 缺少配置或主文件已跳过) continue config json.loads(config_path.read_text()) module importlib.import_module(fskills.{skill_dir.name}.main) skills[config[name]] { config: config, executor: module.executor, } return skills这里有个经验技能模块用动态导入加载不要一次性把所有技能代码 import 进来。因为技能可能依赖不同的第三方库动态导入可以在单个技能出问题时不拖垮整个 Agent 进程。加载失败时我会打日志让 Agent 运行在部分技能不可用的降级模式下而不是整个系统崩掉。3.5 参数抽取与校验的工程细节技能定义里的 parameters 就是给参数抽取用的。具体来说Agent 接到用户请求后会把用户的话术结合技能描述尝试生成一个符合 JSON Schema 的参数对象。这个过程我建议单独做一步而不是让执行器内部再做一次解析。工程上的典型流程是第一步Agent 决定使用哪个技能。第二步根据该技能的 parameters schema从用户消息中抽取参数。第三步用 jsonschema 库做一次程序化校验看看抽出来的参数符不符合定义。第四步校验通过传给执行器校验失败让 Agent 根据校验错误信息补充追问用户。import jsonschema def extract_and_validate(user_message: str, skill_config: dict): extracted agent_extract_params(user_message, skill_config[parameters]) try: jsonschema.validate(extracted, skill_config[parameters]) return extracted, None except jsonschema.ValidationError as e: return None, str(e.message)这里有个容易忽略的点jsonschema 校验的报错信息直接拿给用户看是看不懂的。比如xxx is not of type string用户哪知道你在说什么。所以我做了一个映射层把常见的校验错误翻译成用户能懂的话您还没有告诉我要查询哪个城市请补充一下城市名称。Agent 会把这句翻译后的内容组合进自己的回复里实现自然的追问。4. 工具选型与运行架构让 agent-skills 跑起来的配套生态4.1 Agent 运行框架怎么选单独的 skill 只是零件要把它们组织成一个完整运行的 Agent还需要一个运行框架。当前生态里可选的有 LangChain、LlamaIndex、AutoGPT 这类开源框架也有 Bedrock Agent 这类托管服务。我的建议是如果你的技能数量和业务复杂度都不高直接用在框架里做简单的 RAG 工具调用就行不用引一堆依赖。如果你的技能系统会发展成一个几十个技能的复杂网络那请认真考虑框架只是胶水这个定位——核心的调度逻辑、状态管理、技能注册表你自己维护框架只负责提供大模型调用和基础的链式执行能力。我自己曾经在一版项目里重度依赖 LangChain 的 Agent Executor结果发现把自定义技能塞进它的规范的额外一层适配逻辑整个项目的复杂度翻倍。后来我改为自己管理技能调度框架只负责 LLM 调用和 memory结构反而清晰了很多。4.2 上下文中技能描述的动态裁剪一个实际工程问题技能多了之后把所有技能描述全部塞进 prompt 会爆 token。目前 GPT 类模型的上下文窗口虽然越来越大但描述塞得越多Agent 的注意力就越分散选择准确率下降。我的方案是做一个候选技能召回层。每次用户请求进来先用一个轻量分类器或者就是关键词匹配加 embedding 相似度从前几十个技能里召回五六个候选再把候选技能的完整描述塞进 Agent 的上下文。def recall_skills(user_message: str, all_skills: list, top_k: int 5): # 用 embedding 计算用户消息与技能描述的相关性 msg_vec embed(user_message) scored [] for skill in all_skills: desc skill[config][description] desc_vec embed(desc) score cosine_similarity(msg_vec, desc_vec) scored.append((skill, score)) scored.sort(keylambda x: x[1], reverseTrue) return [s[0] for s in scored[:top_k]]这一步替代了把所有技能描述都塞进去是技能规模扩大后必须做的一个优化。召回层本身可以用很多方式实现我测试过纯 embedding 相似度的效果搭配上规则关键词加权在几十个技能的场景下命中率已经能到 90% 以上。4.3 工具函数与外部 API 的处理规范技能执行层经常要调外部 API。这块我有一套固定的处理规范对排查问题时特别有帮助。第一所有外部 API 调用必须走一个统一的 HTTP 客户端这个客户端统一管理超时、重试、鉴权。超时时间默认设 10 秒外部服务不稳定时技能不应让用户等太久。第二每个技能要定义自己的错误码映射表比如服务商返回 500 就映射成 error: api_unavailable, message: 服务暂时不可用。第三调用外部 API 的密钥绝对不能硬编码在技能代码里统一从环境变量或密钥管理系统读取。这套规范看着繁琐真正出问题的时候能救命。我遇到过某个外部 API 突然改版返回结构变了如果每个技能各自处理错误绝对会出现同样的错误在不同技能里表现各异排查起来想砸电脑。统一规范之后一个日志就能看出所有外部调用的状态分布。4.4 可观测性技能调用链路的日志与监控agent-skills 体系一旦跑起来调试的难度远高于普通后端服务因为中间隔着大模型的自由发挥这一层。为了能定位问题我从一开始就给技能调用做了全链路日志。每次技能调用的日志至少包含用户请求原文、Agent 选择了哪个技能、抽取出的参数 JSON、执行返回结果、耗时、错误信息。日志统一打到结构化日志系统用 request_id 串起用户请求 → 技能选择 → 参数抽取 → 执行结果的完整链路。这里有一个我踩过的大坑早期我以为把日志打印出来就行结果排查为什么 Agent 选错了技能时发现根本看不到 Agent 当时的完整上下文没法复现它的决策过程。后来我把每次请求发送给大模型的完整 prompt包括系统提示词、技能描述、历史消息都留档存储排查问题时直接回放效率一下子高了很多。5. 常见问题与排查技巧实录5.1 Agent 选错技能先看描述再看召回选错技能是 agent-skills 开发中最常见的问题但很多人一上来就怀疑模型能力不行。按我的经验80% 的选错问题出在技能描述上。排查套路是这样的第一步把那次误选请求的完整日志调出来看 Agent 实际选择了什么技能、以及它当时看到了哪些候选技能描述。第二步对比误选技能和正确技能的描述看语义边界是否足够清晰。第三步针对模糊点修改描述反复验证。实测中负面约束是最容易被忽略、但对准确率提升最明显的。我甚至见过一个案例某个技能加了当用户只是闲聊时不要使用本技能这句话之后误调率直接砍半。5.2 参数抽取错误别让 Agent 脑补参数参数抽取出错是第二高发问题。典型表现是Agent 明明不知道用户的某个信息却自己编了一个默认值塞进去。比如用户说帮我订一家明天晚上的餐厅Agent 调订餐技能时连人数都给抽出来了而且是2 人。这属于 Agent 在脑补。解决办法有两个层面。第一个层面在参数 schema 里把非必填参数标清楚并写明如果用户未提及不要猜测。第二个层面在执行层增加参数校验发现关键参数缺失时不直接报错而是返回一个需要追问的信号让 Agent 向用户补充提问。5.3 技能执行超时区分等待型和轮询型任务有些技能调用外部服务响应慢是常态比如生成图片、跑数据分析。直接同步等待会把整个 Agent 卡住用户体验极差。我的处理方式是区分等待型任务和轮询型任务。等待型任务比如查数据库设置硬超时超时后返回错误。轮询型任务比如生成图片先返回一个任务已提交正在处理中的信号同时给一个任务查询句柄Agent 可以把句柄存起来稍后通过另一个技能查询结果。5.4 技能维护清单我每周要做的事最后分享一个我自己的技能维护流程。每周我会抽一个固定时间做技能体检第一翻看本周所有技能调用的日志找出调用失败率最高的几个技能逐一排查。第二收集 Agent 选择技能的置信度数据置信度低但最后结果正确的看看是不是描述写得太模糊。第三和业务方对一遍需求看看有没有新增的需求其实可以复用已有技能没必要新增。这个流程听起来简单坚持做下来会发现技能系统的稳定性会持续改善。很多人把技能写出来能用就扔一边结果过两个月某个技能的行为早就变异了也没人发现等到用户投诉才追查就太被动了。6. 对 agent-skills 未来演进的一点个人判断技能生态一定会从单体助手走向多 Agent 技能市场的模式。一个 Agent 不可能拥有所有技能就像一个人不可能掌握所有职业能力。未来会有大量垂直技能的提供方把自己打磨好的技能上架到技能市场业务方按需组合订阅。这带来的新挑战是技能互操作标准。目前各家技能定义格式五花八门换个框架就要重写。我判断未来两三年内会有一个相对通用的技能描述规范跑出来类似于 OpenAPI 之于 REST API 的地位。做 agent-skills 的团队现在开始就向标准化描述 通用执行接口的方向靠拢未来迁移成本会低很多。另外一点是关于技能的自进化。现在的技能还是静态的定义好了就固定不变。未来更理想的形态是Agent 在执行任务中遇到新场景能自动生成新技能的草稿经过人工审核后注册进技能库。这个方向我目前只是碰了碰边缘尝试让 Agent 在失败时生成技能改进建议实测下来部分场景是有效的但距离完全自动化还有距离。不过大方向我很确定技能系统一定是从人写技能给 Agent 用演进到Agent 帮人生产技能的。