★ FEATURED ARTICLE 做AI应用落地这一年多我最大的感受是让大模型能说会道已经不难真正难的是让它靠得住地干活。Agent Skills这个概念恰恰就是为了解决后者出现的。它不强求你懂多复杂的框架也不需要你成为提示工程大师它提供了一条非常务实的路径把模型能调用的能力封装成一个一个结构清晰、描述准确、可测试的技能包让智能体在合适的时机、以合适的方式调用它们。这篇文章面向两类人一类是刚接触Agent开发想知道从哪儿下手的初学者另一类是已经写过不少Prompt和Function Call但总觉得效果不稳定、想系统化整理的老手。我会从最基础的概念讲起逐步拆解一个技能的内部结构再把我实测中踩过的坑、翻过的车原原本本摆出来。全程不依赖任何特定平台或厂商讲的是思路和通用方法你完全可以搬到自己的项目里去用。1. 聊Agent Skills之前先搞清楚智能体到底缺什么1.1 模型会说话与会办事之间差了一层可执行逻辑很多人刚接触智能体时会有一种错觉大模型这么强给它一个任务它就能自己搞定。真上手才发现模型本质上是一个文本生成引擎它知道很多但做不到任何事。你说帮我去数据库里查一下本月订单它能写出SQL但不会真的去连数据库执行。你说帮我把这份报告发给老板它能编一封像模像样的邮件草稿但不会真的点发送。这就是所谓的知行鸿沟。模型负责思考工具负责行动而Agent智能体就是连接两者的胶水。但胶水也分三六九等。早期大家习惯用Function Calling函数调用来解决给模型注册几个函数它根据用户意图选择函数并填充参数。这个思路在小场景里很清爽一旦任务变复杂就露馅了函数只描述做什么不描述什么时候做、做到什么程度、失败了怎么办、结果怎么返回。模型面对十几个平铺的函数经常选错、漏参或者误报成功。Agent Skills的出现本质上是在函数调用外面包了一层使用说明书 执行规范 结果协议。一个技能不再是一个孤立函数而是一个完整的业务能力单元。它告诉模型你面对什么情况时该想起我、调用我需要填哪些参数、我会给你返回什么格式的结果、哪些事别指望我做。这个概念真正解决了智能体开发里最挠头的问题——不是模型不会用工具而是工具不知道怎么被用好。1.2 Skill、Tool、Prompt在实战里的边界感这三个概念在日常交流里经常被混着用但在工程落地上它们的职责差异非常大。我习惯用下面的方式理解概念粒度核心作用举例Prompt文本指令约束模型怎么回答你是一个数据分析专家回答要分点Tool/Function单一函数完成一次确定的调用输入城市名返回天气数据Skill能力包封装一类任务的全流程识别录音、转写文本、提炼纪要、输出模板Tool是手Prompt是嘴Skill则是一套完整的岗位职责。举个例子一个会议纪要技能不只是把录音转成文字这样一个工具它还要包含什么时候触发用户提到会议录音或纪要需求时、怎么做预处理降噪、分段、识别发言人、怎么提炼行动项、按什么模板输出。这中间的每一步都可以调用不同工具但整体编排逻辑被Skill锁死。我在实际项目里有个很深刻的体会如果只用Tool你需要在对话轮次里让模型反复判断调用哪个函数上下文稍长就乱。如果用Agent Skills的方式把流程封装成技能模型只需要判断这个请求是不是属于某技能判断成本大大降低稳定性明显提升。所以我的建议是单次、无状态的调用用Tool涉及多步骤、需要上下文约定、需要结果规范化的任务一律优先设计成Skill。2. 一个最小可用技能的手写全过程2.1 先搭目录一个技能本质上是一个能力包不扯远直接看我建议的最小目录结构。假设我要做一个日报生成技能它的功能是从指定的数据源里读取指标生成图文并茂的日报文本daily-report/ ├── SKILL.md # 技能说明书模型接到任务后最先读的文件 ├── run.py # 核心执行逻辑可以是一个脚本也可以是一个函数入口 └── assets/ # 静态资源文件模板、图标、词表等 └── report_template.md这个结构是我在实际项目里反复调整后沉淀下来的。SKILL.md是给模型看的run.py是给系统跑的assets是给两者共享的。不要让模型去读代码它读不懂也不该读也不要让系统去读SKILL.md那是自然语言描述机器解析效率低。各司其职后面维护才不拧巴。初学者最容易犯的错是把所有说明都写进代码注释里然后让模型看代码理解技能。这种方式在小项目里勉强能跑技能一多就彻底失控。模型每次触发技能都要重新推断意图注意力被大量无关实现细节分散。正确做法是代码只负责确定性地执行SKILL.md负责把何时用、怎么用、边界在哪讲清楚。2.2 技能描述是最容易被低估的入口文件SKILL.md的核心不是长篇大论而是精准。我见过的优秀技能描述通常都长这样name: 日报生成 description: | 当用户提供或指定了可读取的数据源如数据库表、CSV文件或API接口 并要求生成按日维度的统计报告时使用本技能。 包含指标计算、趋势标注、模板渲染三个环节。 本技能不处理数据写入操作不替代用户决策。注意几个细节第一description开头就写明触发条件而且是可校验的条件用户提供了数据源。第二明确说明了技能的三个内部环节模型对接下来的流程有预期。第三最后补齐了两条负向边界——不做什么防止模型越权调用。我踩过最深的坑就是负向边界缺失。早期我给一个数据查询技能写描述只写了当用户需要查询数据时使用结果模型在用户问你觉得哪个指标更重要这种纯咨询问题上也调用了查询技能白白浪费了一次API调用返回结果还答非所问。后来我加上了本技能仅执行查询不做分析建议若用户未指定数据来源请先询问获取之后这种误召就基本绝迹了。再补一句描述里的触发条件要尽量用客观可判断的表述少用主观词。用户想要看数据这种就含糊用户提供了表名或文件路径就是客观可判断的。模型判断前者会犹豫判断后者则非常果断。2.3 执行脚本的三层拆分很多人写技能内部的代码喜欢把所有逻辑堆进一个函数。这在小项目里问题不大但技能一旦要扩展比如新增一个输出模板、接入一个新的数据源就得整段重写。我自己的习惯是拆成三层参数清洗层接收从对话中萃取出来的原始参数做格式校验、默认值填充、边界值规整。这一层只做数据准备不碰业务。业务逻辑层真正去查数据、算指标、做渲染。这一层不关心参数从哪来只接收清洗过的标准结构。结果格式化层把计算结果包装成约定的返回协议确保下游模型或另一个技能能稳定解析。这样拆的好处是每一层都可以独立测试。我可以不经过模型直接拿一个JSON参数去调run.py验证清洗逻辑对不对也可以伪造一个绑定结果验证格式化层输出的字段是否齐全。这在后面的轻量测试环节特别有用。顺带说一个实操细节执行脚本的输入输出都应该是标准JSON而不是命令行参数和打印文本。因为技能可能被多个场景复用——有时候是模型调度有时候是另一个技能编排调用。标准JSON接口能最大程度降低耦合。3. 技能接口设计参数萃取、返回协议与运行边界3.1 从自然语言到结构化参数别让技能替你猜模型从用户对话中提取参数这一步是整个技能链路里最容易出问题的环节。用户说帮我把上周的销售数据整理成日报模型提取出时间上周这个上周是模糊的。直接把这个值传给执行脚本脚本还得猜上周是从周一开始还是周天开始。我的解决方案是在技能内部再做一道二次解析将相对时间换算成绝对时间范围。比较稳的做法是在SKILL.md里给模型提供明确的参数schemaparameters: data_source: type: string required: true description: 数据表名、文件路径或API地址必须是用户明确指定的 time_range: type: object required: false description: 统一为 start_date 和 end_date若无则默认最近7个自然日这里有个容易忽略的关键点required字段要诚实标注。如果某个参数缺失会导致技能无法执行就标true如果技能内部有合理的默认值兜底才标false。我见过很多项目把所有参数都标成可选模型每次只填一两个就放行结果技能拿到残缺参数后跑出一个不三不四的结果反而更糟。我的经验是宁可让模型在参数不足时向用户多追问一句也不要让它拿猜测值硬跑。真实任务里用户说查一下上个月的数据模型如果追问请问上个月是指6月1日到6月30日吗用户只会觉得它聪明不会嫌它啰嗦。3.2 返回协议是给模型看的不是给用户看的技能执行完之后系统会把返回结果交给模型由模型组织语言回复用户。问题恰恰出在这里——很多技能的返回结果是机器导向的充满字段名和逻辑结构模型不知道哪些该转化成人话哪些保留原样经常把内部结构一股脑端给用户。我现在用的是一套稳定的三段式返回协议{ status: success, // success | failed | partial data: { // 结构化主结果 summary: 本周销售额环比上升12%, metrics: { total_revenue: 358000, growth_rate: 0.12 } }, message: 数据读取成功已生成摘要。注意仅包含已支付订单 未包含退款订单。可建议用户查看退款明细。 }status字段让模型在0.1秒内判断技能是否成功data字段承载核心结果message字段则是最关键但又最容易被忽略的部分——它是写给模型看的执行说明包含当前结果有什么限制、下一步建议做什么。这里我想强调一个观念转换message不是给人看的报错信息而是写给同事的工作交接。你执行完一单业务不光要汇报结果还要提醒同事这份数据里哪些口径要注意我建议你下一步怎么跟进。模型拿到这样的message生成给用户的回复时就有据可依不会自由发挥到跑偏。3.3 幂等、超时与权限收敛技能一旦开始执行真实操作比如发邮件、改数据库、调外部接口就必须考虑三个工程问题。第一个是幂等。技能被调用了两次会不会产生两笔订单、两封邮件解决思路是在参数里引入request_id技能执行前查询该ID是否已处理过处理过就直接返回旧结果。这个机制听起来简单但放在技能封装里特别有用因为模型的重试行为是不可控的你不能指望它只调用一次。第二个是超时。外部依赖数据库查询、第三方API可能很慢技能如果死等整个Agent对话都会被卡住。我一般会在技能内部设置两层超时单次外部调用超时比如10秒以及整个技能执行总超时比如30秒。超时后返回statusfailed的协议并给出message说明是哪一步超时方便模型判断是重试还是换方案。第三个是权限收敛。技能能访问的系统资源要做到最小化文件读写限定在工作目录内网络请求限定在白名单域名数据库操作限定为只读账号。这不是过度设计而是真实教训——我见过一个数据导出技能因为用了高权限账号在一次错误调用里把生产表清掉了一半数据。从那以后所有技能默认配置都是最保守的权限需要扩展时再单独审批。4. 三次真实翻车复盘触发时机、结果误读与长对话失忆4.1 描述写得太宽技能变成万能胶第一个翻车案例发生在一个企业内部数据分析助手项目上。当时我给一个数据分析技能写的描述是处理用户的数据分析请求特别自信觉得范围广一点覆盖率才高。结果上线后崩了用户问今天中午吃什么模型都先调用一下数据分析技能把对话历史里的文字做了个词频统计再回复。每一次误召都是一次毫无必要的API调用返回结果还干扰正常对话。根因很简单触发条件写得太宽分析请求这四个字可以解释出无数种含义。模型在模糊条件下倾向于宁多勿少先把技能调用上再说反正调用本身不会报错。修复方式也很直白把逻辑改成仅当用户提供或指定了可读取的结构化数据并且明确要求进行统计、汇总或可视化时才启用本技能。加了结构化数据和明确要求两个硬前置条件后误召率直接降到了零。这件事让我彻底明白了一个道理技能描述里的触发条件宁严勿宽。模型不会因为有时候该触发没触发骂你但会因为不该触发乱触发让整个体验变得一团糟。精确描述技能何时生效比模糊地追求高覆盖率重要得多。4.2 返回给足信息模型却照着念第二个案例很滑稽但也很典型。我给一个销售周报生成技能设计的返回协议里包含完整的指标口径说明和对比数据结构非常清晰。结果模型在给用户呈现时把metrics字段里的字段名、JSON键原封不动地念了出来用户那边看到的是total_revenue: 358000, growth_rate: 0.12这种满屏技术味的内容。我开始以为是模型能力问题后来对比测试才发现返回协议里缺少对呈现方式的约束。模型不知道哪些信息应该翻译成人话哪些信息应该保留为数据细节自然就按自己的习惯处理了。修复方法是在返回协议里增加一个汇报要点字段明确告诉模型你只需要基于summary向用户做自然语言总结metrics里的原始数值可以作为参考但不要原样复述字段结构。这个坑的教训是给模型返回结构化数据时一定要额外声明如何向用户呈现。模型是概率生成器你不告诉它边界它就会自由发挥。把对用户怎么说的控制权握在自己手里体验的稳定性会大幅提升。4.3 单轮没问题20轮之后技能结果蒸发第三个案例最隐蔽。技能在单轮对话里执行得很完美返回结果漂亮、模型总结得也流畅。但到了真实的长时间对话里问题出现了用户在第3轮让技能生成了一份数据摘要然后继续聊了十几轮别的业务第20轮突然问刚才那个摘要里提到的增长率是多少模型一脸茫然好像那段技能执行结果从未存在过。根因是上下文窗口的遗忘机制。技能返回的结构化结果确实进入了上下文但随着对话增长早期内容会被压缩、截断或加权降权。模型不是精准的数据库它对于早期细节的记忆是概率性的。解决方案是引入状态记忆层技能执行完把关键结果以显式摘要的形式写入一个独立的记忆文件中后续对话中如果模型感知到相关诉求可以主动读取该摘要。这相当于给Agent配了一个外挂的记事本。这个机制实现起来不复杂一个小JSON文件就够但效果立竿见影。我把它想成是手术后的病历时隔很久依然能翻到而不是靠医生模型对几个月前的印象来回忆患者用户情况。凡是技能结果需要跨轮次引用的都建议做这一层持久化。5. 技能越来越多之后版本管理、组合编排与轻量测试5.1 从技能目录到技能库的演进当你手头有3个以下技能时随意管理毫无问题。一旦超过10个、20个命名冲突、加载顺序、依赖关系就会通通冒出来。我开始系统化整理时做了三件事至今受用。第一件按领域分组目录。数据类、沟通类、运维类分开存放避免一眼望去全是平铺的文件夹。第二件每个技能维护独立版本号并在SKILL.md里声明依赖的Python版本、外部服务地址、必要的环境变量。第三件给每个技能加一个自检测试入口比如run.py --self-test能在5秒内验证技能是否健康。这一步强烈建议趁早做。等到技能库里几十个技能挤在一起再回头补管理规范成本高到你宁可重写也不想动。5.2 串行编排里的信息损耗问题当多个技能组合完成一个复杂任务时最常见的是串行编排技能A产出结果交给技能B继续处理。这里有一个容易被忽略的效率杀手——如果技能A返回的是结构化结果就直接把结构化结果传给技能B如果传输路径要经过模型转述信息损耗就开始了。我做过一个小实验技能A算出一个数据表让模型用一句话概括后再传给技能B和直接把JSON数据传给技能B两种方式下技能B的输出质量差距悬殊。前者丢失了大量细节后者能精确复现。所以我的原则是系统层面能传结构就不要让模型当传话筒。技能A输出→技能B输入中间该走程序化通道的坚决程序化。5.3 没有传统测试环境就做契约测试给技能做测试不能照搬传统软件开发那套完整的单元测试、集成测试流程——成本太高且边际收益低。我实践下来性价比最高的是契约测试只验证两件事第一给定特定触发场景模型是否会选中该技能第二给定符合约定的参数执行脚本是否能返回符合schema的结果。第一件事可以用一批标注过的用户话术跑离线评测统计召回率和误召率。第二件事更简单直接构造参数样本调用执行脚本检查返回的JSON是否符合预设结构。这两个测试覆盖了技能链路里80%的隐患足以让技能在真实场景里站得住脚。我现在每写完一个技能都会先自己扮演用户跑二十遍把所有失败的返回全都截下来看。技能这东西写代码其实只占四成功夫剩下六成都在打磨边界——什么时候触发、参数怎么约束、结果怎么呈现、失败怎么兜底。把这层功夫下足Agent才能从偶尔灵光变成稳定靠谱。
阅读完成 · 觉得有帮助？
