我一直在琢磨怎么让AI Agent从“演示玩具”变成真正能稳定干活的工具直到最近反复研究agent-skills这个方向才算是摸到了门道。如果你也在做AI应用开发、自动化流程设计或者单纯好奇为什么别人的Agent能一口气搞定复杂任务而你的Agent只会“一本正经地胡说八道”那这篇文章应该能帮你少走不少弯路。我会从什么是Agent Skills讲起再拆开讲讲怎么设计、怎么写、怎么调试最后分享一些我在实际项目中踩过的坑和总结的经验。1. 先看懂“技能”Agent Skills是什么解决什么问题1.1 从单体Prompt到技能化Agent开发的一次重要转向早期做Agent大家习惯把所有的角色设定、业务规则、工具说明、输出格式全部塞进一个巨大的Prompt里指望模型“凭借聪明才智”完成所有工作。结果用过的人都懂Prompt稍微超过一万字模型的注意力就开始涣散经常把前面的规则忘得一干二净业务逻辑一旦复杂改一处需求整个Prompt就要重写牵一发而动全身。而且这种“单体Prompt”式的写法有个最致命的隐患——模型每次推理都要重新“理解”一遍所有规则既浪费Token又容易产生行为漂移同一个Prompt今天跑得好好的明天升级了模型版本就完全变了个样。agent-skills的核心思路就是把Agent的能力拆散成一个个独立的、可复用的“技能单元”每个技能单元负责一件具体的事比如“查天气”“生成周报”“调用数据库接口”“解析PDF文件”。Agent本身只负责理解用户意图和编排任务真正干活的时候它调用对应的技能来执行。这很像一个公司老板Agent不需要亲自写代码、做财务、跑业务他只需要知道团队里每个人都有什么专长然后把任务分配给对应的人Skills就行。每个技能内部怎么做Agent不关心只要结果符合预期就可以。这种转向之所以重要是因为它把“让模型更聪明”的问题转换成了“让模型更专业”的问题。模型本身的推理能力当然重要但通过技能化我们可以把确定性高、重复性强的操作从模型手里拿出来用传统代码实现保证100%正确而那些需要理解、判断、规划的部分才交给模型发挥。这样的组合方式既发挥了大模型的泛化能力又规避了它“满嘴跑火车”的缺点。1.2 Skills、Plugin、Function Call和Workflow到底有什么区别很多朋友第一次接触这个概念时会懵因为市面上叫法太多了ChatGPT Plugin、OpenAI Function Calling、Coze插件、LangChain Tool、Dify工作流……它们之间到底是什么关系我整理了一张对比表方便你根据自己的场景做选型。概念核心特征适合场景典型代表Agent Skill一段带描述和入参定义的代码/脚本可被Agent按需调用逻辑可轻可重需要复用的单点能力比如抓网页、写文件、算公式Anthropic Claude Skills、各类Agent框架的Skills目录Plugin面向应用的完整扩展包通常包含UI、权限、多个API接口需要深度集成外部平台比如GitHub、SlackChatGPT Plugin、Coze插件Function Calling模型通过结构化输出触发预定义的函数只负责“决定要不要调”短期内一次性的函数调用逻辑通常较简单OpenAI Function Call、各类模型APIWorkflow固定执行流程的图编排节点之间的顺序基本确定稳定不变的业务流程比如自动发邮件、定时报表Dify Workflow、n8n、Coze工作流从这张表能看出来Skill和Function Calling最像但定位完全不同。Function Calling更像是一个“接口规范”它本身不包含实现逻辑模型只负责输出一段JSON告诉系统“我决定调用函数A参数是B”真正的函数逻辑要你自己写、自己挂载。而Skill可以理解成“接口规范实现代码说明文档”的打包体它不仅告诉模型“我有什么功能”还自带执行逻辑。换句话说Function Calling是一个空的插座Skill则是一个即插即用的家电。1.3 为什么Skills是Agent落地的关键拼图我见过太多团队做Agent Demo时激动不已一到生产环境就砸锅的场景。最典型的原因就是模型在“理解意图”上表现优秀在“精确执行”上却非常拉胯。让它算个数据它能给你算错让它读个Excel它能给你凭空编出几行不存在的记录。而Skills真正厉害的地方就是把这些“需要精确性”的操作从模型的嘴变成了程序的代码。模型只需要回答“该用哪个技能、参数是什么”剩下的交给技能本身执行结果就是确定的、可复现的、可测试的。另外Skills大大降低了Agent系统的维护成本。以前改一个业务逻辑你可能要在Prompt里翻半天改完还要担心影响其他部分。现在技能都是独立的改“生成周报”的技能绝不会影响到“发送邮件”的技能。而且Skills天然适合团队协作——每个人负责维护几个技能模块接口约定好了就行大家各干各的最后拼装起来就是一个完整的Agent系统。这种模块化思路在传统软件开发里被验证了几十年现在终于被带进了Agent领域。2. 设计一个优质Agent Skill核心细节与评判标准2.1 技能描述Agent眼里的“说明书”怎么写才能让模型正确触发我见过很多新手写的技能描述不是太啰嗦就是太空泛。技能描述的作用是让Agent在“决定调用哪个技能”的时候能一眼认出来“这个技能适合当前任务”。因为模型本质上是靠语义匹配来做决策的描述写得好不好直接决定了技能会不会被正确触发。合理的描述应该包含以下要素技能名称用动词开头的短名比如 fetch_web_content、generate_report、query_database让模型能快速理解功能。功能路径一句话说明这个技能在什么场景下使用例如“当用户需要获取某个URL页面正文时使用”。适用条件明确什么情况下应该调用什么情况下不应该调用越精确越好。关键参数说明在描述里简单交代必填参数避免模型漏填或者乱填。但注意描述不要写成“让Agent理解一切”的说明书要抓住核心场景写得越精准模型的选择就越准。我常用的方法是“场景-动作-对象”三段式例如“当用户需要场景时使用此技能动作获取/生成/处理对象。”这样的描述语义清晰匹配成功率极高。还有个容易被忽略的点就是负向提示。也就是在描述里告诉Agent“什么情况下不要用”比如“本技能只处理本地文件不处理网络请求”。别小看这一句很多时候模型就是因为缺少这层约束把一个本该调用A技能的任务召唤到了B技能头上。2.2 技能入参与出参把边界划清楚Agent才不会捣乱技能定义里入参和出参是最需要认真设计的。入参设计不好模型要么给不出你想要的参数要么会给出一堆无用的参数。我总结了几条特别实用的设计原则入参设计原则参数越少越好能设计3个参数就不要设计5个。参数越多模型填错的概率就越大。参数类型要明确字符串、整数、布尔值、数组类型定义要清楚模型是严格按照JSON Schema来生成参数的定义越精确出错越少。必填和选填要分清必填参数千万不要设置默认值否则模型会认为可以不填选填参数要给出合理的默认值减少模型负担。参数描述要具体比如date参数的描述不应该只是“日期”而应该是“要生成报表的日期格式为YYYY-MM-DD如2025-06-01”这样模型才知道如何组织输出。出参设计原则出参是技能的“交付物”是Agent用于后续决策和反馈给用户的核心依据。出参建议统一用JSON格式因为结构化数据方便Agent读取和加工。同时无论执行是否成功都应该返回一个包含status字段的对象比如{status: success, data: {...}}或者{status: error, message: 具体错误原因}。这样Agent才能根据状态决定如何回复用户而不是对着一个空消息瞎编。2.3 从需求拆到代码一个“周报生成”技能的完整设计纸上谈兵容易我拿一个真实场景来完整演示。假设我们要做一个“周报生成”技能用户只需要说一句“帮我生成这周的周报”Agent就能自动统计工作内容、汇总成果、生成结构化周报文本。这个需求看起来简单拆解下来其实很复杂。先从需求拆起一周的工作数据从哪里来可能是IM聊天记录、项目管理工具的工时记录、或者用户自己提交的工作日志。我们假设数据来源是一个已存在的数据库里面记录了用户每天的工作内容、耗时和完成状态。那么“周报生成”技能的基本职责就是从数据库里取出本周的数据按日期整理成列表再汇总各项成果最后渲染成标准的周报Markdown文本。入参设计上最核心的参数就是时间范围可以用start_date和end_date两个字符串参数并明确格式为YYYY-MM-DD。为了让Agent用起来更友好还可以加一个可选的focus_areas参数让用户指定本周重点想突出的方向比如“接口开发”“故障排查”等。出参就是两个字段summary一段总体概述details一个包含日期、内容、耗时、状态的数组。此外如果数据库查询失败返回status: error并附带错误信息。这个设计看起来很简单但实际操作中我发现很多人的技能问题都出在没有把“Agent需要什么”和“用户需要什么”分开。用户的原始需求是“帮我生成周报”而Agent执行时需要的却是“从数据库查数据、按格式渲染”。如果你在设计技能时只想着“完成用户需求”而不去想“Agent每一步需要什么信息”那做出来的技能一定是残缺的。3. 落地实战从零构建一套Agent Skills目录3.1 目录结构怎么组织先约定再开发真正落地一套技能库先不要急着写代码第一步是把目录结构约定好。没有统一约定后续技能一多管理起来就是灾难。我习惯的项目结构长这样skills/ ├── README.md # 技能库总说明写清楚每一个技能的作用和调用方式 ├── generate_weekly_report/ # 每个技能一个独立文件夹 │ ├── SKILL.md # 技能说明文件描述、入参、出参、注意事项 │ ├── main.py # 技能的核心实现代码 │ └── requirements.txt # 技能依赖的第三方库如果有 ├── fetch_web_content/ │ ├── SKILL.md │ ├── main.py │ └── requirements.txt └── query_sales_data/ ├── SKILL.md ├── main.py └── requirements.txt为什么每个技能单独一个文件夹因为每个技能都应该可以被独立开发、独立测试、独立部署。这样团队协作时一个人负责一个技能互不干扰。SKILL.md 是整个技能目录的灵魂我习惯把它写得像“招投标文件”一样严谨——明确定义技能名称、说明、参数、返回值、错误码任何开发者拿到这个文件不需要追问就知道这个技能该怎么调。技能的命名也有讲究我推荐用小写下划线、动词开头的风格比如fetch_web_content、parse_pdf。这样做的好处是当Agent的技能数量达到几十个甚至上百个时模型依然能通过语义快速匹配到正确的那个像get、set这类过于宽泛的词应该尽量避免。3.2 技能文件怎么写以Python技能为例以fetch_web_content这个技能为例它的职责是获取某个网页的正文内容并提取关键信息。SKILL.md 可以这么写--- name: fetch_web_content description: 当用户需要获取某个URL页面正文内容、提取文章关键信息、或者分析网页结构时使用此技能。当用户只需要纯文本而不需要网页结构时也使用此技能。 input: - name: url type: string description: 需要抓取的目标网页URL必须是完整的http或https链接。 required: true - name: max_length type: integer description: 返回正文的最大字符数默认3000最大10000。 required: false output: - name: title type: string description: 网页标题 - name: content type: string description: 网页正文纯文本内容 - name: status type: string description: success或error - name: message type: string description: 当status为error时给出错误原因主逻辑main.py可以用 requests BeautifulSoup 实现但要注意几个在生产环境里必须处理的细节设置合理的超时时间防止网页无响应导致Agent长时间卡住做好异常捕获返回的错误信息要能让Agent“读得懂”而不是只有开发者才看得懂的堆栈信息。3.3 挂载与加载给Agent装上技能并验证调用效果写好了技能文件和实现代码怎么把它“装”到Agent上不同框架的挂载方式不同。以Claude Agent Skills为例只需要把技能文件夹放到Agent配置中指定的skills目录下Agent启动时就会自动扫描并加载所有技能。使用OpenAI API的话你需要在请求中把每个技能转换成一个function定义并把实现代码挂载到函数调度器上。挂载之后一定要做一次系统的验证。我通常先测试“无Agent情况下的技能本身”——直接调用main.py传入假参数确认功能正常。然后再测试“有Agent的情况”——让Agent按自然语言触发技能观察它能不能正确理解意图、是否能提取出合法的参数值、是否能在技能返回结果后合理组织语言回复用户。很多人会忽略一个细节技能返回值本身并不会直接展示给用户Agent拿到返回值之后还要在回复里做一层“翻译”。所以你设计的出参不仅要符合机器逻辑还要方便Agent理解后转述。比如返回里带一个summary字段Agent就能直接拿它生成给用户看的回答这个设计能让整个链路的稳定性大幅提升。4. 常见问题与排查技巧实录4.1 Agent“看不见”技能或者总是找错技能这类问题我排查的优先级是先确认技能目录或配置有没有被正确加载再检查技能描述与真实功能是否匹配。我遇到过一个很典型的翻车案例一个技能原本是“查询库存数据”的但我在描述里写成了“查询商品信息”结果Agent每次都在用户问“这个商品还有货吗”的时候调用它返回的数据却跟库存完全无关。后来我在描述里加了负向提示“本技能不处理商品基本信息查询如需商品名称、分类等信息请使用商品查询技能”问题立刻解决了。当你发现Agent频繁找错技能时别急着怪模型智商不够先审视你的技能描述是否足够“精确且唯一”。4.2 技能输入输出不符合预期Agent“胡编”参数这可能是最让人头大的一类问题因为Agent传入的参数往往“看起来合理但其实不合规”。比如你要求日期格式是YYYY-MM-DD但它传了2025/06/01你要求整数它传了字符串。遇到这种情况我强烈不建议在技能内部做大量的兼容处理因为你会发现模型总能变着花样给你“惊喜”今天少个斜杠明天多个空格永远不会穷尽。正确的做法是在入参校验阶段就严格把关参数格式不对直接返回错误并把“正确格式示例”写进错误信息里。我实测过只要错误信息足够清晰比如“date参数格式应为YYYY-MM-DD示例2025-06-01你提供的是2025/06/01”模型下一次就会立刻修正。这本质上是在用错误信息“教育”模型比在代码里做海量兼容要高效得多。4.3 多技能协作时的冲突与优先级当技能数量多了另一个常见问题是多个技能之间的边界模糊导致Agent不知道选哪个。比如你有fetch_web_content和parse_pdf两个技能用户说“把这个网页的内容存成PDF”Agent到底应该调哪个可能先调fetch_web_content拿内容再调一个create_pdf技能生成文件也可能只调一个就能搞定。解决这个问题的思路是把“路由决策”的复杂度留在描述层尽量让每个技能的边界清晰。如果是多个技能有先后依赖关系更推荐的做法是在技能描述里给出“配合使用”的提示例如“本技能返回结果后可配合create_pdf技能用于生成PDF文件”。这样Agent就能学会在合适的环节调用合适的技能。4.4 建立一套定位问题的通用方法论调试Agent技能如果只靠“出了一次错修一次”效率太低很难积累起可复用的经验。我现在的做法是先抓Agent的完整调用链日志逐步确认“意图理解”“技能选择”“参数生成”“技能执行”“回复生成”五个环节看问题到底出在哪一环。我很喜欢把Agent的中间推理过程打出来再配合每次技能调用的入参和出参记录做复盘。有一次我的Agent连续报错排查了很久才发现问题不在技能本身而是上一轮的回复生成阶段Agent把技能返回的JSON截断了导致后续流程解析失败。这个问题就是靠完整链路日志定位出来的。我还整理了一个“问题快速定位表”每次调试都会先过一遍这张表能节省大量时间现象可能原因排查手段Agent完全不用某技能技能描述不清晰或名称不直观检查技能描述是否覆盖目标场景有无冲突描述Agent用错技能技能边界模糊、描述重叠增加负向提示缩小每个技能的适用场景参数总是传错参数描述不清楚、类型定义模糊简化参数、补充格式示例、严格入参校验技能执行报错代码异常、网络问题、依赖缺失测试技能本身绕过Agent直接调用技能入口返回值与用户问题不匹配出参设计不合理确保出参包含可直接用于回答用户的结构化字段说到底agent-skills这套思路并不神秘它真正改变的是我们与Agent协作的方式。过去我们期待模型能“理解一切”现在我们把模型当成一个聪明的“调度员”把确定性的执行交给技能。这个思路一旦打通你会发现Agent的开发效率、稳定性、可维护性都会上一个台阶。我在自己的项目中把常用能力逐步技能化之后最大的感受是终于不用再为模型某次“灵光一现”的发挥而提心吊胆了因为重要的事都有技能代码兜底。如果你正在开发Agent我的建议是别急着堆Prompt先把那些反复用的能力抽成独立的技能你会回来感谢这个决定的。
 替代 assertSame() + count())
