1. 从“会聊天”到“能干活”Agent 技能体系的本质过去两年我一直在折腾各类智能体项目一个很深的体感是同样是接了大模型接口有的 Agent 用起来像“玩具”有的却真的能顶半个实习生。差距不在模型智商而在技能Skills体系的完整度。所谓 agent-skills说白了就是给智能体装上一个个可复用、可编排的“能力插件”。聊天只是最基础的部分——真正的 Agent 得会查数据、调接口、写文件、跑流程、做决策而这些能力如果全部塞在提示词里很快就会乱成一团。技能体系的出现就是为了把“模型会什么”和“Agent 能干什么”这两件事解耦。我大概在两年前开始认真对待这个方向。当时做的一个模拟项目里需要让 Agent 同时处理信息检索、表格整理、报告生成三件事第一版用的是“一个大 prompt 包打天下”结果上下文一长就崩指令稍微含糊一点就答非所问。后来参考了几套开源智能体框架的 design把能力拆成了独立的 skill 模块效果立刻不一样了。这篇文章就把我踩过的坑和摸出来的门道完整写出来给正在做 Agent 开发的同行一些参考。2. 技能体系的设计思路与选型考量2.1 为什么不能把所有逻辑塞进 Prompt先回到最初的问题为什么一定要有“技能”这个中间层最简单的方案是让模型自己根据对话内容自由发挥比如你在 prompt 里写“你可以调用这些函数”然后给出一堆描述。这在 demo 阶段完全可行代码量少、见效快。但一旦进入真实业务场景问题就接踵而至。最典型的问题是指令遵循的不稳定性。模型不是机器它对自然语言的理解有概率性尤其是在长上下文、多工具、多步骤的场景下很容易漏调用、错调用或重复调用。我实测过一组数据同一个包含 5 个步骤的任务在纯 prompt 方案下模型完全正确地执行率只有六成出头而换成结构化技能方案后这个数字能拉到九成以上。另一个问题是可维护性。业务逻辑一变你得去改 prompt改完还得重新测试各种边角情况。但如果是技能模块每个技能就是一段独立代码有输入输出约定有边界情况处理改起来就像改普通函数一样清晰。还有一点很多人没意识到纯 prompt 方案下模型每次调用都要把全部工具描述塞进上下文。工具一多光描述性文本就占掉几千 token既贵又影响模型注意力。技能体系天然把描述收窄到“本次会话实际会用到的那几个”上下文占用和响应质量都会明显改善。2.2 技能和工具、插件、工作流到底什么关系在聊具体设计之前得先把这些名词区分清楚因为很多人一上手就混了导致架构越做越拧巴。我在实际开发中是这样理解的**工具Tool**是最小粒度一个函数级别的能力单元。比如“发送 HTTP 请求”“读取本地文件”“执行数学计算”都算工具。它不关心业务逻辑只做好一件事。**技能Skill**则是在工具之上做了一层封装和组织。一个技能可以调用多个工具也可以有自己的状态逻辑。比如“生成月度报表”这个技能内部可能涉及读取数据库、处理数据、格式化输出三个工具的配合。**工作流Workflow**是更上层的编排概念它把多个技能按业务时序串起来。比如“客户投诉处理”工作流可能先是“识别投诉内容”技能再是“查询关联订单”技能最后是“生成处理建议”技能。插件这个词在 Agent 生态里用得很泛我倾向于把它理解为技能的一种分发形式——带上依赖、带上配置装进一个包就能跑。搞清这层关系很重要因为很多项目失败就栽在粒度不对要么把一切当工具技能层缺失逻辑还是碎一地要么把一切当工作流过度编排稍微改一点流程就得重构僵硬得没法用。2.3 我最终采用的技能组织方案在综合评估了几个主流思路之后我目前采用的是“目录即技能、接口即约定、元数据即路由”这套组织方式。目录方面每个技能一个独立文件夹文件夹内包含一份描述文件说明技能功能、适用场景、一份参数定义描述输入输出结构、以及若干执行脚本Python 或 Node.js 都可以看你技术栈。这样每个技能天然具备可读性和可管理性新成员加入项目时扫一遍目录就能知道系统有哪些能力。接口方面我定义了统一的输入输出格式。所有技能统一接收一个包含任务上下文的 JSON 对象输出也是标准 JSON。模型层和技能层通过这套接口通信互不干扰。好处是技能内部不管怎么实现对外契约一致以后替换实现方案、升级某个技能不影响其他模块。元数据方面每个技能在描述文件里写清楚自己适用的情况和不适用的情况。这看起来是小事但实际影响巨大。模型在决定“该不该用某个技能”时就是靠读这些元数据做判断。写得太泛模型会误用写得太窄模型该用的时候不调用。这个度的把握后面会详细展开。3. 核心细节解析与实操要点3.1 技能描述文件的写法与调优技能描述文件是整个体系里最容易被低估的部分。很多人觉得技能的核心是代码逻辑描述随便写写就行结果上线后技能访问率极低模型根本不知道该在什么场景下用。我在多个项目里反复调过描述文本下面这份模板是我目前用得比较顺手的name: generate_report description: 生成数据统计报告。适用于需要将结构化数据转换为摘要性文字、图表或表格的场景。当用户询问“统计”“汇总”“报告”“分析结果”时优先考虑使用。 input: data_source: 数据文件路径或数据库查询结果必填 report_format: 输出格式可选值为 markdown、html、pdf默认为 markdown include_charts: 是否生成图表布尔值默认 false output: report_content: 完整报告内容字符串 success: 是否成功生成这份描述看起来简单但里面藏了几个容易踩的坑。第一个坑是触发条件写得过于笼统。比如只写“适用于数据分析场景”模型就可能在用户说“帮我看看这个文件”时调用来生成报告但用户其实只想预览前几行。把“当用户询问统计、汇总、报告时”这样的针对性描述写进去之后误调用率明显下降。第二个坑是输入参数没有标注必填可选。模型在参数缺失时有两个选择自己编一个合理值或者报错。让它自己编经常编出离谱的东西让它报错体验又很生硬。明确标注必填和可选配合合理的默认值这个问题基本能解决。第三个坑是未写负面条件。也就是“什么情况下不要用这个技能”。比如生成报告技能如果用户只是随口问一句“昨天数据怎么样”这种轻量对话不应该进报表生成流程。我在描述里补了一句“非正式对话、无需结构化输出时不要调用”误触发率降了不少。3.2 技能调度的核心逻辑技能调度的本质是让模型在合适的时机选择合适的能力这里面有两种主流路线。一种是完全由模型自主决策也就是把技能列表及描述全部交给模型让它自行决定调用哪个。这条路灵活、开发量小但对描述质量要求极高模型还是可能出现“明明有专门技能却绕远路用另一个”的情况。我实测下来技能数量超过十来个之后模型的选择准确率下降得比较明显。另一种是规则路由 模型兜底。先用关键词和正则做一个粗筛把明显匹配的技能先挑出来再把缩小后的候选集交给模型做精排。这样模型面对的选项少决策压力小准确率自然高一些。一个我实际项目中用过的简化路由逻辑的伪代码 def route_skill(user_input, all_skills): # 第一步规则粗筛找出语法关键词直接命中的候选技能 candidates [] for skill in all_skills: if any(keyword in user_input for keyword in skill.trigger_keywords): candidates.append(skill) # 第二步若没有规则命中则退化为全部技能走模型决策 if not candidates: candidates all_skills # 第三步模型精排从候选中选最合适的一个 return llm_select_best(user_input, candidates)这套“规则粗筛 模型精排”的架构几乎可以无脑搬到绝大多数 Agent 项目里。唯一需要注意的是粗筛的触发词要维护好避免出现过宽或过窄的情况这个维护周期大概每两周审视一次比较合适。3.3 技能之间的协作与数据传递很多任务不是单个技能能完成的必然要有多技能协作。协作最核心的问题只有一个数据怎么传。我最早的设计是技能 A 的输出直接作为技能 B 的输入一个接一个严格执行。但很快发现一个问题中间数据如果格式不吻合B 技能就会收到无法解析的内容。后来改成“共享上下文 显式引用”的方式效果好了很多。具体做法是这样的每个技能执行后输出内容写入一个共享的上下文存储可以是一个全局 JSON 对象也可以是外部 KV 存储技能之间不直接对接而是通过读写公共上下文来协作。每个技能在描述文件中显式声明自己会读取哪些上下文键、会写入哪些上下文键。“生成报告”技能和“数据汇总”技能的协作流程大概是数据汇总技能把统计结果写入summary_data键生成报告技能声明自己依赖summary_data调度层检测到依赖存在就执行报告技能依赖缺失则提前提示或触达上游技能。这套方案的优点是解耦清晰、排错方便。数据在哪个环节出了问题直接查上下文快照就能定位。3.4 参数的命定与校验技能的参数设计直接决定了整个系统的稳定性上限。我在迭代中总结出一套比较完整的参数生命周期管理流程定义、提取、校验、兜底。定义阶段每个参数都要写明类型、取值范围、默认值和必填性。这不仅是给模型看的也是给后续校验逻辑看的。提取阶段模型从对话内容中抽取参数值。这里有个操作要点一定要让模型用 JSON 格式输出参数提取结果哪怕只有一个参数。原因是 JSON 结构可以显式反映“哪个参数没填”比自然语言描述可靠得多。校验阶段要对参数做类型和范围检查。比如report_format只接受三种枚举值模型传了个xlsx进来校验层得在进入技能之前就拦截住否则技能内部报错排查成本高得多。我见过太多团队在这一层偷懒结果每次报错都要翻技能内部的日志才能定位效率极低。兜底阶段对于可选参数在技能内部设置默认行为对于必填参数缺失的情况明确让模型向用户追问而不是硬着头皮猜一个值。这一条极其重要我见过很多 Agent 因为“猜参数”猜出了严重错误。4. 实操过程与核心环节实现4.1 从零搭建一个技能模块的完整步骤下面用一个真实的例子完整走一遍实现一个“获取天气信息”的技能。这个技能简单但有代表性涵盖了参数提取、外部接口调用、输出定制等典型环节。第一步创建技能目录与描述文件。skills/ └── get_weather/ ├── SKILL.md ├── parameters.json └── main.pySKILL.md 文件内容我已经在上文给出了模板这里不重复。重点说一下 parameters.json 的设计{ city: { type: string, required: true, description: 目标城市名称需为中文正式名称如北京、上海、广州 }, date: { type: string, required: false, description: 查询日期格式为 YYYY-MM-DD默认当天, default: today }, unit: { type: string, required: false, description: 温度单位可选 celsius 或 fahrenheit默认 celsius, enum: [celsius, fahrenheit], default: celsius } }这里有个经验点unit字段用枚举约束比让模型自由发挥要稳得多。模型不是不懂温度单位而是在生成 JSON 时存在一定的随机性偶尔给你拼个℃之类的变体出来。枚举值定义得清清楚楚才能在源头规避这些花式问题。第二步编写技能主逻辑。以 Python 为例技能入口函数的定义可以这样写import json from typing import Optional def execute(params: dict, context: dict) - dict: city params[city] date params.get(date, today) unit params.get(unit, celsius) # 这里替换为真实天气服务商的 API 调用 weather_data fetch_weather(city, date) # mcp 中诸如此类的结构化协议也可以接入按需扩展 result format_weather(weather_data, unitunit) return { success: True, result_text: result, result_data: weather_data }这段代码里有几个细节值得留意params.get(date, today)体现的是参数兜底逻辑返回结构里同时包含result_text自然语言结果和result_data结构化数据这样下游既可以展示给用户也可以继续做二次处理比只返回一种格式灵活得多。第三步注册技能并配置注入方式。在配置文件里把技能路径和名称加入到技能列表。注册完成后模型就能在决策时看到这个技能及其描述。第四步本地联调与日志输出。这一步我会建议做三件事跑通“模型能正确识别调用意图”的 case跑通“参数正常提取”的 case以及跑通“参数缺失时能正常追问”的 case。这三个 case 是最基本的分水岭过了这关技能才算半可用。4.2 技能上下文的有效管理与隔离策略技能执行过程中会涉及大量的上下文读写如果管理不善很容易出现“这个技能读到的数据是上个技能污染过的”这类问题。在实际项目里我采用了一套两层上下文隔离方案。全局上下文存储用户基本信息、会话目标、对话历史等跨技能共享的数据。所有技能都可读只有调度层可写。局部上下文每个技能有自己的局部临时存储只存放本次执行中产生的中间数据。技能执行完毕后把需要共享的结果显式写入全局上下文中“自己对应的区域”。这个设计的好处是技能的局部数据不会污染全局多个技能并行执行时互不干扰。比如两个技能同时读全局里的用户信息各自处理后只有把结果写回指定区域时才会影响到其他技能而这个写入动作是经过调度层同意的。实际操作中我在每个技能执行前会快照一份全局上下文执行完再做个 diff用于追踪这个技能到底动了哪些数据。这个习惯在调试阶段帮了大忙——因为经常出现“某个技能意外改了所有人的数据”这种匪夷所思的 bug。4.3 技能的可观测性建设Agent 项目里最让人头疼的就是“黑箱感”——你只知道输入和输出中间过程完全不可控。技能体系的优势在于它是天然的结构化单元这给可观测性建设提供了很好的基础。我的每个技能都强制输出了几类日志入参日志记录收到的参数内容不包括用户敏感信息决策日志记录为什么选择这个参数值如果这个值来自模型猜测单独标记出参日志记录返回给调度层的结果异常日志技能内部报错时记录完整堆栈和当时入参快照。这套日志体系建立后绝大多数问题都能在几秒钟内定位到具体技能、具体参数、精确到哪一行代码出错。在没有日志体系的阶段排查问题往往要耗费数小时这是我觉得最值得投入的一笔建设。4.4 技能的动态加载与热更新最后聊一个很多项目做到后期才会遇到的问题技能如何动态更新。如果你把技能全都写死在代码里那么每次新增或修改技能都得重新发版。这在个人项目里还行但在生产环境、尤其是商业化产品里是不可接受的。我用的方案是将技能清单和相关代码放到独立的存储位置运行时动态加载。技能清单放在存储里后每次会话启动时读取一次最新版本。这样运营人员更新技能描述、调整触发词甚至新增一个技能都无需重新发布主程序。这带来两个很实际的好处一是迭代速度更快二是可以按人群/场景分批次灰度不同技能配置。这个方案也有代价动态加载对技能的目录结构和接口约定要求更严格乱写就很容易出现加载失败或者新版技能与老数据不兼容的情况。所以我加了版本号机制每个技能目录里都放了一个版本字段加载时检查版本兼容性不兼容的自动回退到上一稳定版本。5. 常见问题与排查技巧实录5.1 模型总是选错技能怎么办这是我从始至终遇到频率最高的问题也是让开发者最焦虑的问题。它在传统软件里没有类似物——因为传统代码里不存在“决策偏差”这种概率性 bug。排查顺序我基本遵循以下固定路径先看技能描述是否足够区分度。如果两个技能描述高度重叠模型自然容易混淆。比如“生成摘要”和“提取要点”听起来几乎是一回事模型抓瞎是正常的。再看触发条件是否写清楚。很多开发者只写“适用于某类场景”但没写“不适用于什么场景”模型就很容易在非目标场景里误用。还要确认是不是上下文信息不足。如果模型根本不知道当前场景的全貌你怎么写描述它都很难选对。检查排序逻辑。同一层级的技能排列顺序对部分模型的决策有影响试着把常用技能排前面。如果上面四步都走完了还选不对就得考虑上规则路由了——把高频场景直接硬编码映射到特定技能跳过模型的自主决策。5.2 参数提取错误频发如何根治参数提取错误是最常见的技能执行失败原因。模型在从对话中提取参数时总会出现诸如“把城市理解成区县”“把日期读成格式不同的字符串”“把单位搞混”这类问题。我的经验是四个字别让模型猜。具体做法是参数缺失时直接引导用户补充而不是让模型自己造一个看起来合理但实际错误的值。同时尽可能用结构化的参数提取指令要求模型按 JSON schema 输出并且只用它看到的事实信息不推断、不补齐。5.3 技能执行超时的处理策略很多技能涉及外部 API 调用慢是不可控的。为了不让单个技能拖垮整个会话我引入了超时和重试机制。核心参数是“超时阈值”和“最大重试次数”。这两个参数的取值要根据技能类型调整本地计算的技能超时阈值设短一些外部接口的技能就设长一点。如果你做一个以对话为主的 Agent建议超时后先给用户一个缓冲回复比如“正在处理中请稍等”后台任务继续跑完后再把结果推给用户。5.4 上下文爆炸与记忆混淆的应对多技能协作时中间数据越来越多几轮对话之后上下文就容易膨胀。上下文一长模型的注意力就开始涣散很容易把不同技能的数据搞混。我在这方面踩了好几次坑有一套比较成熟的应对方法中间数据瘦身。每个技能执行完写入全局上下文之前先做一个裁剪只保留真正影响后续决策的字段。比如“天气查询”技能只需要保留温度和天气描述即可原始接口里的所有中间响应一律不进上下文。按会话阶段性清理。根据任务的进行阶段动态清除已不再需要的中间数据。比如报告生成完成后原来的数据汇总中间结果就没必要继续保留在上下文里。记忆分层存储。用户长期偏好这类信息放在持久化层任务中间数据放在短期存储技能内部临时变量只存在技能执行期间。各司其职互不干扰。5.5 调试 Agent 技能时的高效工具最后分享一个调试技能时我觉得特别有价值的小工具回放式调试器。它的核心思路是把一次完整的 Agent 执行过程记录成结构化日志包括模型输入输出、每次技能调用参数和返回结果。出问题的时候可以像看视频一样一步步回放看模型在哪个节点做了错误决策、为什么做这个决策。有了这个工具排查效率提升了不止一个量级。回放式调试的具体实现上我加了时间戳和上下文快照方便对比不同实验之间的差异。6. 我的判断技能体系是当前 Agent 落地的关键分水岭说实话我见过很多团队把大模型接入做得非常娴熟但项目依然失败了。失败的原因很少是模型选型的问题而是 Agent 的能力组织方式出了问题。技能体系看起来像是一个技术架构问题但它本质上反映的是产品思维一个 Agent 能解决什么任务、不能解决什么任务、在什么条件下调用什么能力这些必须被显式地定义不能交给模型自由发挥。有一点我特别想强调技能体系的建设不需要一开始就追求大而全。从一个高频场景、一个技能模块做起跑通之后再横向扩展是最务实的路径。很多项目死在起步过度设计一个人维护几十个技能结果每个技能都半生不熟。我自己的做法是先做三个核心技能观察真实使用数据然后持续迭代补充三个月之后技能库自然长到了一个合适规模。再分享两个实践中沉淀下来的习惯算是给后来者的礼物第一个是技能命名一定要“实”。在技能命名上用过一些花哨的术语看起来酷但模型在选择时很容易误解。宁愿用一个朴素直白的名字比如send_email而不是communication_facilitator换来的是决策准确率的提升。第二个是给每个技能写一句话级别的“成果定义”。也就是说这个技能执行成功到底意味着什么产出是什么形态。这件事想不清楚的时候技能设计通常都是含糊的写代码时你会发现边界模糊得不行。技能体系的深度和成熟度才是决定一个 Agent 项目能否走出演示环节的关键。越早重视技能设计项目的地基就越稳。