1. 从提示词到技能agent-skills到底在解决什么问题做AI Agent时间长了你会发现一个很微妙的分水岭。早期大家玩Agent更多是在琢磨怎么把Prompt写得足够精细让模型表现得聪明一点。但项目一旦跑起来Agent要处理真实业务的时候光靠提示词就不够了——你可能面对的是一个需要调用十几个工具、跨多个系统、还要保持输出格式稳定的任务流。这时候这个Agent会什么就变成了一个工程问题。agent-skills这个概念本质上就是在回答这个工程问题。它不是让模型想得更聪明而是让Agent会做更多事。你可以把一个技能理解成Agent能力的基本单元一个技能封装了模型完成某类特定任务时所需的全部要素——包括触发条件、执行流程、工具调用方式、参数定义、输出格式甚至包括异常处理和边界约束。换句话说技能是把模型的能力固化成流程的手段。这篇文章我想聊的就是围绕agent-skills展开的一套完整实践心得技能体系应该怎么设计、每个技能内部怎么拆解、多个技能如何编排协作以及我在实际项目中踩过的那些坑。适合正在做Agent应用开发、或者准备把Agent从Demo推向生产的团队参考。里面的经验不一定适用于所有场景但方法论是通用的。我始终觉得Agent应用做得好不好跟底层模型关系没想象中那么大反而跟技能这层中间件设计得合理不合理关系很大。接下来我用自己的项目经历把这条链路从头到尾拆一遍。2. Agent技能体系的设计思路2.1 一次任务驱动的技能重构从零散工具到结构化能力我先交代一下项目背景。当时我们团队接了一个企业内部的知识管理Agent需求核心任务是让Agent能自动从各个业务系统里收集数据、整理成结构化信息、生成分析报告最后推送到协作工具。最开始我们按工具调用的思路来设计——定义了一堆函数比如query_database、fetch_api、send_message让模型根据用户意图自己组合调用。实话说第一步跑通的时候效果还行。但越往后越不对劲用户的需求稍微复杂一点比如总结上周各地区的销售数据和上个月做对比然后给每条产品线写一份简短的走势分析模型就会开始自由发挥——有时候它先查了全年数据有时候它忘记做对比有时候它生成的报告格式长得完全不一样。你会发现模型不是不会调用工具而是它根本不知道该按什么顺序、什么标准来执行一整个流程。这就是工具思维和技能思维最核心的区别。工具解决的是能做什么技能解决的是该怎么做。我们在设计agent-skills的时候把原来那些散的函数调用重新组织成了一个个有明确目标、有步骤约束、有输出标准的技能模块。比如数据分析这个能力不再是模型随时可以调用的一个API而是一个完整的数据分析技能——它规定了输入数据源、分析维度、对比方法、报告模板甚至规定了中间每一步的校验规则。这个重构带来的第一个明显变化是稳定性的提升。模型不再是临场发挥而是在一个设计好的框架内执行自由度被限制在合理范围内。第二个变化是可维护性上来了业务要加新的分析维度不需要重新调Prompt只需要改技能内部的配置。2.2 技能粒度怎么定拆得太细和拆得太粗都是坑设计技能体系时最容易被忽视却也最关键的问题是技能的粒度应该怎么把握。我见过不少团队把技能拆得极其精细每个技能只做一件小事比如格式化日期去重列表这种级别。结果就是Agent要完成一个稍微复杂点的任务需要串起十几个技能中间的参数传递、上下文衔接变得异常复杂模型出错率反而更高了。反过来也有走极端的把所有东西都塞进一个超级技能内部用一大堆条件分支来处理不同场景。这种做法的缺点是技能内部逻辑变成了黑盒一旦某个环节出错排查成本非常高而且技能很难复用——你会发现生成周报和生成月报明明大量逻辑重叠却因为被写死在两个大技能里只能各维护一套。我现在的实践经验是技能粒度应该以一个可独立验证的业务动作为单位。什么叫可独立验证就是这个技能做完之后产出的结果可以被明确地判断对不对。比如从数据库查询原始数据是一个技能生成对比分析报告是一个技能将报告格式化推送到企微群又是一个技能。每个技能内部可以有多个步骤但这些步骤服务于同一个业务目标对外暴露的输入输出是清晰的。判断粒度合不合适我还有一个很笨但很有效的办法给每个技能写文档如果写文档的时候发现有超过20%的篇幅在描述什么情况下不该用这个技能那大概率是粒度拆错了。真正好用的技能场景应该是收敛的。2.3 技能的输入输出契约一切稳定性的根基工程师都知道约定优于配置这句话在Agent技能设计里输入输出契约就是那个约定而且它的重要性远高于传统软件开发。原因是传统接口的调用方是代码行为是确定的但技能的调用方是模型模型的理解天然存在波动。如果技能定义里参数含义模糊、输出格式不严格模型就会在边缘情况下产生各种意想不到的理解偏差。我在项目里定义的技能契约一般包含这么几块技能名称、适用场景描述、输入参数表包含参数名、类型、取值范围、默认值、必填与否、输出格式定义、执行步骤说明、错误处理策略以及几条使用注意。其中最容易被忽视的是适用场景描述——这段文字不参与技能内部的执行但它写得清不清楚直接决定模型会不会在错误的时候调用这个技能。输出格式方面我也吃过亏。早期我们让技能自由输出文本结果模型写报告的风格每天都在微调今天用表格明天用列表今天先总结后明细明天先明细后总结。后来我们把输出格式全部改成严格的schema约束跟工具调用的function calling类似必须输出结构化字段再由渲染层负责展示。这一步实施之后输出的稳定性有了质的提升。2.4 技能注册表让Agent知道自己会什么有了技能模块下一步就是解决Agent怎么知道自己有哪些技能可以用的问题。这就是技能注册表的作用。从实现上讲它就是一个结构化的清单每次模型做规划之前系统会把注册表里的技能描述注入到上下文中让模型根据用户需求挑选合适的技能组合。这个环节有一个性能陷阱。当技能数量从几个增长到几十个的时候把所有技能描述全量塞给模型会占用大量上下文窗口不仅变慢还可能干扰模型对核心信息的注意力。我在项目里做了一级粗筛先根据用户请求的语义做一个技能召回只把相关性高的几条技能描述注入上下文。这一步用的是轻量级的向量检索命中率实测下来95%以上而且大幅节省了Token消耗。注册表里除了技能本身的描述我还会维护一个技能间关系的字段——标注哪些技能经常搭配使用、哪些技能存在前置依赖。这个信息对模型做任务规划很有帮助相当于给模型一张地图让它知道流程可以怎么走而不是每次都靠模型自己摸索。3. 技能模块的完整拆解以数据指标对比分析为例3.1 技能内部的五个层次纸上谈兵没什么意思我拿一个真实的技能模块出来拆开看。这个技能叫数据指标对比分析它解决的问题是给定一个业务指标和两个时间周期自动从数据库取数、计算变化率、识别异常波动、并输出一份带自然语言解读的分析结果。整个技能内部我分成了五层。最底层是数据访问层负责连接不同的数据源——可能是MySQL、ClickHouse也可能是内部API这一层对上层屏蔽了数据来源的差异。再往上是计算层负责指标口径的核对、同环比的计算、异常检测算法我们用的是简单但有效的3σ原则加趋势判断。第三层是语义层把计算结果转成自然语言结论比如华东区销售额环比下降12.3%超过阈值需要关注——这一层我通常会写清楚语言模板防止模型自由发挥出奇怪的说法。第四层是组装层把数据结果、结论文本、图表参数按标准格式聚合成结构化输出。最上面一层是校验层检查输出结果是否满足技能定义里的schema要求不满足就触发重试或报错。分层的核心理念是每一层只干一件事模型只在语义层和组装层参与文本生成计算和数据操作全部由代码控制。3.2 技能定义文件里到底写了什么下面是一个简化后的技能定义文件示例真实项目里会复杂一些但核心结构可以参考skill: name: data_metric_compare description: 对比分析指定业务指标在两个时间周期内的变化情况输出结构化报告。 适用场景: - 用户要求分析同比/环比变化 - 用户要求对比两个时间段的表现 - 用户需要指标波动的解释说明 输入参数: metric: type: string required: true description: 业务指标名称必须在系统指标字典中存在 current_period: type: string required: true description: 当前分析周期格式为 YYYY-MM-DD ~ YYYY-MM-DD baseline_period: type: string required: true description: 对比基准周期格式同 current_period 输出格式: type: object properties: metric_name: string current_value: number baseline_value: number change_ratio: number is_abnormal: boolean abnormal_reason: string summary_text: string 执行步骤: - 校验指标名称是否在指标字典中 - 从数据源读取当前周期和基准周期的聚合值 - 计算变化率和差异绝对值 - 根据阈值规则判断是否存在异常波动 - 调用语义生成层撰写解读文本 错误处理: - 指标不存在: 返回明确错误信息不尝试猜测指标含义 - 数据为空: 返回空数据提示不生成虚假结论这个文件看起来简单但每一行都有讲究。拿适用场景来说当初我们没有认真写这段结果模型经常拿这个技能去回答今天周几这种问题不是模型蠢而是描述不够精确。后来我把适用场景写成三四条具体的句子误用率立刻降下来了。输入参数的类型和格式标注也很关键如果不写清楚格式模型可能给你传一个上周这样的自然语言值导致解析层崩溃。3.3 为什么技能必须包含错误处理而不是让模型自由发挥很多团队在写技能定义时完全没有错误处理的部分。他们的逻辑是反正模型很聪明遇到问题它会自己想办法。这句话在某些场景下成立但在生产环境里非常危险。模型自由发挥处理错误最常见的结果是编造一个看似合理的结果或者反复尝试同一个错误操作浪费时间。我举个例子。有一次我们的分析技能在半夜执行任务时发现目标数据库连接超时模型没有报告错误而是基于上一次的缓存数据继续生成了一份报告而且完全没有标注数据时效性问题。第二天早上业务团队看到报告后差点基于过期数据做了决策。从那之后我把所有技能的错误处理策略统一成三条原则第一拿不到数据就明确说拿不到绝不编造第二执行失败就按定义的兜底流程走比如发一条需要人工关注的提醒绝不静默吞掉异常第三重试不做无脑循环最多试两次第二次失败必须触发告警。这条经验也改变了我们对模型能力边界的认知。模型擅长的是理解和生成但严谨性这件事不能依赖模型自觉必须通过工程手段来兜底。技能里的错误处理就是第一道兜底防线。4. 多技能协作与编排从单个技能到工作流4.1 模型规划与技能编排的边界在哪里单个技能设计得再完善也只是一个零件。真实业务场景里Agent通常需要串起多个技能来完成一个完整的任务流。比如生成一份竞品周报至少要经历收集数据网页抓取技能、清洗去重数据清洗技能、指标分析对比分析技能、文本生成报告撰写技能、推送分发消息通知技能。这个编排过程应该由谁来主导模型还是预定义的流程这是每个Agent开发者都要回答的问题。我的观点是能用流程固定的不要依赖模型临场规划。道理很简单模型规划的不确定性是生产系统最大的不稳定因素。同一个任务模型今天可能规划三步完成明天可能规划五步每一步之间的数据交接还可能出岔子。对于业务固定、链路清晰的任务直接用工作流编排引擎把技能的调用顺序定义死只有遇到真正的意外情况时才把控制权交还给模型。那模型规划还有用吗用但用在那些真正需要动态决策的任务上。比如用户提出一个开放式需求系统需要从技能库里挑选合适的技能组合这种时候模型的规划能力就很重要。我们内部的做法是双轨制跑批任务全部走预设工作流交互式任务允许模型动态规划但规划结果必须经过一个合法性校验器检查技能是否存在、参数是否齐全、依赖是否满足。4.2 技能编排中的上下文传递技巧多技能协作最常见的工程难点是上下文在不同技能之间怎么传递。我见过很多实现把前一个技能的所有输出一股脑塞给下一个技能结果上下文窗口迅速膨胀而且里面大量无关内容干扰了模型对关键信息的提取。我的做法是设计一个共享上下文结构整个工作流内所有技能共享这个结构但每个技能只能写入自己负责的字段读取时也只读取跟自己相关的部分。比如分析技能负责写analysis_result字段报告技能读这个字段生成文本同时报告技能还需要原始数据的概要信息那它直接引用raw_data_summary字段而不是去读完整的原始数据集。这样做的好处是上下文可控、信息不会因为传递而丢失、每个技能的执行结果都有明确的落点便于审计和排查。另外还有一个小技巧就是每个技能执行完在当前上下文中追加一段执行摘要——一两句话说明这个技能做了什么、产出了什么、有没有异常。这段摘要对模型后续的决策非常关键它相当于一个记忆锚点。我们在实践中发现加了执行摘要之后模型在长链路任务中忘记前面做了什么的错误率下降了一半以上。4.3 工作流编排的失败模式与降级策略流程编排看上去是按顺序调用技能那么简单但真实跑起来你会遇到各种各样的失败模式。我给你盘点一下最常见的几种技能A成功但技能B失败整个流程要不要回滚技能A输出的数据格式跟技能B期望的不一致谁来负责转换某个技能长时间无响应是继续等待还是超时跳过技能链路中出现循环依赖怎么检测我们的处理策略有几条硬性规则第一所有技能调用必须有超时设置超时后默认走失败分支第二关键技能比如数据写入类失败时整个流程中断并告警不允许继续往下走第三非关键技能比如美化格式失败时允许跳过并使用默认值但要在最终结果里标注部分内容未生成第四流程状态全量落盘每一步的输入输出都记录在案这样排查问题的时候能找到准确的现场。降级策略这块我的核心原则是宁可让用户看到部分结果也不要让用户看到错误结果。比如报告生成流程里如果图片渲染技能挂了我们不会让整个报告失败而是生成一份纯文本报告并标注图表生成失败已转为文本模式。用户拿到的是一份可用的结果同时系统自动发起告警通知维护人员处理。这种体验比流程执行失败请稍后重试好太多了。5. 实战案例用技能体系搭一个竞品情报分析Agent5.1 需求拆解与技能选型光讲理论没有说服力我拿一个完整案例收尾。我们当时要做的是一个竞品情报分析Agent目标用户是市场部的同事。他们的日常工作之一是每周收集竞品动态包括竞品官网更新、招聘信息变化、社交媒体动态、第三方平台的版本发布记录然后整理成一份周报。需求拆解下来核心能力包括四块多渠道信息采集、去重归类、趋势对比、报告生成。对应到技能体系我们设计了五个技能网页信息采集技能、信息清洗去重技能、变更识别技能判断某个竞品这周跟上周相比有什么变化、趋势分析技能、周报生成技能。前四个是处理型技能最后一个是把前面所有处理结果结构化输出的报告技能。这个案例我觉得很有代表性因为它覆盖了技能体系的多种典型场景有外部依赖网页抓取、有数据加工清洗去重、有对比推理变更识别、有分析判断趋势分析、有内容生成周报生成。而且每个技能的成败边界都很清晰非常适合用来验证技能设计的好坏。5.2 关键实现变更识别技能的设计细节这个案例里最有意思、也最需要细致设计的是变更识别技能。它做的事情是拿到同一个竞品网站这周和上周的抓取快照识别出哪些内容发生了变化并判断变化的重要性。听起来简单做起来有好几个坑。第一个坑是不同页面的噪音太多导航栏、版权信息、Cookie提示几乎每周都一样如果不做内容归一化处理这些噪音会被识别成变更导致报告里全是无效信息。我们的做法是给页面做区块切割只保留主体内容区域再做diff。第二个坑是变更的语义理解——同样是新增了一个职位在关于我们页面出现可能只是普通的团队扩张在招聘页面出现则可能意味着业务方向调整。为了处理这个语义差异我们给变更识别技能增加了一组注意力规则优先关注招聘页、产品页、定价页的变更并按变更内容做多级分类。第三个坑是模型的输出置信度不可靠它可能把一次普通的文案措辞调整判断成产品战略变化。我们用的妥协方案是所有判断结果必须同时输出原文摘要和判断理由如果判断为高风险变更必须附上原文截图作为证据。这样一来即使模型判断有偏差人工审核时也能快速还原现场不至于被误导。5.3 实操效果复盘哪些技能真正提升了效率这个Agent上线跑了两个月之后退役了原有的人工周报流程这里有几组数据值得一提。在技能体系还未充分打磨的第一周周报生成的成功率只有60%左右大部分失败集中在采集环节的网页反爬以及信息清洗阶段的误删。随着技能定义逐渐完善特别是加入了错误处理策略和重试机制后成功率稳定在了95%以上剩余失败场景全部会自动告警由人工兜底修复。有两类技能升级带来的收益最明显。一类是信息清洗去重技能过去模型经常把同一新闻的不同转载源当作不同信息导致周报里出现重复内容后来我们在技能内部加了URL归一化和正文相似度计算重复率从30%降到了5%以下。另一类是周报生成技能过去生成格式经常漂移业务方每周都要手动调整排版后来数据完全结构化之后渲染层面彻底解耦格式问题基本绝迹。这个案例也验证了我开头那个判断Agent的上限由模型决定但下限由技能体系决定。没有一套设计良好的技能体系再强的模型也只能是一个聪明的玩具成不了可靠的生产工具。而技能体系的构建本质上是一个把不确定性不断转化为确定性的过程——每定义一个技能就等于把一类模糊的能力诉求变成了一个边界清晰、可执行、可验证的工程模块。最后分享一个我在整个项目里体会最深的小技巧给Agent加技能这件事一定要跟着真实业务线索走哪怕只是顺手的一小步也别急着做通用大而全的技能库。我在实践中发现最好的技能沉淀路径是先从具体任务里拆出雏形跑一段时间等模式稳定了再抽象、再泛化。技能不是设计出来的是长出来的。这就是agent-skills带给我最大的认知转变。