上个月我差点把一个智能体项目砍掉重做。原因很老套同一个任务提示词在A模型上效果好得惊人换到B模型就完全翻车。最开始我以为是模型能力差距后来做了大量对照实验才发现根子在于我把所有逻辑都塞在了一段超长的system prompt里模型根本没有“可复用的操作单元”可以调用。直到我把整套流程重构成agent-skills的写法——把任务拆成一个个带输入输出契约、带错误恢复策略、带明确描述边界的技能单元问题才真正被解决。这篇东西不聊高深框架只把我从拆解到落地这一路的完整方法、实测数据和踩坑过程写出来给正在做智能体应用的人一份可以直接抄作业的参考。1. 从“会聊天”到“会干活”agent-skills要解决的真问题1.1 大多数人把技能写成了长提示词我先说一个最常见也最隐蔽的误区很多人嘴上说在做skill实际干的事只是在prompt里加了一段“你是XX专家请按以下步骤执行”。这种写法不是技能只是更长的指令。真正的区别在于长提示词是一次性消费的文本模型每次都要重新理解一遍而技能是能被识别、选择、调用、复用、测试的独立单元。一个技能应该有名字、有清晰的功能边界、有输入参数定义、有输出格式约束、有失败时的处理方式。它类似于把一坨内联代码抽成有函数签名的公共函数而长提示词更像是脚本里一行行顺序执行的命令改一处就影响全局。我见过一个团队把整个客服流程写成8000字的system prompt里面既有话术规范又有数据库查询规则还有情绪安抚指南。结果就是话术正常的时候大家都觉得不错一旦用户问题偏离预定义轨道模型就开始胡言乱语甚至把查询规则和话术混在一起输出。后来我们把这块拆成了“用户意图识别”“工单信息抽取”“回复话术生成”“问题升级判断”四个技能每一个都单独测试准确率立刻拉开差距。1.2 技能、工具、工作流、模板的边界开始动手前必须先分清几个容易混淆的概念否则后面设计一定会乱。工具tool最原子的外部能力比如调用搜索API、执行一段代码、读取一个文件。它没有复杂的业务判断输入输出非常直接。技能skill在工具之上的一层组合能力。它可以调用工具也可以只依赖模型自身的推理能力但一定包含一个完整的任务闭环。比如“整理会议纪要”这个技能内部可能用到了读取文件工具、文本摘要能力、格式转换工具。工作流workflow固定的、已经编排好的多步流程。它强调顺序和执行路径一般不允许模型自主改道。模板template最容易混淆的。模板是静态的文本框架技能则是带逻辑的、可被模型按需选择的执行单元。agent-skills的核心价值在于它把“模型应该在什么时候做什么事”的决定权交还给模型但把“每件事具体怎么做”的细节固化到技能里。模型不再需要从零理解任务只需要识别当前情境下该调用哪个技能然后按照技能契约去填充参数、接收结果。1.3 适合用agent-skills落地的几类任务不是所有任务都值得技能化。根据我这几个月的实践满足下面至少两个特征的任务才值得投入高频出现每周都会执行多次否则沉淀成技能的成本很难摊薄。验收标准明确任务做完以后能清楚判断好坏而不是“感觉差不多”。步骤相对稳定核心路径变化不大异常情况可以通过参数和分支处理。需要模型自主判断不是固定顺序执行而是要根据输入内容决定怎么走。典型的例子包括文档信息抽取、报告生成、代码审查意见汇总、用户反馈分类、多语言翻译后校对、数据清洗等。反过来那种一次性的一次性创意写作任务或者路径极度依赖开放上下文的任务就不太适合技能化。2. 技能定义的第一步先把任务拆成可复用的“最小交付单元”2.1 如何识别真正值得技能化的任务我在设计技能时踩过最大的坑就是一开始把一个复杂任务整体定义成一个技能结果技能内部状态多到根本没法稳定控制。后来我总结出一个简单标准一个技能应该对应一个“可交付”的产物。所谓可交付就是产出结果能独立被验收、被下游使用。比如“写一篇技术文章”听起来是一个任务但它不是好的技能粒度因为它的验收标准模糊而“根据草稿生成文章大纲”就是一个不错的技能粒度它输出结构化大纲好与不好一眼能判断。判断方法就是三问这个任务的输入是什么能不能列出所有字段这个任务的输出是什么能不能定义成一个稳定的结构比如JSON格式如果模型在这一步失败了重试时会不会对结果产生不可逆影响只要有一个问题答不清楚我就知道这个技能拆得太粗或者太模糊需要继续拆或者收窄边界。2.2 技能边界设计单职责与组合约束技能边界设计的原则是“单职责”。一个技能只做一件事并且要把这件事做透。但这里有个平衡如果拆得太细模型要在一次任务中调用十几个技能上下文开销和出错概率都会上升如果拆得太粗技能就退化成普通prompt。我在实践中常用的做法是“两层粒度”底层原子技能处理文件、搜索、计算等基础操作上层组合技能处理业务闭环比如“搜集资料并生成报告”。上层技能可以调用底层技能但它的接口依然要保持简单。比如我让“资料搜集”技能返回的是一个统一结构的条目列表而不是原始网页内容这样下游“报告生成”技能就不需要关心数据来源的差异。还需要给技能设置“不做清单”。一个技能的描述里必须写清楚它不适合处理什么情况否则模型很容易把它滥用在相邻任务上。比如“文本摘要”技能要写明“不接受代码文件、不做观点生成”这样碰到这类输入时模型会主动选择跳过或者转别的技能。2.3 输入输出契约设计结构化才是硬道理我在早期犯过一个低级错误技能说明里只写了自然语言描述比如“对输入文本进行摘要输出摘要”。看起来没问题但模型经常返回五花八门的结果有的带前缀有的把摘要放在Markdown引用里解析起来很痛苦。后来我把所有技能都改成结构化输入输出核心就是定义清晰的JSON Schema。举个例子一个“合同关键信息抽取”技能的输入输出{ skill_name: contract_info_extractor, description: 从合同文本中抽取关键商务信息包括合同方、金额、期限、违约条款。, input_schema: { type: object, properties: { contract_text: { type: string, description: 合同全文建议不超过2万字 }, extract_fields: { type: array, items: { type: string, enum: [parties, amount, duration, penalty] } } }, required: [contract_text] }, output_schema: { type: object, properties: { parties: { type: array, items: { type: object, properties: { role: {type: string, enum: [甲方, 乙方, 担保方]}, name: {type: string}, id_number: {type: string} } } }, amount: {type: number}, duration_days: {type: integer}, penalty_clause: {type: string} } } }一旦把输入输出变成这种形式技能就有了“机器可读”的边界。模型调用技能时参数就会被约束在schema内输出也能被程序稳定解析。这一步是agent-skills能不能落地的关键分水岭没有结构化契约的技能本质还是提示词不值得投入工程化成本。3. 我实践下来的技能封装格式命名、说明、参数与错误恢复3.1 技能描述怎么写模型才真正“看得懂”技能描述是给模型看的“函数注释”不是给产品经理看的PRD。我最终固定下来的描述模板包含五个部分技能名称、一句话用途、适用条件、限制条件、使用示例。其中最容易翻车的两点是“适用条件”和“限制条件”。适用条件要写清“什么时候该调用我”限制条件要写清“什么情况不要调用我”。模型在选择技能时很大程度上不是靠理解技能内容而是靠对名称和描述的关键词匹配。一个模糊的描述会让模型在错误的时候调用技能或者该调用的时候不调用。我举一个优化前后的例子。优化前技能名称信息提取 描述提取信息。优化后技能名称invoice_info_extractor 描述从发票PDF或扫描件中提取发票号、金额、税额、开票日期等结构化字段。用于财务报销场景。仅处理发票图片或PDF文本不适用于手写单据或非发票文件。后者包含了触发场景、数据来源、处理对象和排除情况模型选择时有了明确上下文误调率明显下降。3.2 参数定义类型、默认值、词汇表参数定义不仅要给类型还要给默认值和枚举词汇表尤其是枚举词汇表能显著降低模型自由发挥的空间。举个例子我在做一个“用户反馈分类”技能时最初把分类标签设计成open string结果模型生成了一百多种不同叫法比如“性能问题”和“运行卡顿”明明是一类却写成两个标签。后来我把classification_tags改成enum固定为“性能、崩溃、易用性、功能缺失、体验建议、其他”要求模型必须从枚举里选无法匹配时选其他并备注原因。这个改动让后续的数据聚合分析容易了不止一个量级。参数定义还有一个容易忽略的细节字段命名要用模型熟悉的术语不要用缩写。比如desp看起来节省token但模型有时会犹豫它到底是description还是despatch直接写用full_name也更容易让模型填正确。另外建议给每个参数都配置一个简短示例。模型在处理少样本或边缘情况时会倾向于模仿示例值。比如参数“sort_order”的默认值写“desc”示例也写“desc”模型返回非法值“descending”的概率就会小很多。3.3 错误处理与重试策略技能不能死在半路这一步是agent-skills和普通prompt最明显的分界线。普通prompt失败了模型可能直接编一个结果继续跑带错误处理契约的技能必须明确告诉模型失败后怎么办。我采用的错误返回格式是这样的{ status: error, error_code: INVALID_INPUT, message: 输入文本为空请检查数据源, retryable: false, suggestion: 请更换数据源后重新调用 }这里最关键的是retryable字段。模型看到retryable为true时可以按suggestion重试看到retryable为false时应该立即停止并上报错误而不是强行编造结果。我见过大量智能体系统出错后一本正经地输出一个看起来合理但完全错误的结果就是因为缺少这种“错误终止”信号。技能实现内部也要做好幂等设计。尤其涉及写文件、发消息等副作用操作时重试不能导致重复执行。我常用的办法是要求技能在参数里支持request_id唯一标识重试时携带相同的request_id服务端就能判断是否已经执行过。4. 工程落地注册中心、加载机制与模型调用链4.1 轻量级技能注册表的设计可能有人觉得技能注册中心要上完整的微服务其实不然。我在项目里一开始只用了一个Python字典就能跑通核心是符合技能描述、处理器函数和参数schema三者能映射上。注册表的每个条目至少包含这些字段id技能唯一标识小写字母加下划线。name展示名称。description供模型选择的说明文本。parametersJSON Schema定义了输入参数。handler实际执行函数。enabled开关可以在不删除代码的情况下下线技能。version技能版本改描述或逻辑时递增。用代码表达就是这样SKILL_REGISTRY {} def register_skill(skill_meta): def decorator(func): SKILL_REGISTRY[skill_meta[id]] { **skill_meta, handler: func, } return func return decorator register_skill({ id: text_summarizer, name: 文本摘要, description: 对长文本进行多层级摘要支持按要点和全文总结两种模式。, parameters: { type: object, properties: { text: {type: string}, mode: {type: string, enum: [key_points, full_summary]} }, required: [text] }, version: 1.0.0, enabled: True }) def summarize(params): ...这种注册方式不需要引入重量级框架所有技能可以用装饰器声明文件结构清晰后续迁移到数据库存储时只需要把注册表的数据源换一下即可。4.2 技能加载与动态注入的两种方案技能描述不能一股脑全塞进prompt里。我尝试过加载30个技能描述光描述就占了近6000个字符模型的选择准确率反而下降了。原因很简单上下文太拥挤模型无法聚焦。我实践下来的方案有两种第一种是“全量注入动态截断”。将所有启用的技能描述压缩成一行摘要放入系统提示中只有模型明确选择某个技能后才追加该技能的完整参数schema。这种方式适合技能数量少于20个的场景。第二种是“按意图预筛候选注入”。先用一个极轻量的“意图识别器”把主任务对应到3-5个候选技能再把候选技能完整描述注入模型。这种方式的成本增加一次模型调用但准确率会明显提升适合技能数量较多或者技能间边界模糊的项目。我现在的项目里采用第二种。实测下来单纯的全量注入在高频场景下的命中率大约82%加入预筛后能到95%左右。多出的一次调用换来几十个百分点的稳定提升非常划算。4.3 上下文体量控制把技能说明压缩成“可消费格式”除了按需注入还要考虑每个技能描述本身的长短。技能描述不是越长越好过长的描述会挤占可用的输出空间。我给技能描述设定的软上限是500字以内参数schema尽量精简到只定义必须字段。如果必须传递很长的指令怎么办我会把详细指令放在skill包里模型通过调用技能时传入的参数间接使用而非把完整指令暴露在上下文中。比如“生成月度报告”技能模型只需要传report_date和data_source两个参数具体的报告模板、格式规范、图表要求全部封装在handler内部。这样上下文干干净净模型也更容易理解自己要做的事。我还养成了一个习惯定期用tokenizer统计所有技能描述的总token数目标是控制在3000 token以内。超过这个值就开始考虑压缩描述或者提高候选技能筛选的门槛。5. 实测记录单技能、多技能协作与效果对比5.1 场景一文档整理技能的实际表现我在一个知识库项目里做了“会议纪要结构化”技能输入是会议录音转写文本输出是会议时间、参会人、决议事项、待办任务列表。总共测试了60份真实会议记录。单技能模式下前20份测试的成功率只有13/20。失败集中在两类一是模型把“讨论内容”和“决议事项”混淆导致输出结构错位二是待办任务缺少负责人模型经常脑补一个名字。这两类问题都不是模型能力不够而是技能描述里没有明确“决议事项必须包含明确动词”和“没有提到负责人时必须标记为待分配”这样的约束。我调整了技能描述和输出schema增加required字段和枚举约束后第二批20份成功率到了18/20。失败的2份都是因为原始会议记录本身信息缺失严重已经不属于技能应该硬处理的范围。最后一轮我又给技能加了“信息完整度评分”输出字段让下游知道结果的可信度整体表现才稳定下来。5.2 场景二两个技能的协作与冲突多技能协作比单技能复杂得多。我测试过一个组合场景“全球信息搜集”技能加上“报告生成”技能。期望路径是模型先调用搜集技能拿数据再调用报告技能写成文。实际跑下来的问题出在参数传递上搜集技能返回的结果结构和报告生成技能输入schema里要求的结构字段对不上模型在两个技能之间来回尝试最终在第四次调用后放弃了。排查后我发现根因是两者的数据结构是独立设计的缺少一层“适配”。我加了一个中间步骤让模型在调用报告技能之前先执行一个“结果转换”技能负责把搜集结果标准化。看似多走了一步但对齐了上下游契约协作链路就通了。这个过程让我意识到多个技能组合时不仅要考虑各自单一职责还要设计好衔接层的协议这个衔接协议本身就是一类技能。5.3 我踩过的坑和完整的排查链路再分享一个让我印象深刻的坑。某个版本我调整了“资料搜集”技能的描述把“关注权威来源”改成了“关注可靠来源”。第二天就收到反馈说模型大量调用“代码审查”技能来处理文档类任务。一开始我还以为是数据集问题后来翻日志才发现技能描述的改动让模型对“来源”这个词产生了新的关联影响了技能选择的权重。那次之后我固定了一套排查流程给同样踩坑的人参考保留每次调用的完整日志至少包含候选技能列表、模型选择的技能、置信度分数。没有日志就无从排查。发现误调后先看最近版本对技能描述做了哪些修改优先怀疑描述变化。用一组固定的回归用例来测试技能描述改动不要只靠零散的线上调用。如果模型在技能失败后编造结果检查技能返回的error_code是否被解析以及error信息有没有被回传给模型。很多时候是程序把错误吞掉了模型以为成功了。把误调用的案例加入技能描述的负面示例里比如“本技能不适用于代码相关任务”。这套链路帮我解决了很多看似玄学的问题。事实证明没有什么玄学只是链路中某个环节的契约断了。6. 如果现在重新做一遍我会调整的三件事6.1 技能元数据比技能正文更值得花时间以前我把大量时间花在打磨技能的内部提示词上比如怎么让摘要更有洞察力、怎么让语气更专业。后来发现这些内部提示词的优化带来的收益远不如把外部元数据设计清楚。我说的元数据包括技能名称、描述、适用场景、负面条件、参数语义、输出示例。因为这些元数据直接决定了模型会不会在正确的时候调用它。如果把技能比作一本书元数据就是书名、目录和推荐语内部提示词是书的正文。书再好读者搜不到、不知道该不该读也是白搭。我现在每写一个技能会先花半天把元数据改到稳定才开始调内部逻辑。6.2 给技能做回归测试技能描述一改模型的行为就可能跟着变。所以技能和普通代码一样需要回归测试。我建了一个很小的技能测试集每个技能准备10条代表性输入和对应的期望输出任何技能改动后都在本地跑一遍确认成功率和输出格式没有退化。这个测试集不需要很复杂只覆盖正常路径和两三个典型的失败路径就够了。但一定要固定下来不能每次临时构造输入。我前面说的那个“可靠来源”引起的误调问题就是靠一套固定用例对比才快速定位的。如果当时没有测试集大概率又要靠玄学排查好几天。6.3 留好人工介入的接口最后一件重新做时会坚持的事是在所有高风险技能执行链路上留一个人工介入接口。比如涉及对外发送消息、删除数据、生成正式合同内容的技能必须在执行前把待执行的“动作”和“原因”返回给系统经过人工确认后才会真正执行。实现方式很简单给技能返回结果增加一个statusneed_review的状态作用是让agent暂停并向用户发送审批请求。这个接口不需要复杂但必须存在。因为技能可以处理大部分确定性工作但边界场景永远存在。与其设计一个复杂的自动决策机制去处理所有特殊情况不如让人在关键节点快速确认。这不仅让系统更安全也能收集到更多边界case反向优化技能描述。技能不是越智能越好而是越稳定越好。我把技能越写越简单把选择权交给模型的决策层把复杂度封装在技能内部这可能是做agent-skills最值得记住的一件事。