“Agent不是聊天机器人Agent是一套能干活儿的系统。”——这是我最近把几个内部项目改造成Agent架构之后最想对所有人说的一句话。过去半年我一直在折腾agent-skills这套技能体系从最初的应急脚本到后来成建制的技能库再到现在的多Agent协作框架可以说把这块从里到外踩了个遍。这篇文章不打算讲那种“教你三天造一个智能体”的速成课而是想以一个实践者的身份聊聊agent-skills到底是什么、为什么需要它、怎么把它落地成可维护、可复用的工程能力。我会把核心原理、实操步骤、踩坑记录都放进来适合已经接触过Agent、准备把它推向生产环境的开发者也适合那些对“Agent能不能真正解决业务问题”抱有怀疑态度的技术负责人。1. 内容整体设计与思路拆解1.1 为什么单独的模型能力解决不了实际问题先说个很扎心的观察很多人拿到一个GPT级别的模型第一反应是“我什么都能问了”但真到了业务场景里模型只能给你“建议”不能替你“执行”。你可以让模型写一段营销文案但你不能让模型自动把文案发布到公众号后台你可以让模型分析一份财报但你没法让模型自己去查财报、下载PDF、解析表格、算完指标再给你一份带图表的报告。这就是Agent存在的原因——它把模型的理解能力和你系统的“手脚”连接起来。而agent-skills就是那双手脚的“操作手册”。它不是模型本身也不是工作流本身它更像是让Agent在复杂环境里行动的最小功能单元。你给它一个清晰的名称、一段足够明确的能力描述、一个可执行入口和一套输入输出约束Agent就能在推理过程中“看见”这个技能并在合适时机调用它。我踩过最大的坑是把所有逻辑都塞进Prompt里。结果Prompt膨胀到几千行模型每次都要重新“理解”一遍业务流程然后给出五花八门的调用方式。后来我悟了Agent不是靠“脑子”干活的是靠“工具箱”干活的。你给它一百个烂技能不如给它十个精悍、稳定、描述准确的好技能。1.2 agent-skills在整体架构里的定位我在网上看了很多Agent架构图的讨论发现多数人把Agent架构画成了“模型 工具 记忆 规划”的四层结构。这个框架没问题但它太粗了。实践中我的分层方式更细大致是模型层负责推理、决策、生成自然语言内容不直接触碰外部系统。技能层也就是agent-skills的所在层负责封装所有具体可执行动作比如调用订单API、读写数据库、发送通知、执行数据分析脚本。知识层负责给模型提供提示之外的背景信息比如业务术语表、历史决策记录、领域规则这些都是“参考材料”而非“动作”。编排层负责决定“技能怎么组合调用”可以是显式的工作流也可以是模型自由编排通常会和记忆与反思机制配合。把技能独立成层最大的好处是模型无关。你可以今天用模型A做推理明天换模型B做推理技能层不需要改动。这就好比一家公司的行政后勤体系是稳定的换CEO不影响收发快递流程。单位里的分工越清楚整体运转就越稳。1.3 为什么“技能”比“工作流”更适合Agent工作流这个词大家都不陌生很多低代码平台都在做这个。工作流的特点是“预先编排好步骤”比如先拿订单数据再校验合法性再计算价格再生成物流单。它适合业务路径非常固定的场景。但Agent面对的往往是不确定的开放场景——用户的需求千奇百怪你没法提前排列组合所有可能性。技能则不同。技能是“能力原子”没有固定的先后顺序。Agent在收到任务时自主判断需要哪些技能、按照什么顺序调度这些技能、遇到异常时尝试哪些替代技能。这就是为什么技能相对于工作流更能适应动态环境。我打个比方工作流是自动售货机技能是厨房的灶台。自动售货机按按钮就出商品但只能出固定东西你用灶台可以炒任意一道菜完全取决于厨师Agent的心情和判断。所以当我需要构建一个能应对“模糊需求”的系统时正统做法是把业务能力拆碎成技能而不是提前写好一串串指令。项目的核心价值正是把碎片化能力以标准接口的形式沉淀下来让模型可以灵活动用。2. 环境准备与工具选型解析2.1 跑通agent-skills的最基本环境这一节我尽量少谈理想架构多谈落地事实。如果你想复现我这套体系最小需要三样东西一个可以调用外部工具的大模型接口一个能执行Python脚本的运行环境再加一个把技能注册给Agent的框架。我在项目里实际用的是Python 3.10以上版本作为技能执行底座。原因是大部分数据类、文档处理类、网络请求类库都在Python生态里最成熟Debug起来也直观。模型接口我用的是OpenAI兼容格式API这块的好处是你可以在不同模型服务之间切换不必把自己绑死在单一厂商上。至于Agent框架如果你不想从零搭建编排逻辑可以直接用LangChain或自研的轻量调度器但我的建议是即便用了框架技能注册表必须自己维护因为框架给的技能管理往往太黑盒。实际项目里我维护了一个skills目录每个子目录代表一个技能。技能目录下通常包含三样东西skill.md技能描述文件、run.py技能执行入口、config.json技能参数配置。这套约定简单、直观且能天然地和Git配合做版本管理。以后模型换了、框架换了技能文件照样能迁移。2.2 技能定义的核心文件skill.md真正的核心是skill.md。你不要觉得它就是一段说明文字——它是LLM能否正确调用技能的最关键因素。我见过很多人在技能描述上偷懒写一句“从数据库查询订单信息”就算完事结果模型老是把参数传错。我把skill.md的模板打磨了很久现在长这样技能名称: order_query 一句话功能: 根据订单ID或客户手机号查询订单基本信息。 适用场景: 客服咨询订单状态、售后查询物流进度、运营核对订单金额时使用。 输入参数: - 参数名: order_id 类型: string 必填: false 说明: 订单编号唯一标识 - 参数名: phone 类型: string 必填: false 说明: 客户手机号用于模糊查询 输出说明: 返回订单当前状态、支付金额、物流单号。 使用限制: 订单ID和手机号至少填一个查询结果只返回最近30天数据。你别小看这些字段。模型在决定是否调用这个技能时会先在内部把用户的自然语言“翻译”成参数结构。如果技能描述里没有说清楚参数边界模型可能把“手机号”塞进order_id字段或者把查询条件“最近一周”忽略掉。一份好的skill.md等于是在教模型“什么情况下该用我、怎么正确地把参数喂给我”。2.3 工具选型的心得别迷信大而全的框架有一阵子我疯狂收集Agent框架像是要把市面上所有编排框架都试一遍。最后发现框架之间八成功能是重叠的记忆机制、工具调用、Prompt模板、回调系统。真正拉开差距的反而是你对技能体系的理解和精细度。我现在更倾向于一个极简的核心一个技能注册器一个路由函数再加一个执行器。技能注册器负责读取所有技能目录并构建索引路由函数根据用户请求和模型决策找到目标技能执行器负责把参数传进run.py并返回标准化结果。看上去就那么几十行代码但配合上良好的技能设计效果比满配框架顺手得多。框架选型上如果你非要用现成的我建议优先关注支持“技能热加载”的框架。什么叫热加载就是技能文件放进了目录系统不需要重启就能自动识别。这个能力在开发调试阶段极其重要不然每改一次描述文件就要重启一次服务效率太低了。3. 核心细节解析与实操要点3.1 技能描述是给模型看的使用说明书再深化一下skill.md的价值。技术界有一个很有趣的现象给“人”写的说明书和给“AI”写的说明书最大的区别是“AI”会逐字逐句翻字典。它不像人一样能根据上下文自动脑补缺省的信息。所以你给模型看到的每一个字都会被纳入它决策的权重分布。技能描述写得太泛模型就会在模棱两可时倾向于调用写得过于严苛模型又会不敢调用导致Agent只能“空手回答”。一句话功能描述我建议控制在20个字以内并且直接包含“动作 对象”。比如“根据订单ID获取物流轨迹”就比“查询物流信息”好。后者没有说清楚输入的查询键模型极有可能让你传一个客户姓名然后技能执行时报错。适用场景这一段也很关键。你必须明确告诉模型这个技能不适合在什么场景下使用。比如一个订单查询技能如果你不写“只能查已完成订单状态不能查询退款申请进度”模型就可能在用户问退款进度时也去调这个技能返回一个无意义结果。负向约束和正向使用条件同等重要。3.2 参数设计限制大模型的自由度参数设计是另一个容易翻车的环节。我给Agent设计参数时有一条铁律所有参数类型必须尽量用枚举值或严格类型约束不要给模型太多自由发挥空间。比如“查询时间范围”这种参数你不要让它传自由文本而是让它传系统预定义好的固定枚举值诸如“last_7_days”“last_30_days”“today”。这能省掉无数解析脏数据的麻烦。此外参数少即是多。每多一个可选参数模型选错或遗漏的概率就会上升一分。我现在的做法是一个技能最多配5个参数能合并的合并能自动推断的不让模型填。比如技能能从用户身份令牌里自动获取当前用户ID那就没必要让模型额外传一遍“当前用户ID”。这类细节做得好模型调用成功率能明显提升。3.3 执行器设计的通用标准技能的执行器我会统一设计成“输入字典输出字典”的形态。run.py里定义一个main函数接收一个args字典返回一个包含了执行结果、状态码、错误信息的字典。这样设计的好处是Agent框架层不需要关心技能内部逻辑只需要把模型生成的参数转成字典、调用run.py、把返回结果再序列化给模型。就像是把不同技能封装成了统一的USB接口什么设备插上来都能供电。返回结果我建议至少要包含两个字段statussuccess或error和data实际结果内容或错误描述。如果技能执行出错千万不要返回裸的异常堆栈因为模型看到一堆Traceback会懵不知道怎么跟用户解释。你应该在技能内部把错误捕获掉转换成一句人话比如“未找到该订单请确认订单编号是否正确”。模型拿到这句话之后会自然生成一段对用户友好的提示。3.4 技能注册与动态发现机制技能注册机制听起来很高大上其实实现起来很朴素。我在服务启动时扫描skills目录下所有子目录解析每个子目录里的skill.md然后构建一个技能清单列表把清单和对应的调用入口绑定在内存中。当模型需要调用技能时我会把“技能名称 描述信息”拼接进系统提示词里。所以你不需要把每个技能的长篇描述都塞进Prompt只需要塞一个精简版技能摘要完整描述仍然在技能注册表中按需加载。在注册表构建时务必要做一遍技能冲突检测。我碰过的情况是两个技能的功能描述高度重叠模型在决策时犹豫不决导致调用准确率下降。后来我加了规则同一领域内技能描述的前缀不能重复语义相似度超过85%的技能需要合并否则不予注册。这一步让你在技能库膨胀时仍然能保持调度纯净。4. 实操过程与核心环节实现4.1 一个最小可用的技能编写流程我先带你过一遍最短路径。假设你要写一个“汇率查询”技能目标是让Agent根据当前日期查询指定货币对的历史汇率。第一步创建skills/exchange_rate目录里面新建skill.md、run.py和config.json。第二步在skill.md里把技能名称、功能、适用场景、输入输出写清楚。第三步在run.py里实现一个函数接收起止日期和货币对调用一个汇率API返回结果。我把run.py的骨架贴出来你感受一下这种统一接口的写法import json import requests def main(args: dict) - dict: currency_pair args.get(currency_pair, USD/CNY) date args.get(date, 2025-01-01) try: resp requests.get( https://api.example.com/historical, params{pair: currency_pair, date: date}, timeout10 ) resp.raise_for_status() data resp.json() return {status: success, data: data} except Exception as exc: return {status: error, data: f汇率查询失败{str(exc)}}你注意到没有这个函数没有任何Agent框架特有语法就是一个典型的Python函数。这就对了。技能是平台无关的它不应该知道外面是谁在调用它。4.2 参数解析与校验的兜底逻辑刚才那个main函数看起来简单实际生产环境里必须加参数清洗和兜底逻辑。模型传过来的参数经常有三种问题该填的没填、填了不存在的键、值类型不正确。所以我在技能执行前的公共模块里统一做三层校验第一层检查必填参数第二层检查参数类型第三层检查枚举值边界。校验不通过就返回错误状态和提示不让技能进入业务逻辑。REQUIRED_KEYS [currency_pair] OPTIONAL_KEYS {date: str} for key in REQUIRED_KEYS: if key not in args: return {status: error, data: f缺少必要参数{key}} has_pair args.get(currency_pair) if / not in has_pair: return {status: error, data: 货币对格式应为USD/CNY}这些校验逻辑看起来枯燥却直接决定了Agent在生产环境里的稳定性。模型不会因为你底层报错就自动反思它只会拿你给它的错误信息继续“编”解释。所以错误信息务必语义清晰让模型不用二次猜测。4.3 技能编排从单技能到多技能组合说实话单个技能的调用并不难难的是让Agent恰当组合多个技能。我举一个典型的跨技能场景用户想比较两个基金的历史收益并生成一张对比表。这个任务至少涉及三个技能基金基础信息查询、历史净值拉取、数据可视化绘图。Agent需要“看见”这三个技能并按顺序编排先拉两个基金代码再逐只拉历史净值最后把数据整理成图表。在工程上我采用了一种“依赖声明”技巧。技能md里加一个depends字段声明该技能依赖的其他技能名称。模型决策时如果发现目标技能有依赖项就会自动意识到还需要调用前置技能。这就相当于是给技能之间建立了一套“软连接”既不用写死工作流又给模型提供了清晰的行动路径。比如画图技能的依赖可能长这样depends: - fund_net_value_query - fund_info_query模型一看到这两个依赖就不会只调用画图函数然后傻等着数据从天上掉下来。这个技巧让我从“经常缺少上下文数据”的坑里跳出来了。4.4 技能错误处理与重试机制技能执行失败是家常便饭网络抖动、参数不合法、下游服务故障都可能发生。如果你的Agent对失败没有处理策略用户就会得到一句冷冰冰的“系统错误”体验很糟糕。我设计了一套三级失败处理机制第一级技能内部自行捕获异常返回可读的错误信息第二级Agent框架根据错误信息判断是否重试通常对于超时类错误会重试一次第三级如果重试仍然失败Agent会调用一个“降级预案技能”比如“人工客服转接”或“缓存数据返回”。这套机制落地后系统可用性从最初的94%提升到接近99%。做Agent落地时最怕的就是“看起来聪明、用起来拉胯”。错误处理在传统软件工程里是必修课在Agent工程里是保命符不可省略。5. 常见问题与排查技巧实录5.1 问题速查模型为什么总不调用技能这是被问得最多的问题。模型不调技能可能的原因有不少我整理一个速查表现象可能原因排查方向模型完全无视技能列表Prompt里技能摘要太长模型上下文被淹没精简技能摘要控制在200字内突出能力名称模型知道技能但不愿用技能适用场景描述和用户意图不匹配检查技能描述是否过度限制适用边界放宽触发条件模型持续报参数错误技能描述里的参数说明不清晰参照3.2节给参数加严格类型和枚举约束翻新描述模型调用技能但返回空技能内部异常或API返回未按标准格式包装检查执行器是否统一返回status和data字典同一技能被频繁误用技能间功能边界模糊描述重叠做技能注册冲突检测合并相似技能我见过太多人遇到“模型不调工具”就立刻怀疑模型能力结果换了更大的模型依然不调。其实问题九成出在描述工程上。你花半小时把“技能说明书”重写一遍比换模型快得多。5.2 排查实录一次“查得到订单但查不到退款”的问题有一次做客服Agent用户问“我的退款到哪一步了”Agent总是返回“订单已发货”。排查后发现客服查询技能只能查订单状态根本没有退款进度字段。问题是模型看到“退款”两个字时关联到了最接近的订单查询技能就调用了。这个问题的根因不是描述不清而是缺少“退款进度查询”技能。我把这个场景单独拆了一个技能补上合适的描述模型立刻就能分辨两种诉求了。这个案例告诉我们当你发现Agent反复用一个不太合适的技能时先别急着调Prompt先想想是不是技能粒度太粗了。技能拆得越细模型就越容易命中正确的动作。5.3 排查实录参数幻觉导致的脏数据另一个印象深刻的坑是参数幻觉。用户问“我上周的订单”模型调订单查询技能时把date参数传成了“上周”。技能内部解析date为字符串直接拼进SQL结果数据库报错。后来我给所有时间类参数接了一层标准化解析器把“上周”“最近三天”“上个月1号”这类人类化表达统一换算成具体日期范围。模型负责表达意图技能负责翻译意图。既然模型已经尽力了剩下的不确定性就该在技能侧消化掉。5.4 技能生命周期管理更新、废弃与灰度技能和代码一样也会老化、被替代。我维护了一个技能生命周期状态机开发中、可用、已废弃。已废弃技能不会直接从注册表删除而是标上废弃原因和建议替代技能并保留一段时间再下线。模型在调用时注册表对“已废弃”技能返回“请改用XX技能”规避了老技能引用的兼容性问题。另外一个很实用的经验是灰度发布。新技能刚上线时我都会先在一个小流量实验环境里跑两天记录模型调用成功率和用户反馈分数再决定是否全量开放。没有这个验证期你永远不知道哪些技能描述是真懂模型哪些只是你自以为懂。5.5 可观测性给Agent装一个监控仪表盘Agent服务的可观测性比传统服务更重要。传统API的失败是确定性的Agent的失败则充满不确定性。同一个Prompt可能今天成功明天失败同一技能可能在一种语境下表现好、在另一种语境下一塌糊涂。我项目里给每个技能都埋了监控指标调用次数、成功率、平均延迟、返回错误类型占比。模型每一次调用记录的辅助数据也会入库包括它看到的技能列表、它选择的技能、它构造的参数。这些日志最大的价值是复盘。每当Agent表现不佳我第一件事是翻调用链还原模型当时的决策上下文。没有这套观测体系所有优化都像盲人摸象。真正的工程化Agent不是靠写更多Prompt而是靠不断从反馈数据中修正技能设计。6. 技能体系的边界与扩展方向6.1 技能不是银弹什么场景不适合得泼一盆冷水技能体系不适合所有问题。如果业务场景是固定套路、循环往复的老老实实用工作流引擎反而更稳、更快。技能体系的优势是应对不确定性代价是增加推理开销和调试复杂度。你让模型每次都要摸索技能调用路径在小规模场景下是杀鸡用牛刀。另外技能也不适合作为复杂业务规则的载体。假设计费规则有三十多个分支、每个分支还要对接不同策略这类状态机逻辑塞进技能里调试会让你崩溃。正确的做法是把复杂规则下沉到后台服务技能只保留一个“计算价格”的入口。技能要做的事情是“触发能力”而不是“承载逻辑”。6.2 多Agent协作中的技能复用我在后期的项目里开始尝试多Agent协作每个Agent专注一个小领域比如客服Agent、数据分析Agent、内容生成Agent。技能库变成了共享层每个Agent只把自己关心的技能子集加载进上下文。这里就出现了一个有意思的优化点不同Agent对同一技能的应用视角不同。比如“用户订单查询”这个技能客服Agent使用时关注订单状态数据分析Agent使用时关注订单金额分布。如果只写一份技能描述很难同时满足两种视角。我的解法是技能描述支持多视角标签一个技能可以有多个版本描述注册时按Agent类型选择对应描述。底层执行逻辑完全一样只是“说给模型听的话”不同。这好比同一个员工对外是销售、对内是培训师话术自然不一样。6.3 向通用技能市场演进技能做得多了你会发现很多技能是可以跨项目复用的。比如“发送企业微信通知”“从PDF提取表格”“将数据渲染成图表”这些能力几乎每个项目都少不了。我最近在整理一套内部技能市场把通用能力沉淀成付费共享包。团队之间不用再重复造轮子接入一个技能就像npm安装一个包一样简单。在这个方向上技能描述文件里可以加入更丰富的元信息作者、版本号、依赖项、输入输出示例。甚至可以做技能自动测试——跑一组典型用例看看技能的返回结果是否稳定符合预期。这会让技能体系从“个人经验”走向“组织资产”真正具备工程化的味道。我现在的体会是agent-skills这个方向本质上是在给Agent“建工具箱”而不仅仅是在写代码。你需要像养育一个新人那样对待这套体系持续完善技能文档、优化参数约束、维护技能生命周期。磨刀不误砍柴工你在技能库上投入的每一分钟到最后都会以“更稳的Agent行为”回馈到业务结果上。如果你正要上手Agent项目我建议你从最基础的技能定义做起把一个技能的调用跑通跑顺再加下一个。聚沙成塔这套系统会远比想象中能打。