1. 从会聊天到会干活Agent Skills到底解决什么问题我做AI Agent相关的项目差不多两年了踩过的坑比写过的代码还多。最早期的时候圈子里流行的是把所有指令塞进提示词指望大模型自己领悟该怎么干活。Demo阶段确实惊艳可一上真实业务就露馅模型今天记得调接口明天忘了同一个任务换个提问方式执行顺序就乱了。后来我逐渐意识到我们缺的不是更聪明的模型而是一套让Agent稳定执行任务的肌肉记忆。把这种肌肉记忆沉淀成一个个可复用、可单独调试的模块就是agent-skills这个方向存在的根本意义。1.1 单纯靠提示词让Agent干活瓶颈在哪拿一个我早期做过的案例来说。当时要做一个自动整理周报的Agent提示词里写得很详细——请从邮件、IM、项目管理系统里收集本周任务按项目分组输出Excel表。听起来没什么问题真实跑起来全是问题。第一个问题是数据来源的口径漂移。邮件里说的本周任务是按周一开始算的项目管理系统里的本周可能按上周五截止两边的数据对不上。模型不会主动发现这个差异它只会默默把两边数据拼接在一起然后给出一个看着挺合理的结果。第二个问题是错误被悄悄消化。某个数据源接口超时Agent没有停下来报告而是自己发挥想象力补了一段数据进去。这在演示环境里看不出来放到生产环境就是事故。第三个问题更隐蔽——提示词越长模型越容易丢失重点。你把本周的判定标准去重规则异常处理方式全部塞进一段提示词里指令之间反而会互相干扰。而且提示词是无法拆解的换一个任务场景所有内容都要推倒重来。当时我反复思考一个问题人是怎么解决这些问题的答案是——人会把整理周报数据这套流程固化成自己的操作习惯下次直接用不用每次重新思考。Agent需要的就是这种固化能力技能模块就是这种固化的载体。1.2 技能Skills和工具Tools、工作流Workflows的边界很多人会把技能“工具”“工作流”这三个概念混在一起我最初也绕晕过。用大白话捋一遍工具Tools是原子操作比如发送一条HTTP请求“读取一个文件”执行一段Python代码。它们是Agent的手指,一般由框架提供或者由外部API封装而来独立且无状态。技能Skills是由多个工具调用组合成的、能完成一个完整业务子任务的功能模块。举个例子从网盘批量下载本周报表这个技能内部可能依次调用获取访问令牌识别报表目录匹配文件名并发下载校验文件完整性五步。技能是面向具体业务场景的、可复用的能力单元——这是整个agent-skills架构里最核心的一层。工作流Workflows是把多个技能按业务规则串联起来的编排层可以带条件分支、循环、超时重试、人工审批节点。比如周报自动生成工作流调用收集数据技能然后调用生成摘要技能再调用发送报告技能最后等负责人确认。工具是手技能是手的连贯动作工作流是编排整套动作的舞谱。做agent-skills项目重点要打磨的恰恰是中间这层——技能。工具层太底层通用性高但业务价值有限工作流层太顶层跟具体业务强绑定很难跨场景复用。**只有技能层既具备足够的业务抽象又保持相对稳定的复用边界。**这个认知上的转变是我后来重构整个Agent项目的最重要起点。2. Skill的系统设计输入契约、输出契约与状态管理确定了要把技能作为核心设计单元之后下一个问题就是一个技能模块到底应该长什么样我见过很多团队拿给模型写一段好提示词的思路来设计技能结果做出来的是一个高级提示词模板。这完全跑偏了。技能模块的本质不是提示词而是一段经过封装的、可执行的任务逻辑它有明确的边界、可验证的输入输出、独立的错误处理。2.1 为什么必须先定义输入输出契约我先讲一个反面案例。团队里一个同事做了个客户反馈分类技能输入是一段客户留言文本输出是分类标签。听起来很清晰对吧实际使用中才发现分类标签到底有哪几类他没定义——有时候返回投诉有时候返回退款意愿强同一个意思多种表达。下游做统计的同事为了兼容这些五花八门的标签光清洗数据就花了三天。这就是典型的输出契约缺失。设计一个技能时第一件事不是写实现而是把输入输出彻底定死输入契约至少要明确三点参数名、类型、约束范围。以客户反馈分类为例输入参数应该是{ text: string, max_length: int, language: zh | en }而不是把客户留言传进来。参数约束越清晰技能的可控性越强。输出契约则是一个结构化的JSON Schema比如{ category: 投诉 | 咨询 | 表扬 | 退款 | 其他, confidence: 0.0, key_phrases: [响应慢, 客服态度差], needs_human_review: false }定义输出契约的好处是所有下游逻辑都可以基于稳定的结构去处理而不是依赖自然语言描述。实践里还可以再加一个fallback_reason字段——当技能无法处理某个输入时返回这个字段而不是甩给模型自由发挥。提示写技能设计文档时把输入输出契约放在最前面比先把实现代码写出来要省力得多。先想清楚边界再谈实现能帮你省掉后面80%的麻烦。2.2 状态管理与上下文传递的三种做法技能设计里另一个绕不开的问题是技能执行过程中需要跨步骤传递临时数据时状态放在哪我实践下来有三种做法各有适用场景第一种无状态技能Stateless。技能内部把任务一次性完成不保留任何中间状态。比如URL抓取并提取正文技能输入URL输出正文文本一次搞定。这种技能最简单、最稳定、也最容易被多个Agent复用是默认推荐的做法。第二种外部状态存储External State。技能执行过程中把中间结果写入Redis、数据库或对象存储。适用于多步骤、可能要跑几分钟的重型技能。比如批量处理1000张图片每处理完一张就把结果写入数据库中途崩溃了可以断点续跑。这种方案的关键是状态读写要和技能逻辑分离否则技能就没法摆脱具体的运行环境了。第三种会话上下文透传Context Passing。技能接收一个context对象里面带着前面步骤的结果、用户偏好、业务元信息。这种方式在现代Agent框架里最常见因为整个技能链条本来就是靠上下文串起来的。但要注意context越大模型和技能的负担越重处理时需要做裁剪和摘要。我个人的组合策略是常规技能一律无状态重型任务用外部存储需要多技能协作时用轻量级context传递关键信息而不是把整个历史一股脑传下去。2.3 技能描述怎么写才能让模型准确调用技能有了还得让Agent知道什么场景下该调用它。这靠的是技能的description字段——这是决定技能调用准确率的关键却常常被当成可有可无的装饰。写得好的技能描述应该像一个清晰的服务说明。举两个例子对比写得差的description: 对文本进行情绪分析。写得好的description: 当用户需要判断一段中文文本蕴含的情感倾向积极/消极/中性或需要从客户反馈中提取情绪信号时使用此技能。输入stext为原始文本返回情感标签及置信度。若文本长度超过5000字请先截断。不要用此技能做文本分类那是text_classifier技能的工作。注意到差别了吗好的描述包含触发条件When、输入说明What、约束边界Limits甚至还告诉模型这个技能不适合做什么。这样做有两个直接好处一是减少误调用——模型不会把一个分类任务错误地交给情绪分析技能二是减少无效调用——你知道这个技能处理不了超长文本先截断再传。给所有技能写描述的时候我都要求按触发场景 输入期望 输出格式 不适用场景这个模板来。写入框架后实测技能调用的准确率从70%出头提升到了90%左右效果立竿见影。3. 从零搭建一个技能库目录规划与技能实现流程设计好单个技能的系统结构之后下一个大问题是技能库整体怎么组织这不是一个简单的建几个文件夹的问题。技能库本身是一个会持续演进、会腐烂、会被团队多人修改的资产组织方式决定了它的生命力和复用率。3.1 先给技能库画边界什么该收什么不该收很多人的第一个技能库是从把有用的小功能都塞进去开始的。没有边界技能库很快就会变成垃圾场——每个技能都很有用但谁也不知道该用哪个。我建议按照业务域 能力类型两个维度来圈定边界。业务域解决这个技能是给谁用的例如销售域客服域数据域能力类型解决这个技能干什么活例如信息提取内容生成数据分析系统操作。用这个框架来取舍一个技能要进入库至少要满足三个条件——第一面向明确的业务场景第二具备跨任务复用的可能第三实现逻辑已经验证稳定。一次性脚本、临时Hack、个人偏好型的加工逻辑都不该进技能库把外部API直接包装成技能的做法也尽量少用。技能库不是API网关注册中心它要保存的是经过思考后的业务逻辑不是纯粹的传输层封装。3.2 一个技能从抽象到落地的完整流程以我最近给团队做的合同关键条款抽取技能为例完整走一遍流程第一步需求抽象。业务方提的需求是帮我看一眼合同告诉我哪些条款有风险。这句话太模糊不能直接做成技能。我把它拆解成更明确的子任务抽取合同双方名称、合同金额、付款节点、违约责任、保密期限、解约条件。每个子任务都对应明确的信息抽取目标。第二步定义输入输出。输入是合同的PDF路径和页数范围输出是上述字段的结构化JSON。这个定义过程要跟业务方反复确认尤其是风险的判定标准——业务方真正想要的不是判断风险而是提取出人工判断风险所需的全部信息。第三步选型与实现。合同大概率是PDF格式先用解析库提取文本然后分段送入模型做信息抽取。这个技能同时涉及PDF解析文本切片结构化抽取多个底层能力但它对外暴露的是一个统一入口传入合同文件得到结构化字段。第四步编写技能描述与测试用例。准备20份真实合同脱敏后作为测试集记录抽取的准确率、漏抽率、格式错误率。达不到预期就迭代直到稳定。第五步接入Agent场景。把技能注册到多Agent协作环境里让合同审查Agent在实际任务中调用它。这五步缺一不可但最容易被跳过的是第四步——测试。一个没有测试用例的技能就是一个不知道什么情况下会出错的定时炸弹。我的最低要求是每个技能必须伴生至少5个典型测试用例和2个边界用例否则不允许合入技能库主线。3.3 技能命名与版本号小细节大麻烦命名这个事看着小等技能库里有了两三百个技能你会发现命名混乱比代码混乱更让人头疼。我的命名规范是业务域-能力-对象-形态sales-extract-contract-clauses、>1. 文本预处理清洗转写文本合并重复片段标记说话人 2. 分段理解将长文本按话题切分分别做信息抽取 3. 结构化组装将抽取结果按统一schema组装并做去重和校验 4. 任务对接将待办事项逐条转换为项目管理软件的字段并写入系统。最容易出问题的是第三步。模型对待办事项的提取经常漏掉责任人或者给出的截止时间是相对描述比如下周而不是具体日期2025-12-08。我的对策是在抽取阶段就要求模型对每个待办输出action动作描述、owner责任人姓名、due_dateISO8601格式日期、priority高/中/低四个字段凡是责任人缺失的默认标记为待确认并放进需要升级的事项里而不是默默丢弃。第四步的容错也值得说。项目管理工具的写入接口有可能因为权限、字段格式、并发锁等原因失败。我在技能里做了一个简单的半自动对接策略写不进去的事项不会让整个技能崩溃而是返回一个sync_failed列表由人工确认后重新触发。Agent技能不等于全自动灵活地在自动化和人工兜底之间切换才是生产环境里真正耐用的做法。4.3 实测效果与调优方向技能上线后我统计了一个月的使用数据一共处理了46次会议记录自动提取的待办事项共218条人工需要修正的只有9条准确率在95%以上。这比之前纯靠人工整理省了大概四分之三的时间。准确率能到这个水平其实取决于一个很关键的细节——标题级约束。我在技能描述里明确写了输出待办事项时必须使用动词 具体内容 责任人 时间的句式不要使用模糊表达这个约束对模型输出的规范性提升非常明显。后续我还在迭代两个方向一是接入企业内部知识库让纪要里的术语和项目名称能自动映射到标准名称二是对跨团队的会议增加相关方影响字段。技能这个东西就是这样第一版能跑通就成功了一半剩下的靠跟业务方的持续碰撞打磨。5. 落地过程中的坑与对策任何项目做到生产环境问题才开始真正暴露。Agent技能落地也不例外。我总结了自己和团队踩过的三个最深的坑每一个都花了不少时间去趟平。5.1 技能边界模糊引发的套娃式调用第一个坑是技能之间的边界模糊。早期技能库里有一个获取客户信息的技能和一个分析客户画像的技能。听名字好像边界清楚实际使用中问题很大——获取客户信息技能里其实包含了部分统计分析逻辑分析客户画像技能里也调用了部分原始数据查询。一个分析客户流失原因的任务触发了两个技能反复调用对方形成了套娃式调用链延迟翻了3倍还多。排查的时候我画了一下真实的调用关系图才发现两个技能在功能上有大面积重叠。我当时的对策是重构技能边界把获取客户信息强行收敛为只返回原始字段不做任何分析所有统计、建模、画像的逻辑统一收进分析客户画像技能。这一步执行完之后调用链变得清晰干净延迟降了60%。这个坑的本质其实是设计时顺手多做了一点造成的。技能的设计原则应该是单一职责——一个技能只做一件事哪怕这件事特别小。宁可多设计几个做小事的技能由工作流把它们串起来也不要搞万能技能。万能技能往往什么都做不好。5.2 模型能力参差时的降级策略第二个坑是我刚开始没用本地小模型跑Agent时踩到的。不同的底层模型对同一个技能描述的理解能力差异极大。同一个会议纪要结构化归档技能用旗舰模型跑输出规范、字段齐全切到轻量模型可能漏掉一半字段或者把JSON schema都搞变形了。这迫使我在技能设计里引入模型能力分级的概念。具体做法是技能配置中增加一个model_level字段标记该技能的最低可用模型等级。同时每个技能都要提供降级预案——当检测到当前模型能力不足时技能自动走向更保守的执行路径比如简化输出字段只保留最核心的信息从完全自动抽取降级为自动抽取 人工确认从多步骤连续执行降级为分步骤执行每步都让用户确认这套降级策略上线之后最直观的体验是换模型不再导致连带事故。即便底层模型变了技能也能知道自己的能力边界不会硬着头皮硬闯。注意模型能力分级不是一个固定配置它应该随着模型迭代不断更新。我每季度会跑一遍全量技能的自测用例把测试结果跟model_level配置对比发现不匹配就调整。5.3 技能测试不能只靠端到端第三个坑是关于测试的。刚开始我觉得技能测试很简单写几个测试用例跑一遍看输出对不对就行。真正做起来才发现端到端测试的用例是过了就不知道有没有覆盖到挂了也不知道坏在哪里。举个具体的情景。某个技能在一个测试用例中输出了预期结果但这个结果恰恰是模型运气好或者恰好命中了训练数据里的相似案例产生的。同一个技能换一批输入表现立刻暴跌。面对这种随机性端到端测试帮不了你什么。合理的做法是分层测试单元测试技能内部每个步骤单独测试尤其是数据解析、格式转换、异常分支契约测试专门校验技能输出是否符合schema定义字段是否齐全、类型是否正确场景测试模拟真实用户的多轮交互关注技能是否在正确的时机被调用稳定性测试同一组输入反复跑50次观察输出分布是否稳定。这四层跑下来技能的可靠性才能有一个基本认知。我最近还在技能库里加了一个阴影模式新技能上线前先让它在真实流量里旁听但不对用户生效记录它的输出和理想的输出之间的差距连续观察一周稳定了才正式开放。这个做法极大降低了上线翻车的概率。6. 从个人技能库到团队共享复制与沉淀当技能库从我一个人的玩具变成一个团队的生产工具问题就变了不再只是我的技能能不能用而是别人的技能我能不能用我的技能别人能不能维护。这个阶段文档规范和共享机制的重要性开始超过纯粹的编码能力。6.1 技能文档让同事两周后还能看懂很多搞技术的人讨厌写文档但我现在要说一句可能让你反感的话技能代码本身不构成技能文档才是技能真正可复用的前提。理由很简单——技能库是给多个Agent和多个开发者共享的如果没有清晰的文档一个人写的技能别人根本不敢调用。我给团队定的技能文档模板是五个部分用途说明这个技能解决什么问题、输入输出契约JSON Schema和示例、执行流程步骤和依赖关系、已知限制哪些场景下不能用、可能产生什么错误、变更记录版本号和每次改了什么。文档不需要长但必须快——让一个不熟悉这个技能的人读三分钟就能判断这个技能适不适合我用、怎么用。这种文档才是技能从个人经验变为团队资产的关键。6.2 共享技能库的冲突与合并技能库一旦多人维护就一定会遇到并发冲突。两个人同时往库里加了一个都叫parse-invoice的技能实现思路完全不同这是最常见的冲突场景。我的经验是共享技能库必须有明确的评审和合并纪律。技能不是完美的代码写出来就能用它是业务逻辑的高度抽象如果有人随意改动下游的工作流完全无法追踪。我们团队现在实行的是技能委员会机制——每个人可以做技能提案但合入技能库主线前需要过一遍评审输入输出契约是否清晰、测试用例是否充分、跟已有技能是否有重叠、命名是否合规。这看起来增加了流程负担但实际上压低了长期的维护成本。因为技能库的麻烦从来不是加技能而是技能越来越多之后没人知道哪个能信、哪个不能用、哪些已经过时。有评审和版本管理才能让技能库保持可信。6.3 一点关于技能生态的实在体会聊到最后我想说点跟技术不那么相关、但我觉得更重要的话。Agent技能设计的本质不是给模型写代码而是把业务经验系统地沉淀下来。我见过很多技能库设计得漂亮、代码写得优雅但业务方根本不买单——因为技能解决的是技术人员想象中的问题不是真实业务里的痛点。反过来最好的那些技能往往是跟业务方反复碰撞、在一次又一次的这个字段不对这个流程太绕这个输出不够直观反馈中迭代出来的。所以如果你现在正准备搭一个技能库我的建议是先别急着搭框架、写代码。找一两个真实的、让业务方头疼的重复性任务手工拆解清楚定义好输入输出做成两三个能解决实际问题的技能。技能库不需要大需要准。当这几个技能真正被用起来、让业务方觉得离不开的时候你再去考虑规模化和共享协作——那时候你会对什么技能值得沉淀、什么不值得有本能一般的判断力比任何方法论都管用。我在这条路上踩过的坑很多但收获也实打实那些曾经反复翻车的提示词如今变成了一个个稳定的技能模块那个只能聊天的Agent如今真的能独立处理团队里一摊子日常活儿。这套东西给你最大的价值是让你从和大模型讨价还价的泥潭里抽身出来把精力放回真正的业务问题上去。如果有人问我要不要做agent-skills这样的技能体系我的回答是一定要做但要从最小、最痛的那个业务问题开始做。