做Agent开发这一年多我最大的感受是模型能力的天花板早就不是推理水平了而是它手里有没有趁手的技能。同一个开源模型只给它对话能力它就是个聊天机器人给它配上检索、计算、自动化脚本这些技能它就能变成能帮你干活的数字员工。今天想好好聊聊agent-skills这个话题也就是Agent技能体系的搭建。这篇文章不是什么高深的理论而是我自己从零到一把一个Agent项目跑起来在技能设计、代码实现、问题排查过程中攒下来的一手经验。适合正在做AI Agent应用开发、或者准备把大模型接到实际业务流程里的朋友可能你已经看过LangChain、LlamaIndex这类框架的文档但对“技能到底该怎么设计”这件事还是一头雾水那这篇文章应该能帮你避开不少坑。1. Agent Skills到底是什么为什么成了绕不开的关键词1.1 “会聊天”和“会做事”之间差了整整一个技能层大模型刚火起来的时候大家讨论的都是“它能不能写诗”“它能答对多少道题”。但真到了做项目的时候你会发现客户根本不关心这些。客户关心的是能不能自动查一下库存能不能把这份PDF里的数据提取出来填到表格里能不能每天凌晨跑一遍脚本把异常订单捞出来这些需求有一个共同点光靠LLM的文本生成能力完成不了它必须去操作外部系统。而Agent Skills就是你给模型预设好的一系列可调用的操作能力——查数据库、调接口、执行脚本、读写文件全都通过技能的方式暴露给模型。模型在对话过程中根据用户的意图自主决定调用哪个技能、传什么参数然后把结果整合进回答里。可以这样理解大模型本身是一个知识渊博但不会动手的专家Agent Skills就是分配给它的那双手和工具箱。没有技能层模型再聪明也只能“纸上谈兵”有了技能层它才能真的帮你把活干了。1.2 Skill、Tool、Function Calling这几个词到底怎么区分刚开始接触这个领域时我也被一堆术语搞得头晕Function Calling、Tool Use、MCP、Agent Skills好像都在说同一件事又好像各有侧重。根据我的理解它们其实是不同层面的东西。Function Calling是模型厂商如OpenAI、Anthropic提供的一种模型能力模型可以输出结构化的函数调用指令而不是纯文本。Tool是应用层对可调用能力的统称一个Tool可以是一个API函数、一段脚本、一个SQL查询器。而Agent Skills是我个人更愿意采用的组织方式——它不是单个函数而是把函数、调用说明、参数约束、前置条件、错误处理、示例打包成一套完整的“技能单元”。打个比方Function Calling是模型会说“我要开灯”的能力Tool是那盏灯的开关Agent Skills则是一整套“通过自然语言控制房间灯光”的方案——包括开关在哪、什么情况开什么灯、灯坏了怎么报错、有没有备用方案。三层各有分工缺一不可。1.3 技能层解决的核心痛点模型与真实世界的连接我在项目中依赖Agent Skills最核心的原因是它解决了三个痛点。第一模型永远是“无状态的”它记不住上一次调用发生了什么更不知道外部系统的实时状态。有了技能层模型可以通过查询类技能获取最新数据再基于真实数据做判断而不是靠训练时的旧知识在编。第二模型的输出有随机性直接让它生成SQL去查数据库十条里有两条语法有问题。通过技能封装把SQL提前写好模型只需要填几个参数错误率能降到接近零。第三业务逻辑要沉淀。开发一个订单管理系统判断“这个订单要不要人工介入”的规则你可以在系统里写死但更好的方式是把判断逻辑做成技能让模型结合上下文综合判断。业务规则后续要变只需要调整技能内的逻辑不需要改动模型本身。2. 技能体系的分层设计先搭框架再写代码2.1 基础技能把原子操作封装成积木块在动手写第一个技能之前我踩过一次挺深的坑当时接了一个AI客服项目我一股脑把后端十几个接口全写成技能丢给模型结果模型经常在多个技能之间犹豫不决响应速度也慢得离谱。后来我痛定思痛开始给技能做分层设计。首先是基础技能层它对应的是“不可再拆分的原子操作”。比如查询订单状态、读取用户信息、计算两个日期差几天、给指定用户发送一条验证码这些都是基础技能。设计原则是一个技能只做一件事且这件事的结果要能被明确描述。如果某个操作特别复杂比如“处理退款”那就不该是基础技能因为它涉及资质校验、金额计算、库存回滚等多个步骤。基础技能的最典型特征是“无状态、可复用”。它不关心这次调用是不是第二次不关心是哪个场景在调用输入固定的参数就返回固定的结果。就像乐高积木里的标准块单看很朴素但它是上层一切复杂结构的地基。2.2 组合技能用编排把积木搭成流水线基础技能解决“单个动作”的问题但实际业务需求往往是多步骤的。比如用户问“我那个退款什么时候到账”正确流程是先查订单状态再查退款单状态然后结合支付渠道的到账规则最后生成一句自然语言回复。如果让模型自己做任务拆解模型确实可以做到——但每次都要重走一遍思考链路既慢又不稳定偶尔还会漏步骤。组合技能就是把这些稳定流程固定下来内部预设好步骤顺序外部暴露一个意图接口。模型看到用户的问题只需要触发“查询退款进度”这个组合技能技能内部自动依次调用基础技能最后把结果汇总返回。用工程术语来说就是从“自由编排”变成“模板编排”适用高概率场景能极大节省模型的推理时间。但也有一个陷阱值得留意组合技能不能过度设计。我见过有人把流程编排得非常深技能里面套技能套了三层。一旦底层某个技能报错错误信息层层传递排查起来非常痛苦。组合技能的层级建议控制在两层以内除非有很强的复用需求否则别为了“优雅”牺牲可维护性。2.3 领域技能把行业经验沉淀成专家包比组合技能再高一层的是领域技能。它通常是面向特定业务场景的“专家包”把某个行业或某个垂直领域里经常用到的基础技能、组合技能、规则引擎、领域数据聚合在一起形成一套开箱即用的能力集合。举个例子我做过一个电商客服的Agent项目它的领域技能“售后处理包”就包含订单查询、退款计算、物流追踪、话术模板、以及一系列业务规则比如“签收超过7天不能无理由退款”。外部接入方不用关心售后流程如何拆解只需要引入这个领域技能包模型就自动获得了一套完整的售后处理能力。领域技能的粒度取决于产品定位。如果你做的是垂直行业Agent领域技能就是你的护城河如果你做的是通用助手领域技能则需要谨慎定义否则技能数量膨胀到最后光是维护文档就能耗尽所有精力。我的经验是领域技能宁可面向一个非常具体的场景做厚也不要面向一类模糊的场景做宽。2.4 技能注册表帮你管好会越来越多的技能当技能数量超过十几个之后你一定会遇到“模型调错技能”或者“技能描述写得很像”的尴尬。我后来的做法是引入技能注册表Skill Registry用一个配置文件或数据库统一管理所有技能技能ID、名称、描述、所属分层、输入参数Schema、访问权限、调用计数、平均耗时。这个注册表的价值在实际运营中会被无限放大。你会突然发现某些技能从来没被调用过而某些技能调用量占比80%那后面做性能优化和模型微调就都有了数据支撑。它还解决了权限控制的问题基础技能可能只允许内部调用领域技能需要过一层鉴权这在注册表里可以统一配置。不要觉得这层设计是过度工程等你被“技能太多无所适从”的现实狠狠教训过就会明白提前管理的重要性。3. 核心实现细节决定技能好坏的3个关键点3.1 技能描述写给模型看的说明书别写给人看如果你真的亲手写过Agent应用肯定有过这种体验同一个技能描述措辞改一版模型调用准确率从50%直接跳到90%。技能描述不是文档它本质上是一段“面向大模型的prompt”需要精心设计。我在写技能描述时遵循三条经验。第一开头两句必须讲清楚“这个技能能帮用户解决什么问题”而且要用用户的语言。比如“根据订单号查询订单的实时物流状态返回已签收/运输中/待发货等状态信息”而不是“订单查询接口”。第二凡是用户意图可能与技能沾边的地方都要写明边界。比如订单查询和物流查询是两个技能就要在各自的描述里注明“如果用户问的是物流的速度和预计到达时间请调用物流查询技能而不是本技能”。第三描述里可以嵌入“触发词”提示例如“当用户提到物流、快递、签收、派送等词时优先考虑此技能”这能明显提升召回率。还有一个小技巧是给模型提供一个调用示例Few-shot直接在技能描述的末尾附上一段示例对话或示例参数值。模型的上下文学习能力会参考示例的格式来生成调用参数规范效果立竿见影。3.2 参数设计能少则少能约束就别放养很多开发者在设计技能参数时习惯性地把后端接口的所有入参一股脑暴露给模型这是一个新手的经典错误。模型不是专业的API调用者给它太多无关参数它会迷茫会增加无效推理和错传概率。参数设计有一条黄金法则模型侧暴露的参数越少越好其余参数由技能内部自动补充。比如技能内部有一个request_id要传给后端这个值明明可以自动生成就没必要让模型操心。对于模型确实需要填的参数务必在类型、格式、取值范围上下足功夫。字符串还是要枚举是用标准日期格式还是纯数字如果传错了模型有没有能力自己纠正这些都是需要在定义阶段回答的问题。参数描述也同样重要。在OpenAI的Function Call规范里参数可以带description字段这个字段对模型的影响非常大。比如一个status参数如果只写成“状态”模型传“处理中”还是“processing”就很随机但如果写成“订单状态可选值包括pending待处理/ processing处理中/ completed已完成/ failed失败”模型的准确率一下就上来了。语言模型的底层逻辑是“看到什么就模仿什么”你把约束写得越细它就越不会发挥。3.3 返回结构一切以“模型好解析”为最高优先级技能的执行结果要返回给模型然后模型基于这个结果生成用户可读的回复。很多人在这个环节忽略了“返回结构的设计”导致模型需要做大量的后处理既慢又容易出错。我的建议是技能返回结果一律使用结构化JSON并且保持字段命名的语义清晰、层级平坦。尽量避免嵌套过深的JSON模型虽然处理JSON的能力不弱但嵌套越深出错概率越高。更要注意的是返回的“错误表示方式”不要有的错误返回{error: xxx}有的错误返回{code: 500}有的错误直接抛异常。统一错误结构比如一律返回{success: false, error: {...}}模型遇到错误时才能稳定地走同一条处理分支。此外返回的内容应该尽量“精加工”而非“生数据”。查询到物流轨迹原始JSON可能包含轨迹更新时间和各个节点名称最好在技能内部就完成排序、格式化直接给模型一个流畅的文本段落加结构化数据。模型擅长理解和转述但不擅长做数据清洗技能要做模型的好帮手而不是把脏活累活丢给它。4. 从零搭建三个典型技能完整实操记录4.1 技能一系统状态查询读类型我们从一个最简单的读类型技能开始查询部署服务的健康状态。这个技能会去调用一个内部运维API拿到各服务的运行状态和最近5分钟的请求错误率然后返回结构化结果。from typing import Annotated from pydantic import BaseModel, Field class ServiceStatusInput(BaseModel): service_name: Annotated[str, Field( description服务名称可选值api-gateway / user-service / order-service )] api-gateway def check_service_status(params: ServiceStatusInput) - dict: 查询指定服务的实时运行状态包括进程存活情况、最近5分钟的请求量与错误率。 当用户询问系统健康、服务可用性、服务异常、请求错误率时调用本技能。 # 实际项目中这里会调用真实的运维API这里做简化演示 result fetch_ops_data(params.service_name) return { success: True, data: { service: params.service_name, alive: result.get(alive), error_rate: result.get(error_rate), qps: result.get(qps), last_check_time: result.get(timestamp) } }这个技能的关键点有三个。第一service_name参数使用枚举约束模型就不会传一个不存在或格式不规范的名称。第二描述里写了触发场景“系统健康、服务异常”模型遇到这类问题时召回率明显提高。第三返回值alive、error_rate都是模型能直接看懂的字段不需要二次解析。对于读类型技能还有一个隐含要求是返回数据的时效性。模型本身没有实时信息技能必须确保每次调用都返回最新数据千万不能在技能层做数据缓存。哪怕只缓存5秒遇到线上事故排查时你给模型送一个过期状态误导性非常大。4.2 技能二批量数据计算计算类型第二个技能更像“给模型装上计算器”读取一份销售明细文件的CSV按指定维度做聚合统计后返回结果。这种技能很适合用来处理“帮我算一下这个月各渠道的销售额”这类需求。import pandas as pd from typing import Annotated from pydantic import BaseModel, Field class SalesStatsInput(BaseModel): file_path: Annotated[str, Field(description销售明细CSV文件的路径格式为 /data/sales/2025/xx.csv)] group_by: Annotated[str, Field(description聚合维度可选值channel(渠道) / category(类目) / region(区域), defaultchannel)] def calc_sales_stats(params: SalesStatsInput) - dict: 读取销售明细文件按指定维度计算销售额与订单量。 当用户需要统计维度对比、销售额汇总、渠道排行榜时调用本技能。 try: df pd.read_csv(params.file_path) result df.groupby(params.group_by).agg( total_sales(amount, sum), order_count(order_id, nunique) ).reset_index() return { success: True, data: result.to_dict(orientrecords) } except FileNotFoundError: return { success: False, error: {message: f文件不存在: {params.file_path}} }这个技能体现了计算类型技能的两条重要经验。第一错误处理要前置文件可能不存在、列名可能对不上、数据可能为空这些都要提前预判并返回结构化错误不要光秃秃抛一个异常让模型自己猜。第二group_by字段要有默认值这样模型在“算一下销售额”这种模糊需求下也能成功调用不会因为参数不齐全而卡壳。可能有人会问既然模型也会做简单的求和统计为什么要专门封装这样一个技能原因很简单模型的数学能力在小样本上看起来没问题一旦数据量变大、维度变多它要么算错要么偷偷省略数据要么速度慢得让人崩溃。用代码做计算精度和速度都是确定性有保障的模型的价值在于理解需求、传达结果而不是来做计算器。4.3 技能三生成工作日报组合类型第三个技能展示的是组合技能的价值。这里有一个办公场景每天早上项目经理问Agent“今天有什么待办”Agent需要汇总多个来源的信息整理成日报。def generate_daily_report(user_name: str) - dict: 汇总用户当日的会议安排、重点任务、未读消息生成一份结构化工作日报。 当用户提到日报、今日安排、今天要做什么、当日工作重点时调用本技能。 # 1. 调用基础技能获取今日日程 events fetch_calendar(user_name) # 2. 调用基础技能获取任务列表 tasks fetch_todo_list(user_name) # 3. 调用基础技能获取未读消息摘要 messages fetch_unread_summary(user_name) # 4. 内部整合 report { date: datetime.now().strftime(%Y-%m-%d), events_count: len(events), task_count: len(tasks), first_task: tasks[0] if tasks else None, top_message: messages[0] if messages else None, } return {success: True, data: report}组合技能在实现上的核心是“内部编排要固定外部入口要极简”。对模型来说它只需要知道“生成日报”这一个入口至于日报怎么拼装、优先级怎么排那是技能内部的事。这样做的好处是模型每次调用生成的日报格式是一致的不会这次先写日程下次先写消息。生产环境里这类组合技能往往还会再接上一个“输出策略层”比如根据报告内容决定是否推送一条提醒、是否需要人工复核。这就不只是技能调用了已经是Agent自主工作流的一部分。但原理不变从稳定流程出发把每一步做扎实。4.4 技能上线前有哪些必做的验证技能写完不等于能用我这里有一套成本不高的验证流程推荐你直接拿去用。第一轮是单元冒烟测试直接调用技能函数用几个典型的合法参数和非法参数各跑一遍确认返回结构符合预期。非法参数测试尤其重要因为模型是“不按套路出牌”的它真的可能传一个空字符串或超长文本进来。第二轮是模型级联调在真实的LLM对话环境里发起几类自然语言请求观察模型是否在正确的时候调用技能、参数是否传对、返回结果模型是否能正确转述。第三轮是回归脚本把历史用户的真实问题整理成测试集每次技能改动都跑一遍确保修复一个bug没有带出新的问题。这轮流程的灵感来自传统软件开发里的单元测试和回归测试。做Agent项目很容易陷入“每次调试都靠人工聊几句”的野路子效率极低而且改一处坏一处。把验证固化下来是Agent项目工程化必须迈过的一道门槛。5. 常见问题与排查技巧实录5.1 模型就是不调用技能怎么回事这是我在项目里被问过最多的问题。现象是用户问了一个明显可以用技能解决的问题但模型却自己凭空编了一个答案。排查路径一般分三步。首先检查技能描述里是否缺少“触发暗示”。描述要和用户的语言习惯匹配如果你在技术文档里把这个能力叫“SKU查询”而用户问的是“这个有货吗”模型就很难把两者关联起来。在描述里加上“当用户询问是否有货、库存情况、现货状态时调用本技能”问题往往会立刻消失。其次检查参数Schema是否过严。模型可能识别出了技能但看到必填参数有4个而用户只提供了2个它不确定剩下的怎么填于是干脆放弃调用。这时候要么给非关键参数设置默认值要么让技能支持缺省参数的预设值逻辑。多给模型一条可以走的路它就不会绕路。最后还要检查是不是有别的技能“截胡”。如果模型觉得另一个技能也能解决同样问题而那个技能的描述更清晰它就会选择后者。把所有技能打印出来想象自己是一个LLM看看哪一版描述更明确就能定位问题。5.2 参数总是传不对问题出在哪如果确认模型已经调用了技能但传参经常出错比如日期格式写成“明天”、字符串里带emoji、数值传了单位那问题基本都出在参数定义上。排查方向有两个约束是否写清楚了示例是否给了模型对参数的理解完全依赖于Schema里的描述你期望它传什么就必须把它没见过、没被约束过的情况都写明白。日期参数明确告诉它“必须是YYYY-MM-DD格式的字符串”数值参数告诉它“必须是不带单位的纯数字”。还有一个很实用的办法把正确参数格式和错误格式各写一遍模型对比示例后通常会自动校准。在工程上参数传错也不应该直接报错导致流程中止。更稳妥的做法是技能内部做一个轻量级参数归一化比如把“明天”自动换算成具体日期把金额里的逗号和小数点统一格式。技能要像一个大厨——即使客人点菜时表述不严谨你也可以根据常理把菜做对。5.3 技能冲突与上下文膨胀的处理技能数量多了以后会遇到两类比较棘手的问题。一类是技能语义重叠导致模型随机选用。解决办法是重新梳理技能边界把重叠的部分合并或拆分同时在描述里互相做“排除性说明”。比如“A技能处理的场景不包括物流信息物流信息请调用B技能”。这看起来很笨但实测效果非常好。另一类是上下文膨胀。现在主流Agent框架都会把技能描述拼进系统提示词里技能几十个以后系统提示词可能超过令牌上限或者虽然没超限但挤占了正常对话的上下文空间。我的应对经验是按需注入根据对话历史先用一个轻量级分类器粗筛技能集合只把最可能被用到的10个左右技能的描述注入系统提示词。这套做下来响应延迟和调用准确率都有明显改善。5.4 安全边界技能不是越强越好做技能设计时不能光想着“能干什么”更要考虑“不应该干什么”。技能权限最小化是底线查询类技能不能带写库权限写操作类技能必须要过一层鉴权和审批。尤其是那些能执行脚本、能操作文件系统的技能一旦被恶意prompt注入利用后果不堪设想。我的经验是给每个技能标注一个“风险等级”。低风险是纯读操作可以直接调用中风险是写操作但影响有限比如发送一条通知需要用户确认高风险是删除、转账、修改配置这类不可逆操作必须在技能内部生成一个“操作确认单”让用户明确读了确认后再执行。把这个机制做进技能框架里而不是靠模型自觉是Agent项目上线前必须补上的安全短板。6. 写在最后这是我持续在踩但也一直在改进的方向技能设计这件事看起来是一堆工程细节但本质上是在做“模型能力”与“复杂真实世界”之间的适配层。我越做越觉得Agent开发的胜负手不在于模型选得多好而在于你愿不愿意花时间在每一个参数约束、每一段技能描述、每一次错误处理上死磕。好的Agent给人的感觉是“它真的懂我需要什么”而这背后往往不是一个超强的模型而是一个把大量现实情况都预埋好的技能系统。我自己现在还在持续迭代的方向是把技能从“被模型调用”逐步升级到“能主动触发”。也就是说模型不一定要等用户问而是在监测到某些条件成立时自动调用技能。比如看到日历上有冲突的会议自动去查参会人的空闲时间并提出调整方案。这个方向对技能设计的要求更高但也让我越来越接近我理想中的Agent形态不是问答机器人而是一个靠技能系统驱动、真正能自主完成业务闭环的数字同事。对这些内容感兴趣的朋友强烈建议从今天提到的分层设计、参数校验、按需注入这几个点入手回去盘一盘你自己的技能库大概率能发现不少可以优化的地方。