锦
锦思新知编辑组
发布时间:2026/11/17 17:29:34
来源:锦思新知
阅读:知识向官网定制

做AI应用开发的朋友最近都在聊一个词Agent Skills。听着玄乎说白了就是给智能体建一套“可复用能力单元”的工程化方案——把智能体要干的那些相对固定的能力拆成一个一个独立的技能每个技能都写清楚它擅长处理什么、输入是什么、输出是什么、内部怎么执行然后注册到一个统一的底座里按需调起。这篇文章想把这套思路从设计到落地完完整整复盘一遍包括技能怎么拆、怎么注册、怎么调、踩过哪些坑以及在团队协作、系统架构上带来的连锁变化。如果你正在做智能体平台、工作流引擎或者只是用大模型接口搭过几个自动化应用应该都能在里面找到有用的东西。先说一个我们踩过的典型教训。早期做一个内容处理智能体图省事把“总结、翻译、改写、提取要点、生成标题”这些能力全塞在一个超长的系统提示词里再挂几个乱七八糟的函数。结果就是提示词越写越长模型行为越来越飘同一个问题上午能过下午就崩每次排查都要翻日志对上下文改一个场景经常把另一个场景搞坏。后来我们把能力一个个拆成技能——长文本摘要是一个技能多语言翻译是一个技能标题生成是另一个技能——每个技能有独立的描述、参数契约和执行逻辑注册表里统一管理模型只负责做“选哪个技能、填什么参数、怎么组织回复”效果立刻不一样。这篇就是从这次重构里沉淀下来的经验。1. 先搞清楚Agent Skills到底要解决什么问题1.1 一次“大而全”设计的翻车现场我见过很多团队做智能体第一步就是写一个“万能系统提示词”把任务背景、角色人设、能力边界、输出格式、对话禁忌、例几个示例全塞进去美其名曰“把业务规则喂给模型”。这种做法的初衷是好的想让模型更像一个懂业务的助手但实际跑起来一定会遇到三个问题。第一是提示词失控。业务逻辑是活的运营同学今天说摘要要带数据明天说标题要控制字数每次需求变化都要动系统提示词。改完长文本场景翻译场景可能就跟着漂了因为模型面对的是同一段混杂指令它根本分不清哪个要求对应哪个场景。第二是排障困难。模型输出不对时你很难判断是提示词写错了、参数传错了、还是函数本身出了问题。所有能力共用一套上下文错误被层层包裹定位一次问题要来回折腾很久。第三是能力无法沉淀。在一个智能体里调好的“摘要逻辑”换到另一个智能体里基本是复制粘贴一段提示词然后重新调试谈不上复用和迭代。这类问题不是模型能力不够而是工程结构不对。智能体本质上是一个复杂系统复杂系统最怕的是高耦合。Agent Skills的核心思想就是把“能力”从“对话逻辑”里剥出来让每一个能力变成有边界、有契约、可单独演进的黑盒。这个思路其实在传统软件工程里已经是常识只不过放到大模型应用里很多人被“提示词万能”的错觉带偏了。1.2 技能、工具和提示词边界到底在哪谈Agent Skills之前得先把几个容易混淆的词理清楚提示词、工具、技能、工作流。我在评审技能设计时经常发现团队内部对这几个概念的认知完全不同说出来的方案自然千奇百怪。提示词Prompt是最轻的一层本质是一段自然语言指令。它灵活但几乎没有结构性约束适合临时性、一次性的交互或者用来定义智能体的说话风格。工具Tool/Function偏底层通常是一个可编程调用的函数接口参数严格、返回原始数据由业务代码直接调用缺少面向模型的语义包装。技能Skill正好落在中间它是一段在业务语义上完整封装的能力块对外暴露的是给模型看的清晰描述和参数契约对内连接的是一个或多个执行动作可能是一段代码、一个脚本也可能是调用某个API。工作流Workflow则是多个技能按业务顺序的组合编排解决的是一个跨步骤的完整任务。用一个生活类比提示词是“你按我说的做”工具是“给机器一个按钮”技能是“一个训练有素的专员”工作流是“一个衔接紧密的办事流程”。技能这个层级之所以重要是因为它同时满足了两件事对模型友好它有清晰的语义描述模型知道什么时候该调用它对系统友好它有固定的输入输出协议和独立的执行逻辑工程上可以测试、可以监控、可以灰度。2. 技能设计的核心拆解一个技能就是一个可复用单元2.1 技能单元的五要素把技能落到工程上至少要有五个关键要素。缺一个这个技能就不完整后续调用时迟早出事。第一个要素是技能名称。名称要短、要准确、要符合业务语言。比如“translate_text”就比“convert_language”清晰“longtext_summarizer”就比“ai_processor”直观。模型在候选技能列表里扫一眼名称是最先被感知的信息起得含含糊糊后面描述写得再好也可能被埋没。第二个要素是技能描述。这是整个技能设计里最容易被低估的部分。描述不是写给项目经理看的是写给模型看的。它决定了模型在什么场景下会选中这个技能。好的描述应该包含触发场景、典型输入句式、输出特点最好还能写一句“它不能做什么”用来跟相似技能做区分。我在实际项目里有一条铁律技能描述写完先让没参与实现的同事拿它跑一轮意图匹配测试如果对方能凭这段描述判断哪些请求该走这个技能模型大概率也能。第三个要素是输入协议。输入协议定义了这个技能需要哪些参数、哪些必填、哪些可选、每个参数的类型和取值范围。输入协议是后面参数抽取的基准设计得模糊模型抽参就会瞎猜。第四个要素是输出协议。输出协议定义了技能执行完返回什么结构。很多团队忽略这一项让技能直接返回一段文本后面模型要在这个结果基础上继续推导时就蒙了。结构化输出永远比自由文本可靠。第五个要素是执行体。执行体是技能真正干活的代码或脚本它可以是本地的Python函数、一个远程HTTP接口、一条SQL查询任务甚至是一个外部系统的操作指令。执行体至少要声明它的运行方式、入口函数、超时时间和重试策略。除了这五要素我还建议每个技能带上运行约束、权限声明、版本号和标签。运行约束控制并发和资源占用权限声明防止技能越权操作版本号支撑演进标签方便做技能索引和批量治理。这些字段看起来是负担技能一多就发现它们全是刚需。2.2 技能粒度怎么定太粗太细都难受技能粒度是Agent Skills设计里最考验经验的一环。拆得太粗一个技能里塞了太多分支逻辑等于把一个小系统做成了技能模型虽然能调用但内部难维护、边界不清晰。拆得太细技能数量爆炸模型在候选列表里挑花眼匹配准确率反而下降维护成本也跟着上来了。我的判断标准很简单一个技能对应一个“能独立验收的业务动作”。什么叫独立验收第一它有清晰的成功标准做完就是做完没做完就是失败不需要后续步骤来补全它。第二它可以单独测试不需要搭建上下游环境。第三它会被多个场景复用而不是只在一个流程里出现一次。三个条件都满足才值得做成技能。举个例子。“总结长文章”是一个合适的技能它有明确的输入输出可以被新闻聚合、会议纪要、论文导读等多个场景复用。“运营日报自动生成”就不适合做成单个技能它包含了数据拉取、指标计算、文案生成、图表绘制、发送推送好几个动作应该拆成多个技能再在工作流里编排。反过来“把文本首字母大写”这种动作太细作为工具函数直接调用就行不必上升到技能层它的业务语义单薄模型也不会因为你把它包装成技能就调用得更准。2.3 状态设计默认无状态技能设计里还有一个容易踩的坑状态。我强烈建议技能默认保持无状态——也就是技能本身不记忆上一次调用的情况所有需要的信息都通过输入参数传进来执行完之后不保留任何内部会话数据。为什么坚持无状态三个理由。第一可重放。技能出问题时你可以拿着同一份输入重新执行一遍复现bug和验证修复都非常方便。如果技能内部藏了状态复现就变成碰运气。第二可并发。智能体在服务多个用户时同一个技能可能同时被调起多次无状态设计天然支持并发不用加锁、不用处理脏数据。第三可恢复。一次调用因为超时中断后重试时不需要考虑状态回滚的问题。如果某些业务确实需要跨步骤记忆把状态显式地放到上下文对象里由调用方管理而不是让技能偷偷藏私货。3. 实操从0到1注册并调起第一个技能3.1 用一份配置清单描述技能把技能从想法变成可被智能体调用的实体第一步是写一份技能描述文件。这个文件是技能和外部世界的唯一契约。我习惯用YAML写它比JSON可读性好还支持注释。下面是一个我当时给“长文本摘要技能”写的简化版本name: longtext_summarizer version: 1.2.0 description: |- 长文本摘要技能。适合处理超过2000字的文章、报告、聊天记录返回结构化摘要。 典型触发场景用户上传一篇长文要求“总结一下”“提炼核心观点”“出个摘要”。 它不能做单句短文本的改写压缩、按指定角度改写原文。 input_schema: type: object required: - text properties: text: type: string description: 需要做摘要的完整原文长度不超过2万字 max_len: type: integer description: 摘要目标长度默认500字范围100到2000 default: 500 output_schema: type: object properties: summary: type: string description: 核心摘要正文 key_points: type: array items: type: string description: 3到5条关键要点每条不超过50字 execution: type: local_function entry: summarizer.run timeout_ms: 30000 retry_count: 2 permissions: - read tags: - text - summary - long_doc写这份文件有几点经验。description字段里那行“它不能做”特别重要它能在候选技能很多时帮模型排除掉错误选项。input_schema里的字段描述也别偷懒模型抽参时会读它。execution里timeout和retry_count是保命用的尤其是执行体要调用外部服务时没有超时控制整个智能体都可能被一个卡死的技能拖住。3.2 注册进引擎技能注册表是底座的核心技能描述文件写好后需要注册到智能体运行时的技能注册表里。注册表做的事并不复杂扫描技能目录、加载配置文件、校验Schema是否有硬伤、把技能转换成两类运行时对象——一类是面向编排器的完整技能定义另一类是面向模型的“技能候选卡片”。这里有一个值得注意的设计点给模型看的技能卡片要精简不能把整个YAML配置原封不动塞进上下文。模型每多读一个技能就要多消耗Token技能多了还容易干扰判断。我通常只把name、description、关键参数名和一个典型调用示例放进卡片输出协议和执行逻辑放在完整定义里由执行器按需读取。Token节省是实打实的更重要的是模型没有被无关细节干扰匹配准确率会更高。技能加载方式也要考虑。技能库小的时候启动时全量加载没有问题。技能库大到上百个时每次请求都把全部技能卡片送给模型既不经济又容易选错。这时候建议做按需加载先通过一个轻量的意图预筛模型或规则模块选定一个技能候选子集再把子集卡片放入本轮请求的上下文中。这一步虽然多了一次小开销但对技能数量多的场景来说收益远大于成本。3.3 调起链路从请求到结果总共分四步技能注册好之后智能体收到一次用户请求完整的调起链条可以拆成四个环节。第一步是意图路由。请求进来后先做一个粗粒度的判断这个问题是否需要调用技能如果需要大概属于哪个能力域。路由可以是一个轻量模型也可以是一组规则与关键词组合。这一步的目标不是精准匹配到具体技能而是快速缩小范围把明显无需调用技能的情况分流掉省掉后面不必要的计算。第二步是技能匹配。在候选技能列表里做语义相似度排序选出TopK。匹配不只是看描述文本的余弦相似度还要结合技能里的典型调用样例、参数名称、业务标签做综合打分。我在这一步会加一条兜底规则如果最高匹配分数低于某个阈值不再强行选技能而是让模型直接向用户澄清需求。宁可多问一次也不要误调用。第三步是参数抽取与校验。根据选中的技能输入协议从用户原始输入中抽取参数值。这一步通常还是交给模型做但一定要按schema做严格校验。缺失必填参数时生成澄清问题回问用户可选参数缺省时补默认值类型不对就纠正。校验不通过就走澄清分支不能把脏参数往执行体里丢。第四步是执行与结果反馈。调用执行体带着超时和重试策略拿到原始结果后按输出协议格式化再把结构化结果和技能版本号一并返回给模型。模型基于这个结果做最终判断任务是否完成还要不要继续调用其他技能最终怎么组织语言回复用户。执行结果里带上版本号是为了出问题时能回溯到底是哪个版本的技能逻辑导致了异常。3.4 一个完整案例给智能体加一个长文本摘要技能前面讲理论我拿真实场景串一遍。当时运营团队每天要把十几篇行业长文整理成摘要原来靠人复制粘贴到对话框让模型总结每个人说一遍规则不同人拿到的结果风格还飘。我们决定做成一个技能。先做拆解。输入是原文、摘要长度输出是结构化摘要对象——正文摘要加三到五条要点。执行体我们不做“模型二次加工”而是把确定性工作全放在代码里完成先清洗文本去掉大量空白和重复段落再按语义切分成多个块每个块调用一次大模型接口做局部浓缩然后合并所有局部摘要并去重最后按max_len参数截断。这套流程本质上是一个Map-Reduce结构好处是能稳定处理超长文本不会因为原文太长而超过模型上下文上限。然后把技能注册进平台的注册表路由层加了一条规则当用户问题里出现“总结”“摘要”“核心观点”等意图词且输入文本长度超过2000字时优先走这个技能。最后是测试我们用几十篇不同风格、不同长度的文章过了一遍确认摘要质量稳定、要点数量和长度都符合预期才放给运营团队使用。上线之后最大的变化是新同学不需要再被培训“你应该怎么跟模型提要求”只要在对话框里把文章贴进去智能体自己就会选对技能、给对参数、返回规范摘要。4. 影响范围技能化之后系统和协作方式全变了4.1 应用架构从“单体提示词”变成“能力总线”做完Agent Skills改造之后最直观的变化是智能体架构从一团乱麻变成了一条清晰的“能力总线”。原来的系统提示词被大幅瘦身里面只保留角色定位、语气风格、通用安全边界这些不变的元信息业务能力全部下沉到技能层。系统提示词不再频繁改动改一个技能不会波及其他场景。同时技能层之上会自然长出一套治理机制。你会有能力地图知道当前智能体总共具备哪些能力会有路由规则知道一类请求应该往哪条链路走会有调用日志和监控面板知道每个技能被调了多少次、成功率多高、平均耗时多长。这些机制在原来的单体提示词架构里几乎不可能实现因为能力没有边界问题没有入口。技能化之后每一个能力都变成了可观测的节点系统的可靠性就有了基础。4.2 团队协作技能开发者和业务编排各管一摊技能化带来的另一个变化在组织和协作层面。以前做好一个智能体需要一个人既懂业务又懂Prompt又懂代码所有改动都堆在一个人身上。技能化之后能力建设可以拆开流水线一部分人专职做技能开发负责把一个个能力打磨到稳定另一部分人做业务编排只负责组合现有技能来满足具体业务需求。技能开发者要对技能契约负责写完技能必须配测试用例至少要覆盖正常流转、参数缺失、超时长文、错误输入四类情况。业务编排者不关心技能内部怎么实现只需要从注册表里看技能卡片判断哪个技能符合他的场景然后用工作流把它们串起来。这个分工模式下技能库成为团队共有的资产一个人开发的技能可以被多个项目复用沉淀下来的不只是代码还有一套可复用的业务能力。新同学上手也不再需要从头理复杂的提示词逻辑只需要熟悉技能库的目录结构。4.3 对模型表现的三个直接收益省Token、降幻觉、可观测从模型使用效果出发技能化带来的收益同样明显。首先是省Token。技能化之前系统提示词里往往堆了大量业务流程描述这些描述每次请求都要消耗Token技能化之后提示词里只剩轻量的候选技能卡片单次调用的上下文显著变小在大流量下这是一笔实打实的成本优化。其次是降幻觉。大模型擅长的是理解和生成不是精确执行。把一个复杂业务的确定性算法步骤从模型手里拿走放到技能执行体的代码里模型只需要做匹配和抽参幻觉空间就被大幅压缩。比如摘要技能切分、去重、字数控制都由代码完成模型只负责局部文本压缩最终结果在长度和结构上几乎不会出错。最后是可观测。技能调用前后的日志、时长、成功率、失败原因都是结构化数据出问题时可以快速定位到具体环节是描述没写好导致模型选错还是参数抽取失败还是执行体本身报错。这种可观测性在原来“一段提示词打天下”的架构里根本不存在。5. 常见问题与排查技巧实录5.1 技能匹配张冠李戴最常遇到的问题就是技能匹配错。用户要翻译一段话智能体却调用了改写技能要提取摘要却走了标题生成。原因多半有三个技能描述没写清楚触发场景候选技能太多没有互斥机制或者匹配阈值设得太低。解决思路分几层。先优化描述给每个技能写清楚“典型触发句子”和“它不能做什么”。再给相似技能做互斥定义比如“翻译”和“改写”在业务层级上就强制要求描述里互相标注对方不是自己的子集。最后在匹配上做工程兜底设置最低分数阈值低于阈值不自动调技能改成向用户确认。我们还会维护一份“易混样本集”把历史上被误判过的真实请求收集起来每次改技能描述或加新技能时拿这批样本做回归测试确保没有把老问题修出新问题。5.2 技能执行超时和“假死”技能执行体和外部服务打交道时超时是最常见的坑。调用一个大模型接口正常可能要十秒遇到高峰期可能拖到一分钟前端用户早走了后端的重试还堆在那里。我见过最离谱的情况是单个技能把整个智能体的请求线程池全部占满其他用户全被阻塞。超时治理要做在两层。第一层在技能执行体内部所有外部调用必须有独立的超时控制宁可这次调用失败也不能无限等下去。第二层在注册表和执行器层面给每个技能设置timeout_ms和retry_count执行超时后按策略重试或直接失败。这里我提醒一句重试逻辑必须保证幂等也就是说同一个技能被重试两次不能产生双份副作用。尤其是“发邮件”“创建订单”这类技能重试前要确认上一次是不是其实已经成功了否则轻则重复发送重则数据不一致。5.3 参数抽取不全导致连环报错用户说“帮我把这篇文章总结成八百字左右”模型可能只抽出了textmax_len没抽到或者把“八百字左右”解析成数字“800”时把单位丢了最后执行体拿到的参数和真实需求根本不匹配。参数错误很隐蔽因为模型通常会给出一个看起来合理的回复但细节是错的。我的做法是三步第一步在输入协议里严格区分必填和可选必填缺失时不走执行先让模型基于schema生成澄清问题回问用户。第二步为可选参数提供合理默认值比如摘要长度默认500字用户没提就用默认值。第三步在参数进入执行体前加一道程序化校验类型、范围、大小都要过不能只依赖模型自觉。校验失败时返回的也不是一堆堆栈而是给模型看的、人可以读的错误说明让模型有机会组织语言向用户解释和补救。5.4 版本升级把存量流程弄坏技能库一定会迭代今天改字段明天动逻辑后天换接口。如果不做版本管理一个技能的升级很可能把依赖它的旧流程全部弄坏。我见过团队升级技能后线上十几条工作流静默出错排查了很久才发现是新版本动了返回结构里的字段名。版本管理要从设计上就做好。技能配置里必须有version字段建议用语义化版本号。调用方引用技能时不要写死版本号而是按能力名引用具体解析到哪个版本由注册表按策略决定。新版本上线先用灰度策略跑一小段时间观察调用成功率没有异常后再全量切换。删除老旧字段时要保留兼容层至少给一个迁移过渡期。废弃技能要发布声明调用方的日志里也要能看出某个技能已经标记废弃避免新流程误引用。5.5 实战问题速查问题现象常见原因排查/解决建议技能选错描述含糊、候选集中没有互斥机制补充“不能做什么”添加易混样例做回归调用超时外部接口慢、无超时配置统一设置超时与重试执行体内外部调用单独控时结果重复重试不幂等引入幂等键重试前查询上次执行状态参数不对模型抽参失败、schema不明确区分必填可选提供默认值加程序化校验升级后旧流程坏无版本管理语义化版本灰度发布兼容层迁移技能库太大导致乱缺少治理按需加载候选技能建立标签和目录规范6. 在实际项目里我更推荐怎么落地Agent Skills最后分享几点属于“不试不知道”的经验。第一不要一上来就重构所有能力。理想中的技能库是完美的能力地图但实际项目都是从三五个高频痛点技能开始的。挑你最痛、调用最频繁、边界最清晰的三个能力先做技能化跑通注册、匹配、执行、观测的全流程让团队看到效果再慢慢扩大范围。上来就铺几十个技能治理成本会在团队还没尝到甜头时就把耐心耗尽。第二先定契约再写执行体。很多工程师习惯拿到需求就写代码技能化要求反过来先写清描述、输入协议、输出协议再补执行体。因为契约才是技能对外价值所在执行体只是实现细节。契约评审没通过执行体写得再漂亮也是白费。第三技能描述要请“第二个人”审核。写技能的人脑子里已经装了太多关于这个技能的理解很容易在描述里省略掉最关键的信息觉得“这么明显当然会被模型选中”。这个“第二个人”最好是没参与实现的人让他看看如果只知道描述和输入协议他能不能判断什么请求该走这个技能。判断不出来说明描述还不够模型大概率也看不明白。第四一定要把调用数据回流到技能迭代里。日志里记录的不只是成功和失败还有匹配分数、模型抽参结果、用户有没有负面反馈。定期翻一翻这些数据你会发现哪些技能描述经常导致误匹配哪些参数用户从来不提供哪些超时集中在哪个外部接口上。技能库不是一锤子买卖它是一个需要持续打磨的动态资产。Agent Skills这套思路说到底没有高深的理论它就是把软件工程里的模块化、契约化、可观测性老老实实搬到了AI应用层。大模型应用要走向生产可用靠的从来不是把更多指令塞给模型而是给模型搭一套清晰、稳定、可治理的能力骨架。希望这篇复盘能给你一些可以抄作业的细节。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化
这篇内容对您有启发吗?
预约一次免费方案沟通,我们会根据您的行业给出可落地的站点架构建议。
立即预约沟通