Agent Skills实战指南：从提示词到智能体技能全链路解析

这个系列写到第 10 期我发现一个特别常见的现象很多朋友已经能熟练地写提示词也跑通了检索增强生成可一旦要让大模型“真正把一件事办成”就卡住了。聊天流利办事拉胯。问题通常不在模型本身而是缺了一层叫Agent Skills智能体技能的东西。简单说技能就是把某一类任务的专业做法打包成一个可调用、可复用、可量化的执行单元让大模型在对话过程中按需调用。它解决的不只是“模型会说什么”而是“模型能做什么”。这一期我不打算泛泛讲概念而是从调用现成技能、自定义技能到性能优化和安全加固的完整链路把 Agent Skills 从入门到进阶一次讲透。如果你已经会写基本的提示词也了解大模型 API 的调用方式这篇内容可以直接落地到你的项目里。1. Agent 技能层为什么大模型有了对话能力还不够1.1 从“能聊天”到“能办事”的关键一跃大模型本质上是一个概率语言模型它最擅长的是把文字接得通顺、接得像样。但它天生不具备稳定执行外部操作的能力——它不会真的去查数据库不会真的去发 HTTP 请求也不会真的去操作系统里的文件。为了防止它“乱来”多数场景下我们限制它只能输出文本。可一旦你希望大模型变成一个能完成实际工作的智能体就必须给它外挂一套“可执行的手脚”这就是技能层存在的意义。我常拿新入职员工打比方一个名校毕业生大模型脑子聪明、表达清晰但没经过岗位培训他不知道你们公司内部系统怎么操作不知道报销流程怎么走也不知道数据库里哪张表才是最新的。技能层就是给他的一本本“岗位 SOP”——每一份 SOP 对应一个具体场景写明“当遇到某类需求时按这个流程去做输入输出长什么样”。所以 Agent 和普通聊天机器人的分水岭就在这里普通聊天机器人只有语言能力而 Agent 在语言能力之外还有一个“可操作的工具箱”并且能根据当前任务自主决定打开哪个箱子。1.2 技能、工具、插件这套概念到底怎么分现在各家平台都喜欢包装新词工具Tool、技能Skill、插件Plugin、函数调用Function Calling经常被混着说。其实它们的本质很接近但在工程上有细微差别理解清楚能避免后续设计走弯路。以下是基于当前主流实现的一套相对清晰的区分方式概念核心含义典型形态侧重点工具函数Tool / Function一个可以被模型调用、有明确输入输出定义的函数单个函数包含名称、描述、参数 Schema偏底层一个工具解决一个原子动作技能Skill一组工具 提示说明 执行逻辑的封装面向一个完整任务场景技能包含技能描述、多个工具、后处理逻辑偏任务层一个技能解决一类问题插件Plugin通常是某个外部服务/应用接入能力的统一包装REST API 规范、认证方式、调用清单偏集成层强调与外部系统的连接也就是说技能通常是建立在工具之上的“组合拳”。一个技能内部可以包含多个工具调用甚至包含一个小的决策流程。举例来说“客户信息查询技能”可能内部拆成“客户 ID 解析”“订单表查询”“联系方式查询”三个工具但模型在外部看来只需要调用一个技能三条数据统一返回。理解这个分层的好处在于当你要给 Agent 扩展能力时优先考虑“任务场景”而不是“单点功能”。很多初学者一开始就把所有能力拆成几百个细小工具函数模型面对一长串工具列表会非常迷茫选择困难、误调用频发而把相近功能组织成若干个高内聚的技能模型的决策负担会小很多。1.3 技能调用的完整生命周期一次执行背后发生了什么一次技能调用从用户提问到返回答案通常走这么几步意图解析模型读取当前对话判断“用户这个需求要不要动用技能”。技能选择模型从可用的技能清单里挑选一个或多个匹配的标准通常来自“技能名称 技能描述”。参数抽取模型把用户自然语言里的关键信息填进技能的输入参数。这一步最容易出错比如用户说“查一下上周华东区的订单”模型需要把“上周”换算成具体日期把“华东区”映射成区域代码。动作执行Agent 运行时接收到结构化的调用指令真正去执行对应的工具函数或者 API。结果回填执行结果成功或失败被拼回上下文交给模型。最终应答模型结合技能结果和原始问题组织出自然语言答案。你会发现这本质上是一个“模型负责判断和表达外部系统负责执行”的闭环。每一个环节都可能成为瓶颈。比如参数抽取错了执行肯定失败技能描述写得不清楚模型可能压根不调用结果回填太长上下文一下就爆了。我们要做的所有优化都围绕这六步展开。2. 入门实操把现成技能接到你的 Agent 上2.1 先盘点一个团队里常用的技能长什么样很多人第一次接触技能以为必须自己写。其实大多数成熟的 Agent 平台和框架都会自带一批现成技能你先学会“怎么用”比“怎么造”更重要。常见的现成技能包括代码执行技能模型动态生成 Python/JavaScript 代码在沙箱里执行直接跑完返回结果。适合数学计算、数据处理、文件转换。网页搜索技能把模型的问题转成搜索词去搜索引擎抓取摘要和链接再让模型综合出答案。文档处理技能读取上传的 PDF、Word、Excel抽取指定页面的内容必要时做表格结构还原。API 对接技能封装企业内部的订单、CRM、人事系统等 HTTP 接口模型可以通过它查数据、发通知。这些技能的共性是它们都把“模型不擅长的确定性操作”外包给了外部执行器。模型负责描述目标技能负责精确完成。接入现成技能时你需要做的三件事是开通对应服务的访问权限、在配置里声明技能参数、对技能返回结果设置合理的超时时间。2.2 最小接入示例从定义到执行一步步来我用一个极简的“单位换算技能”来演示最小接入流程。不管你是用哪家的 Agent 框架核心要素都是下面这些字段技能名称、技能描述、输入参数定义。{ name: unit_converter, description: 将长度、重量、温度等数值在不同单位之间进行换算。当用户询问类似“5公里等于多少英里”时使用。, input_schema: { type: object, properties: { value: {type: number, description: 待换算的数值}, from_unit: {type: string, description: 原始单位}, to_unit: {type: string, description: 目标单位} }, required: [value, from_unit, to_unit] } }接入时你把这段 Schema 和大模型的接口文件放在一起模型看到它就会在合适的时机输出一个类似下面的调用指令{ action: unit_converter, parameters: { value: 5, from_unit: km, to_unit: mile } }你的后端只要识别到action字段就路由到对应的换算函数执行再把结果塞回给模型让它继续组织回答。这一步跑通了你就已经具备 Agent Skills 的基础能力了。这里我想强调一个容易忽略的细节description里那句“当用户询问类似……”不是可有可无的废话它直接影响模型会不会在合适的时机调用这个技能。描述越具体召唤准确率越高。2.3 多技能编排一次任务调动三个技能的协作模型真实场景很少只用一个技能。比如用户说“帮我总结一下今天邮件里提到的两个项目并按优先级生成待办清单”这个需求至少牵涉邮件读取、文本总结、待办生成三个能力。多技能编排有两种常见模式串行模式先调用 A拿到结果后喂给 B再把结果喂给 C。适合有明显步骤依赖的任务。并行模式同时调用 A、B、C汇总各自结果后统一处理。适合互不依赖的多路信息获取。编配时最关键的是“谁来决定调度顺序”。我见过不少半成品把调度逻辑写死在代码里一旦用户表述稍有变化就挂。更稳妥的做法是让模型先输出一个“技能调用计划”Agent 运行时再根据计划做并行或串行执行。继续拿上面那个例子来说模型可能会生成这样的计划调用email_reader解析今日未读邮件得到正文调用project_extractor从正文中提取两个项目的关键信息调用todo_generator根据信息生成待办清单代码里你只需要维护一个简单的循环顺着计划逐步执行每一步的返回结果放入共享上下文。这一套看起来简单但非常实用足以解决 80% 的多技能协作场景。2.4 参数、超时与重试技能接入时的三个基本设置接入技能时有三个基础参数我建议每个技能都要配置别偷懒。超时时间外部 API 请求很可能因为网络或者服务端异常而卡住。不要设无限超时一般默认 10-30 秒。代码执行类技能因为可能有复杂计算可以放宽到 60 秒但必须设上限。重试策略对于幂等的查询类技能遇到超时或 HTTP 5xx 错误可以自动重试一到两次但对于“发邮件”“转账”“创建订单”这类有副作用的操作重试必须极其谨慎否则可能产生重复动作。错误返回格式技能执行失败后不要只返回一个 HTTP 状态码应该返回一段模型可以读懂的错误信息。比如“查询超时数据库连接池无空闲连接请稍后再试”。模型才能基于这段描述向用户给出合理说明而不是硬编造一个结果。你会发现这三个设置本质上都在处理同一个问题技能调用的不确定性。大模型天然不会稳定地每次调用成功我们要用工程手段把失败概率摊薄而不是默认它一定成功。3. 进阶开发从零写好一个自定义技能3.1 技能的三段式定义指令、Schema、执行体现成技能用得很顺之后你很快会遇到定制需求公司内部的业务逻辑不可能有现成技能直接覆盖。这时候就需要自己写技能了。一个高质量技能由三部分组成指令Instruction/Description告诉模型这个技能是干什么的什么情况下该调用什么情况下不该调用。这是最容易因为“写得太短”导致模型误用的地方。Schema严格定义输入输出的结构尽量做字段级说明。模型通过 Schema 来理解参数怎么填。执行体Executor真正干活的代码。它接收 Schema 里定义好的参数返回结构化结果。一个常见误区是很多人在指令里写得很空比如“数据处理技能”对我见过就五个字然后抱怨模型总在不该触发的时候触发。你要记住模型看不到你的执行体它只靠“技能名 描述 Schema”来做判断。描述写得不清楚就跟产品说明书缺失差不多。3.2 实战我做了一个“数据周报整理技能”前几天项目里有个需求每周要整理各个渠道的数据产出汇总成内部分享的 Markdown 周报。原先都是人工复制粘贴我干脆把它做成了一个技能。先看技能描述部分我是这么写的技能名称weekly_report_writer 技能描述 当用户提供多段运营数据或者要求“汇总周报”“整理本周数据报告”时使用。 它接收原始数据文本和汇报周期输出一份结构化的 Markdown 周报。 如果用户只是在提问概念、闲聊请勿调用本技能。再看输入 Schema{ type: object, properties: { raw_data: { type: string, description: 用户提供的各渠道原始数据可以包含多段文字或表格结构 }, period: { type: string, description: 汇报周期例如 本周、上周、2025-11-03 至 2025-11-09 }, focus: { type: string, description: 重点分析方向如 留存率、转化率、新增用户多个重点用逗号分隔 } }, required: [raw_data, period] }执行体代码的逻辑大致是先按渠道分组整理关键指标再按focus字段生成分析摘要最后拼装成 Markdown 输出。这里有个执行体层面的小技巧不要在函数里直接拼接一大段格式复杂的文本而是先返回一个中间数据结构把 Markdown 的排版工作交给模型。这样模型可以根据上下文调整语气和详略而你的代码只需保证数据准确。最终这个技能跑了一个月识别准确率从最初的 82% 提升到 95% 以上靠的就是反复调整描述和补充边界条件。3.3 触发调优让模型在该用的时候一定用不该用的时候不乱用触发问题是做技能进阶时最磨人的一个点。你可能会遇到两种情况该调用的不调用以及不该调用的乱调用。先解决“该用不用”。原因通常是技能描述里的触发场景和用户实际说法对不上。用户可能说“帮我算一下这个月佣金”而你的技能描述只写了“当用户要求生成月度报告时使用”。这时候需要在描述里增加同义触发词“结算佣金”“收益统计”“佣金明细”都可以算触发词。注意不要盲目叠加触发器那样反而会让模型想太多。再解决“不该用乱用”。一个很有效的写法是在描述里显式写否定条件。比如上面的周报技能里我加了“如果用户只是在提问概念、闲聊请勿调用本技能”。这句话看着普通但实测非常管用能把误触发率降低一半以上。还有一个进阶手段给技能设置“前置条件判断”。比如“只有当前对话包含至少 5 条数据时才调用”这个条件也可以写进描述模型通常会自觉地评估自己手里信息够不够。触发调优是慢功夫建议上线后每天看一次调用日志把错误的触发样本收集起来反哺描述。4. 性能与质量优化技能好用和能用是两回事4.1 提示侧技能描述怎么写模型才看得懂我在实战中总结了一个技能描述的四要素模板照这个写基本不会走样功能边界一句话说明这个技能做什么不做什么。触发条件出现哪些关键词、句式、场景时调用。禁用条件出现哪些情况时不要调用。返回特征返回的结果是表格、文本还是结构化数据有多少字。举个例子一个“客户标签查询技能”的描述可以是这样当用户询问某个客户的属性标签如行业、规模、意向等级时调用。 注意本技能只能查询已授权客户库中的数据不负责更新或删除标签。 如果用户只是询问标签的定义应该直接回答不要调用。 返回格式一个 JSON 对象包含客户 ID、标签列表、最近更新时间。这里最有价值的是“返回特征”。因为模型在调用技能之前需要知道“接下来我能拿到什么”清晰的返回特征能让模型决定是否需要继续追问参数也能让模型在后面组织答案时更有底气。4.2 执行侧并行、缓存、流式返回的取舍技能多了之后性能瓶颈主要是两个调用耗时和上下文占用。并行如果一个 Agent 在一轮里决定调用三个查询技能而这三个技能彼此之间没有依赖那么完全可以并行发起。这不需要改动模型调度逻辑而是在你的执行引擎里把模型输出的“技能调用计划”先解析成一个有向无环图DAG然后按拓扑顺序执行。没有依赖关系的节点同时跑能把总耗时压缩到原来的三分之一。缓存很多查询类技能相同参数在短时间内返回结果几乎一样。这时可以加一层缓存缓存键直接使用参数哈希值有效期按数据更新频率设定。但注意金融行情、库存数量这类高频变化的数据缓存会带来“看起来是实时其实是旧数据”的坏体验。一般只对静态或准静态数据开缓存。流式返回如果技能执行时间很长比如跑一个机器学习模型不要硬等它执行完再让模型回复。比较合理的方式是先把“正在执行技能”的状态告诉用户执行完再把结果增量返回。很多框架已经支持这种“流式中间事件”别忽略它用户的等待体验会好很多。4.3 验收侧技能成功率怎么统计、怎么回归一个技能上线后不能只靠“感觉好像还不错”来评估。我在团队内部会建一个简化的验收体系调用率在一百次相关提问中技能被正确调用的次数占比。反映触发调优的效果。成功率技能被调用后执行体成功返回内容的次数占比。反映技能本身的稳定性。有效返回率在成功返回的结果里能被模型正确吸收进最终答案的比例。这一步常常被忽略但核心价值恰恰体现在这里毕竟执行成功不意味着模型用得好。每次优化技能我都建议配一组回归用例涵盖正常场景、边缘场景、错误场景至少各五条。跑一遍记录上述三个指标再对比优化前后的差值。用数据说话你会少走很多弯路。5. 落地避坑从 10 个技能到 100 个技能会遇到什么5.1 返回内容太大上下文被撑爆的解法技能刚上线时返回几百字没啥问题。可当数据量变大技能可能一次性返回数千行日志模型的上下文窗口一下就满了不仅费钱还会让模型在后续对话中变得“健忘”。解法有几个层级按优先级排序技能内先聚合在执行体里做一次预聚合只返回摘要。比如日志分析技能不要返回每一行日志而是统计出错误率、TOP5 错误类型、时间分布即可。分页拉取如果用户明确要看明细就提供一个支持分页参数的技能变体。模型可以自行决定调用第几页。外部存储引用当内容实在太大可以把完整结果写入临时存储然后只返回一个“内容地址”给模型。模型可以说“我把结果放在附件里了”用户再点击附件查看全文。第 3 种方式最容易被忽略但它是处理大文件场景的正确姿势。不要指望模型“通读全文”它更适合“读摘要抓重点必要时用工具继续查”。5.2 技能之间互相干扰命名空间与权限设计技能少的时候还不觉得一旦超过 20 个你会发现模型开始“张冠李戴”查询订单金额的时候调用了库存查询技能明明有两个相似技能模型怎么都不选正确的那一个。这时候要做两件事第一检查技能名是否够独特。技能名尽量带上业务前缀比如order_query和inventory_query不要都用data_query这种模糊名字。模型在茫茫技能列表里快速找“哪个最像”名字就是它的第一直觉。第二收敛相似技能。如果你发现多个技能的描述大片重叠不如把它们合并成一个“万能技能”内部再按参数分流。模型只需要记住一个入口负担更小。比如把“查询订单”“查询退款”“查询售后”合并成“交易记录查询”再用query_type参数区分。还有一点容易被忽视在技能列表里给每个技能加“优先级/hot 程度”权重。某些高频场景的技能可以排在最前面模型选择命中率会上升不少。这是各家框架配置里都能看到的项别嫌麻烦值得认真调一调。5.3 高危操作哪怕是本地工具也要做授权校验一个安全的 Agent绝不能用户说什么就做什么。尤其是那些涉及邮件发送、文件删除、交易操作、数据修改的高级技能必须设计一层独立的授权保护。我见过一个反面案例开发环境里把“数据库删除”功能做成了技能测试时用户随口说了一句“把测试数据清掉”模型二话不说调用了技能。幸好指向的是测试库要是生产环境后果不堪设想。给高危技能加防护至少要做到敏感动作二次确认当模型识别到要调用高危技能时在返回给用户最终执行前先输出一条确认提示“即将执行删除操作是否确认”参数白名单校验在执行体内部对参数值做合法性校验。比如批量删除的 ID 必须是数字最大删除条数不能超过 100。权限级别检查每个技能打上权限标签不同会话、不同用户只能调用标签匹配的技能。这条不是可选项而是底线。哪怕只是一个本地实验项目也建议养成好习惯技能可以很聪明但用起来必须守规矩。5.4 我最后留下的技能自查清单做过的项目多了每次新上一个技能之前我都会过一遍这张清单节省了大量踩坑时间。分享出来你可以直接抄作业[ ] 技能名是否唯一、具体、容易理解[ ] 描述里是否包含触发条件、禁用条件、返回特征[ ] 输入 Schema 是否每个字段都有说明必填项是否正确[ ] 执行体是否做了参数校验和异常捕获[ ] 技能是否有明显的副作用是否需要二次确认[ ] 超时时间是否合理重试策略是否考虑幂等性[ ] 返回内容是否过长是否有摘要或分页方案[ ] 是否已在测试集上记录调用率、成功率、有效返回率[ ] 新增技能后是否和已有相似技能做过名称与描述去重这一整套检查下来一个技能的质量基本就稳了不会出现那种上线三天被用户骂“人工智障”的尴尬局面。我自己做过的一百多个技能里最后活得最久的往往不是逻辑最炫酷的那个而是边界最清楚、失败回应最友好的那个。Agent 的技能本质上是把“大模型的判断力”和“外部系统的执行力”粘在一起粘得牢不牢取决于你有没有把每一条边界都写到。希望这一期能帮你把 Agent Skills 这条链路真正跑通剩下的就是在自己的场景里一点点打磨了。