如果你最近半年在摆弄AI Agent大概率已经遇到过这样一种局面模型的能力明明很强但你反复告诉它同一个操作流程它还是会犯同样的错。我一开始也以为是提示词写得不够细后来发现根本不是提示词的问题而是缺少一层把“流程和经验”结构化的中间层。这个中间层圈子里现在习惯叫它Skill技能。在agent相关项目里提到agent-skills十有八九说的就是这件事如何让Agent拥有真正可复用、可维护、可组合的通用能力。这几个月我在自己维护的Agent工程里完整趟了一遍Skill的设计、实现、调试和落地踩了不少坑也总结出一套还算顺手的打法。这篇东西不打算讲什么玄乎的术语就老老实实拆开讲清楚agent-skills到底是什么、为什么需要它、怎么从零封装一个可用的Skill、不同框架下怎么选型、以及调试过程中那些文档里不会写的血泪问题。适合正在做Agent应用开发、或者准备把原型产品化的朋友参考。1. agent-skills到底是什么Agent工程化绕不开的那层抽象1.1 从一个让人头疼的Agent项目说起先说说我为什么会盯上agent-skills这个概念。之前我在做一个内部知识库问答Agent初期效果其实还行用户问什么模型能翻文档、能总结、能返回答案。但跑了一两个月之后问题就暴露了同样的“把长文档切成可检索片段”这件事模型今天用A方法做明天用B方法做后天干脆自己发明一个C方法结果就是答案质量忽高忽低。你让它“记住”或“沿用上次的方式”它嘴上答应实际操作完全看心情。更麻烦的是研发同学每次想给Agent增加一个新能力比如对接日历、生成周报、汇总邮件都要从头写一遍链路改提示词、加工具函数、调参数、跑回归。代码堆了不少可真正能被复用的东西却很少。这就像一个团队每次接新项目都换一套方法论工作流完全沉淀不下来。后来我意识到问题出在架构缺了一层东西。大模型本身是“聪明但无状态”的执行者工具函数是“能干但不会沟通”的螺丝钉中间的“能力封装层”一直没有做好。而这层东西就是Skill。它不是某一个模型也不是某一个API接口而是一套把“输入、处理、输出、校验、兜底”完整打包的原子能力描述。1.2 什么是Skill给AI的一份“岗位说明书”我在实践中的定义很简单Skill是Agent可以被授权调用的、具有明确输入输出契约的独立能力单元。它本质上是一份“岗位说明书”告诉模型这个能力是干什么的、接收什么参数、返回什么结果、在什么情况下应该调用、在什么情况下不应该调用。举个例子。你给Agent接入一个查天气的工具函数它只是一个API端点但如果你给它封装成一个“天气查询Skill”它就包含了几层信息向用户确认地理位置、拼接API请求、解析天气数据、把“体感温度”翻译成适合人类理解的表述、以及遇到接口超时时的兜底回应。模型不需要自己去思考怎么查天气它只需要根据用户意图调用这个Skill然后拿到一个已经处理好的结果。这种抽象真正解决的是Agent工程里的“靠天吃饭”问题。没有Skill层模型的表现为取决于你当场写的提示词有了Skill层模型的行为被收敛到一系列可预测、可测试、可改进的单元里。这也是agent-skills最近热起来的原因当大家不再满足于Demo而是想把Agent做成稳定交付的产品时这种工程化抽象就变成必需品了。1.3 Skill与普通函数、工具调用的边界在哪有人可能会问这跟写几个普通函数有啥区别区别其实很大。普通函数是给程序员调用Skill是给大模型调用的。两者的“沟通方式”完全不同。普通函数的调用方是代码调用关系是确定的、静态的你写死哪个函数就调用哪个函数。而Skill的调用方是大模型模型要根据用户自然语言来动态决定“要不要调用、调用哪个、传什么参数”。这意味着Skill必须附带足够的语义信息让模型能准确理解还要在参数错误时自己消化掉问题不能动不动就抛异常把任务中断掉。我画过一个很朴素的分层模型帮助自己理解对话层负责听懂用户意图决策层负责选择调用哪些SkillSkill层负责执行具体动作并返回可消费的结构化结果底层工具层负责真正的IO操作。Skill层夹在模型和工具之间看起来只是薄薄一层但它决定了整个系统能不能规模化扩展。没有这层你每加一个新能力都要改大模型的行为逻辑有了这层你只需要新增一个Skill文件剩下的交给运行时去发现和调用。2. Skill的核心设计拆解不是“写个函数”那么简单2.1 Skill的标准结构六个必备组成自己在工程里提炼出来的标准写法一个合格的Skill通常包含六块内容名称与描述、输入Schema、输出Schema、执行器、提示词模板、校验与兜底逻辑。名称与描述是模型看到的第一信息它决定了模型在什么场景下会想到调用这个Skill。描述一定要写“什么时候用”和“什么时候不用”而不仅是“这个工具能干什么”。输入Schema定义了模型需要从对话里抽取哪些参数它越明确模型的“自由发挥”空间就越小。输出Schema则规定了返回的JSON结构让上层能够稳定解析。执行器是实际干活的业务代码提示词模板则用来指导模型如何基于输入完成特定的推理步骤。校验与兜底逻辑是整个Skill可靠性的底座参数缺失、输出错乱、远程服务不可用时怎么处理都得在这里定好。这六块缺了哪一块都会在某个隐蔽的角落出问题。我见过不少项目只写了一个函数和一个描述就上线结果模型在参数理解上频繁出错且问题复现都没有规律非常难排查。2.2 设计Skill的三个核心原则第一个原则是单一职责。一个Skill只做一件事。比如“会议纪要Skill”和“任务分发Skill”不要混合成一个“会议全流程Skill”。理由很简单混合Skill会让输入Schema迅速膨胀模型抽取参数的难度成倍提升同时你也没办法单独调优和替换里面某个环节。宁可让Agent先调用三个Skill也不要让它一个Skill干三件事。第二个原则是显式契约。输入输出都要用Schema定义清楚并且Schema里的description要为模型服务。很多人在Schema里写着“meeting_text会议文本”这对模型几乎没有指导意义更好的写法是“meeting_text用户提供的会议发言或纪要原文通常来自录音转写保留原始句式和缩写”。这种描述能让模型准确抽取参数。第三个原则是设计兜底。任何Skill都要回答一个问题如果没有拿到全部参数怎么办返回错误提示自行生成默认值还是尝试从上下文推断我倾向于让Skill带一个显式的fallback分支因为一个长时间运行的Agent如果动不动就卡死在参数不完整上用户体验会很差。你可以做一个“参数澄清”分支让Agent反问用户补充信息这比默默用错误参数执行要好得多。2.3 粒度控制Skill多大才合适粒度是一个没有标准答案但直接影响成败的设计决策。Skill太粗输入不确定、输出不可控Skill太细Agent在决策时选择成本高调用的链条变长延迟和错误率都会上升。我的判断标准是一个Skill的输入参数最好不超过五六个输出的字段控制在十个左右执行时间尽量在几秒内完成。如果一个任务的实现需要超过100行核心逻辑或者它包含多个可独立失败的子步骤那就应该拆成多个Skill。比如“生成周报”这件事我拆成了三个Skill收集本周事件、按模板生成周报、发送到指定频道。每个Skill独立可测任何一个出问题都能精准定位。粒度选择的背后其实是在平衡模型决策简易度和系统灵活性。对于一个熟练应用场景粗粒度能降低延迟、提升成功率但对于用户需求变化很大的场景细粒度反而让Agent更容易组合出正确的行为。你可以先用粗粒度跑通然后根据模型调用日志逐步拆细而不是一开始就陷入过度设计。3. 动手实现一个可用的Skill从设计到接入的完整过程3.1 这次我们做个什么Skill会议纪要处理理论说多了容易飘我拿一个实际做过的场景来演示会议纪要处理Skill。目标很明确给Agent一段会议转写文本它要输出包含摘要、关键决策、待办事项的结构化JSON。这件事听起来简单但直接让大模型做输出经常格式混乱待办事项的负责人和截止时间经常凭空捏造摘要也经常丢掉关键信息。把它做成Skill之后这些问题都能通过契约与校验集中解决。这个Skill的设计思路是先认定几个关键动作根据会议文本抽取人员与讨论主题区分“决策”和“讨论”对每一项待办提取责任人和截止时间。模型对时间的理解经常错误比如“下周”这种表述所以我会在提示词里要求模型把时间统一转换为ISO 8601日期并且如果原文没有明确日期就输出一个空值而不是猜测。这一步听着简单做出来之后待办事项的可信度提高了一大截。3.2 第一步定义输入输出的JSON Schema我用JSON Schema来定义输入输出边界。输入这里只需要两个字段meeting_text和chunk_size。meeting_text是必填的原始会议文本chunk_size是可选的切片大小默认设为3000字符用来处理超长文本。{ name: process_meeting_notes, description: 当用户提供会议转写文本、并要求整理摘要/待办/决策时使用。当文本内容不是会议记录或没有明确整理要求时不应调用。, input_schema: { type: object, properties: { meeting_text: { type: string, description: 用户输入的会议纪要或转写原文可能含口语、重复、无关对话保留原始内容即可。 }, chunk_size: { type: integer, description: 切片长度默认3000文本超过该长度时自动分片处理。, default: 3000 } }, required: [meeting_text] }, output_schema: { type: object, properties: { summary: { type: string, description: 两到三句话的会议摘要 }, decisions: { type: array, items: { type: string } }, action_items: { type: array, items: { type: object, properties: { owner: { type: string, description: 负责人 }, task: { type: string, description: 待办内容 }, due_date: { type: string, description: ISO8601格式截止日期若原文未明确则为null } }, required: [owner, task, due_date] } } }, required: [summary, decisions, action_items] } }这套Schema写完之后模型对返回结构的理解会稳定很多。但需要注意的是JSON Schema的description字段一定要用模型能理解的语言写不要写程序员视角的说明。比如说due_date你要解释“若原文出现‘下周’‘月底’等相对时间根据当前日期转换为具体日期无法确定时填null”模型才会按这个逻辑去处理而不是随手填一个莫名其妙的日期。3.3 第二步写执行器和提示词模板执行器负责的事很简单接收参数、调用模型、按Schema解析JSON、校验字段、返回结果。为了节省模型的tokens和避免注入危险指令我不会把整个Schema原样塞进提示词而是用一行精简的格式说明。import json import openai class MeetingSkillExecutor: def __init__(self, modelgpt-4o-mini, temperature0.2): self.model model self.temperature temperature self.system_prompt ( 你是会议纪要处理引擎。你只能输出JSON不能输出任何多余文字。\n 输出要求如下\n 1. summary为2-3句话中文摘要。\n 2. decisions是本次明确达成的决策列表不要包含一般性讨论。\n 3. action_items是待办事项owner为负责人task为具体事项due_date为ISO8601日期。\n 4. 如果原文本没有明确截止时间due_date必须填null不要猜测。\n ) def execute(self, meeting_text: str, chunk_size: int 3000) - dict: # 长文本分片分片后逐片处理这里简化只展示单片逻辑 content f以下是会议转写文本\n{meeting_text[:chunk_size]}\n resp openai.chat.completions.create( modelself.model, temperatureself.temperature, response_format{type: json_object}, messages[ {role: system, content: self.system_prompt}, {role: user, content: content}, ], ) raw resp.choices[0].message.content data json.loads(raw) # 校验与兜底字段缺失时补默认值而不是直接报错 return { summary: data.get(summary, ), decisions: data.get(decisions, []), action_items: data.get(action_items, []), }提示词模板里我刻意写了“不要猜测due_date”这是一个让输出可信度大幅提升的关键措辞。模型在回答“不知道的东西”时倾向于编一个貌似合理的值因此需要在提示词层面就把它按住。和参数校验配合这个Skill的失败率会从30%左右降到5%左右。3.4 第三步注册接入Agent到这一步Skill还只是孤立的代码真正让它变成Agent可调用的能力需要注册环节。我用一套YAML清单来管理所有Skill的元信息保存之后由运行时自动加载并注入到Agent的工具列表里。name: process_meeting_notes version: 1.3.0 enabled: true type: llm_skill timeout_seconds: 30 model: gpt-4o-mini temperature: 0.2 executor: skills.meeting_notes.executor description: | 用于处理会议转写文本提取摘要、决策与待办事项。 当用户给出多段会议记录并要求总结整理时使用。 如果用户只是在闲聊、问天气或做其他非会议任务禁止调用。注册完后别忘了做冒烟测试。我会故意用一句很模糊的需求发起调用比如“帮我把今天上午开会说的内容整理一下”然后看模型是否能正确把后面附带的转写文本映射到meeting_text字段。这一步能发现大量描述问题。如果模型把文本传错了字段或者压根不调用Skill那说明description写得还是不够直白。3.5 关键参数怎么调温度、超时与重试参数调优是很容易被忽略但影响很大的环节。对于处理类Skill我常用temperature0.1到0.3温度太高会让同一段文本反复产生不同结果对下游解析和用户体验都是灾难。而创造性任务如写文案温度可以放到0.7以上。所以一个普遍的建议是Skill的类型决定温度不要全局一套参数打天下。超时设置要参考底层API的真实耗时。我用30秒作为默认超时如果模型经常超时先看是不是提示词里塞了太多上下文。重试策略采用带有抖动的指数退避第一次失败等2秒重试第二次4秒最多三次。但重试时需要注意操作是否幂等如果是生成摘要这类只读操作可以放心重试如果是发送邮件这类会留下副作用的操作就绝不能盲目重来否则用户在收件箱里能看到三封一模一样的邮件。4. 工具链与框架选型不同阶段有不同解法4.1 四种落地方式对比Skill这个概念不绑定任何具体产品你可以完全自己写也可以借助现有框架落地。我按“控制力度”和“上手成本”把常见落地方式分成四类列在下面这张表里。落地方式控制力度上手成本适用场景我的评价纯手写代码最强较高深度定制、性能敏感适合沉淀核心能力但需要基本功OpenAI Function Calling中低快速验证简单直接但维护大量函数时容易乱编排框架如LangGraph较高中多Agent、复杂状态流转状态控制好但学习曲线明显可视化平台如Dify/Coze类低更低运营人员和MVP快但复杂逻辑绕手不好做单元测试我的实践路径是MVP阶段用Function Calling快速验证逻辑复杂到需要多步状态流转时迁移到编排框架核心且频繁调用的动作再沉淀为自研Skill包。这样做既不会一开始被框架绑住也不会在规模上来之后被框架限制。选择框架的核心标准是Skill的状态是不是容易管理以及可不可以方便地对单个Skill做回归测试。不能做单测的框架后期会非常痛苦。4.2 Skill与MCP的关系很多读者会问现在大家都在说MCP协议那Skill和MCP是什么关系我的理解是MCP解决的是“模型如何与外部工具通信”的传输标准Skill解决的是“能力如何封装与编排”的工程模型。两者互不冲突甚至经常组合使用一个Skill的执行器内部可以通过MCP客户端去访问各种外部数据源。举个例子我的“周报生成Skill”内部会调一个MCP服务去读取项目管理系统里的任务列表。Skill层负责管理“读取任务、过滤本周事项、生成周报文案”的整体流程MCP层负责规范“读取任务”这个具体工具调用的协议。将通信协议与业务能力解耦后同一个Skill可以平滑切换到不同的数据源和工具实现新同事接入时也不需要理解整套调用细节。4.3 如何评估一个Skill运行得好不好做技术的人容易犯的毛病是只关心“能不能跑通”很少有人真正给Skill建立质量指标。我自己的项目里会盯三类数据调用成功率、参数解析正确率、下游任务完成率。调用成功率指请求没有超时、没有因为参数错误中断的比例参数解析正确率指模型抽取出的参数值与人工标注结果一致的比例下游任务完成率则指最终用户是否拿到满意的结果。这些数据怎么拿最简单的方式是在执行器入口和出口打印结构化日志记录Skill名、版本、输入摘要、模型返回、校验结果、耗时。积累一两周之后你就能看出哪个Skill是“坑王”哪个描述需要优化。哪一类失败占比最高优先修哪一类而不是凭感觉瞎调提示词。把Skill当产品一样做数据复盘是Agent工程化过程中最容易被人忽略、但回报最明显的一件事。5. 调试实录Skill开发过程中踩过的坑与排查方法5.1 问题一Agent对参数“自由发挥”现象我给Skill定义了三个参数模型调用时经常多带一个不在Schema里的参数或者把用户地址里的“明天”理解成了具体日期传进due_date。排查思路这种问题通常出在描述不够清晰。模型不是按Schema做强制类型检查它是“尽力而为”地用自然语言理解去填参数。如果参数含义有歧义它就会猜。我在调试中倾向于给每个参数加“这个字段不包括什么”的说明比如“due_date只填原文中明确出现的日期或明确的相对时间如果没有出现任何时间词必须为null”。这类负向约束让模型的参数抽取正确率瞬间提升。如果加上负向约束还是出错再考虑调整温度或给一个few-shot示例。5.2 问题二多Skill协作时上下文漂移现象Agent先调用会议纪要Skill拿到了结构化输出接着想调用邮件草拟Skill把待办事项写出来结果第二个Skill收到的却是原始会议文本“结构化成果”完全没有被利用。根因很多Agent框架中工具调用的中间结果没有被塞回给模型看或者模型在多轮对话里混淆了输入来源。排查时我先看了调用链路的上下文构造逻辑发现只有最后一次用户消息被保留Skill结果被放在了一个系统变量里模型在后续调用中根本读不到。修复方法是在调用链的每一步之后把“前序Skill的输出摘要”追加为上下文这里要注意不要全量塞回不然长对话的token会很快爆掉只需把关键字段拼成简短文本即可。5.3 问题三调用链路上的超时与重复执行现象一个耗时约40秒的Skill频繁超时导致Agent任务中断。重试机制被触发后执行了两次产生了重复的待办事项推送。分析超时是第一层问题我先把一个长Skill拆成了两个快速检查阶段和重型处理阶段。Agent先调用快速检查Skill判断输入是否满足条件不满足就直接返回说明满足后再调用重型Skill去处理。这能避免大多数无效的超时调用。对于重复执行我给每个调用加了一个幂等键同一个任务ID最多执行一次后续请求直接返回上一次的结果。这个设计在会留下外部副作用的Skill里几乎是必须的。5.4 避坑速查表常见问题核心原因建议解法模型传错参数或多余参数参数描述不明确给Schema加负向约束提供few-shot示例输出JSON格式不稳定提示词约束不足开启JSON模式用校验器解析失败重试一次相同输入在不同时刻结果不同温度太高或提示词不收敛将处理类Skill的温度降到0.2以下长文本截断导致信息丢失未做分片或分片过小按语义段落分片设计跨片合并逻辑多个Skill相互覆盖上下文上下文拼接策略有问题只保留关键结果摘要不塞全量历史超时后重复执行产生脏数据缺乏幂等控制用任务ID做幂等键重试时复用原结果模型对时间表述乱猜提示词未明确处理规则明确要求“无法确定填null”不要猜测我在Skill开发上最大的体会是稳定比聪明重要。大模型天然有“创造力”而Agent系统需要的恰恰是在可控范围内的稳定性。Skill机制的价值不在于让模型一次性能做更多事情而在于给模型提供一组边界清晰、质量受控、可单独迭代的工具。把边界定好模型在边界内的发挥才是真正的加分项。如果你也在维护自己的Agent项目我建议从最小的场景开始搭建你的第一个Skill选一个反复在做、而且结果经常不全一样的任务把它封装起来定义好Schema接上校验与日志。跑一段时间之后你再看那些日志会比任何人给你的建议都更清楚下一步该怎么改。Skill这套打法不复杂但它是让我把Agent从“玩一玩”推向“能交付”的关键一步值得你认真花一个周末把它搭起来。