1. 从skills这个热词说起它到底指什么最近一段时间skills这个词在技术社区里出现的频率突然高了起来。如果你只是偶尔刷到可能会以为是某个新出的前端框架或者云服务产品。但真正跟下来的人会发现它其实是一个更底层、更通用的概念——Agent Skills也就是给智能体Agent用的技能包。我最早接触这个概念是在折腾 Genkit 的时候。当时想给一个对话流程加上查天气和读本地文件两个能力按照传统做法得写两套工具函数、注册到框架里、再处理参数校验和错误返回。后来有人跟我说你试试用 skills 的方式组织把每个能力写成一个独立的技能描述文件框架会自动发现并挂载。试完之后确实省事不少——技能和主流程解耦了加一个能力就是加一个目录删一个能力就是删一个目录不用动核心代码。所以这篇文章想聊的不是某个具体产品的使用教程而是把skills这个东西从概念到落地讲清楚。它适合几类人看一是做 AI 应用开发、想让自己的 Agent 更灵活的工程师二是对 Agent Skills 这个方向好奇、想知道它和传统插件机制有什么区别的技术爱好者三是已经在用相关工具链、但总觉得配置起来磕磕绊绊、想系统梳理一遍的实践者。不管你之前有没有写过 skill读完应该都能对怎么设计一个 skill怎么组织一堆 skill怎么避免踩坑有比较具体的认识。需要先说明一点skills 这个概念目前在不同生态里有不同的实现形态。有的把它做成 Markdown 描述文件加脚本有的把它做成结构化的 JSON 配置还有的把它和 MCPModel Context Protocol这类协议结合起来用。本文不会绑定某一个具体平台而是从通用原理出发结合我实际用过的几种形态来讲。涉及具体命令的地方我会标注清楚是哪个工具链下的写法。2. Agent Skills 的本质给智能体装可插拔的手2.1 为什么不是简单的函数调用很多人第一次听到 skills第一反应是这不就是函数调用吗。表面上看确实像定义一个能力Agent 在需要的时候调用它。但如果你真的写过生产级的 Agent就会知道单纯的函数调用有几个绕不过去的问题。第一个问题是发现。当你有几十个函数的时候Agent 怎么知道该调用哪个传统做法是把所有函数的描述塞进系统提示词里但这样会迅速吃满上下文窗口。skills 的思路是分层先给 Agent 一个技能清单只有名字和一句话描述Agent 判断需要某个技能时再去加载这个技能的完整说明。这就像你手机里的 App 列表——桌面只显示图标和名字点进去才加载完整功能。第二个问题是封装。一个查数据库的技能可能涉及连接管理、SQL 生成、结果格式化、错误重试等一堆逻辑。如果把它写成一个函数这些逻辑要么全塞进去变得臃肿要么散落在各处。skills 允许你把一个技能做成一个目录里面放说明文档、脚本、模板、参考数据Agent 按需读取。这种技能即目录的组织方式让复杂能力有了自然的边界。第三个问题是可组合。真实任务往往需要多个技能配合。比如帮我分析这份销售数据并生成报告可能要用到读表格做统计画图写文档四个技能。如果每个技能都是独立封装的Agent 就能像搭积木一样组合它们。这也是为什么 skills 生态里经常能看到skills 大全skills 推荐这类整理——大家在做的是同一件事积累可复用的能力单元。2.2 一个 skill 的最小结构不同平台的 skill 格式不完全一样但核心要素是相通的。我把它归纳成四个部分组成部分作用是否必需名称与描述让 Agent 知道这个技能叫什么、什么时候用必需触发条件什么情况下应该激活这个技能强烈建议执行逻辑具体怎么做可以是脚本、提示词或两者结合必需输入输出约定参数格式、返回结构、错误处理建议拿一个最简单的例子来说假设你要做一个把 Markdown 转成 PDF的技能。名称可以叫md-to-pdf描述写将 Markdown 文件转换为 PDF 文档支持自定义样式。触发条件写当用户要求导出 PDF 或打印文档时使用。执行逻辑可以是一个调用转换库的脚本。输入输出约定里说明接受文件路径、输出路径、可选样式参数。这里有个容易被忽略的点描述要写给 Agent 看不是写给人看。我见过不少人把描述写成这是一个非常好用的转换工具这种描述对 Agent 判断何时调用毫无帮助。好的描述应该包含做什么和什么时候用两个信息比如将 Markdown 转换为 PDF当用户需要可打印或可分享的文档格式时使用。2.3 和 MCP、传统插件的边界社区里经常有人把 skills 和 MCP 混着说。我的理解是MCP 更像是一个通信协议解决的是Agent 怎么和外部服务对话的问题而 skills 更像是能力组织方式解决的是Agent 有哪些能力、怎么找到并组合它们的问题。两者可以叠加——一个 skill 内部可以通过 MCP 去调用远程服务。至于传统插件区别主要在粒度。插件通常是一个完整的功能模块装上就一直在那儿skill 更轻可以按需加载、按需卸载而且往往以文本形式存在改起来门槛低。这也是为什么skills 开发这件事很多非专业程序员也能参与——你不需要编译打包写个 Markdown 加个脚本就能跑。3. 从零写一个能跑的 skill完整流程拆解3.1 先想清楚这个技能解决什么单点问题我踩过的第一个坑就是贪多。第一次写 skill 的时候我想做一个数据处理技能结果里面塞了读 CSV、清洗、统计、画图、导出五件事。写完之后发现Agent 根本不知道该在什么时候调用它——因为它的触发条件太宽泛了几乎什么任务都能沾边。最后这个技能变成了一个什么都能干但什么都不精的怪物。后来我改成一个技能只做一件事。比如读 CSV 并返回前 N 行预览就是一个技能对数值列做描述性统计是另一个技能。这样每个技能的触发条件都很清晰Agent 判断起来也准。一个 skill 的边界应该能用一句话说清楚什么时候用它如果说不清楚说明该拆了。判断标准很简单如果你给这个技能写触发条件时需要写或者以及来连接多个场景那大概率应该拆成两个技能。3.2 目录结构怎么摆一个典型的 skill 目录大概长这样skills/ md-to-pdf/ SKILL.md # 技能说明Agent 读这个 scripts/ convert.py # 实际执行逻辑 templates/ default.css # 可选资源 examples/ input.md # 示例帮助 Agent 理解用法SKILL.md是核心Agent 通过它来理解这个技能。内容一般包括技能名称、一句话描述、触发条件、使用步骤、参数说明、注意事项。写法上我建议用结构化的 Markdown因为 Agent 解析起来更稳。scripts/放实际干活的代码。这里有个经验脚本要能独立运行。也就是说你不通过 Agent直接在命令行里跑这个脚本它也应该能正常工作。这样做的好处是调试方便——出问题的时候你可以先排除脚本本身的 bug再去查 Agent 调用环节。templates/和examples/是可选的但对复杂技能很有用。模板让输出格式统一示例让 Agent 知道正确用法长什么样。我做过一个生成周报的技能放了三个示例周报进去Agent 生成的质量明显比不放示例时稳定。3.3 SKILL.md 的写法细节这是最影响技能好不好用的部分。我总结了几条实操经验描述用动词开头说清楚动作和对象。比如提取 PDF 中的文本内容比PDF 文本提取工具好因为前者直接告诉 Agent 这个技能能执行什么动作。触发条件要具体到场景。不要写处理文档时使用要写当用户上传 PDF 并要求提取其中文字、或需要对 PDF 内容做检索时使用。越具体误触发的概率越低。参数说明要包含类型和示例。比如参数 - file_path (string, 必需): PDF 文件的绝对路径例如 /data/report.pdf - page_range (string, 可选): 页码范围例如 1-5不填则处理全部加一段常见错误。这个是我觉得最有价值的部分。把你调试时遇到的问题写进去比如如果 PDF 是扫描件本技能无法提取文字需要先做 OCR。Agent 读到这段遇到类似情况就知道该怎么处理而不是硬着头皮返回错误结果。3.4 本地测试与调试写完 skill 之后别急着往生产环境放。先在本地跑通。测试分两层第一层是脚本层测试。直接命令行调用你的脚本喂几个典型输入看输出对不对。这一步能抓出大部分逻辑 bug。第二层是Agent 层测试。把 skill 挂载到你的 Agent 环境里用自然语言提几个需求看 Agent 会不会正确触发、参数传得对不对、结果处理得合不合理。这一步经常能发现描述写得不够清楚的问题——比如 Agent 该调用的时候没调用或者不该调用的时候乱调用。我一般会准备一组测试用例覆盖正常场景、边界场景和错误场景。正常场景验证基本功能边界场景比如空输入、超大输入错误场景比如文件不存在、格式不对。跑完这一轮技能基本就稳了。4. 当技能多起来组织、发现与冲突处理4.1 技能清单的维护策略单打独斗的时候几个技能随便放放就行。但当技能数量上到几十个问题就来了Agent 怎么快速找到需要的那个我的做法是按领域分目录比如skills/data/、skills/doc/、skills/web/然后在每个目录下放一个索引文件列出该领域下所有技能的名称和一句话描述。这样 Agent 在判断阶段只需要读索引不用把所有技能的完整说明都加载进来。等确定了要用哪个再去读对应的SKILL.md。这个分层加载的思路和前面说的手机 App 列表是一个道理。索引文件我建议保持精简每个技能一行格式统一。比如- md-to-pdf: 将 Markdown 转换为 PDF 文档 - csv-preview: 读取 CSV 并返回前 N 行预览 - stat-summary: 对数值列做描述性统计维护索引的时机是新增或删除技能时。我吃过亏——有次删了一个技能但忘了更新索引结果 Agent 一直尝试调用一个不存在的技能报了一堆莫名其妙的错。后来我养成了习惯改技能必改索引两个动作绑在一起做。4.2 命名冲突与优先级技能多了之后命名冲突几乎不可避免。比如你可能有一个search技能是搜本地文件的另一个search是搜网络的。如果都叫searchAgent 就懵了。解决办法有两个一是加前缀比如local-search和web-search二是分命名空间把技能放在不同目录下引用时带上路径。我个人更倾向加前缀因为简单直接Agent 理解起来也不费劲。还有一种情况是功能重叠。比如两个技能都能读文件一个读文本、一个读二进制。这种时候要么合并成一个技能内部判断要么在描述里写清楚各自的适用场景。我一般选择合并因为对 Agent 来说技能越少、判断越简单出错的概率越低。4.3 技能之间的依赖有些技能会依赖另一些技能。比如生成报告可能依赖统计数据和画图。这种依赖关系如果处理不好会出现调用了报告技能但统计数据还没准备好的问题。我的处理方式是在 SKILL.md 里显式声明依赖写清楚使用本技能前请确保已完成 X 和 Y。同时在执行逻辑里做检查如果依赖没满足返回一个明确的提示而不是直接报错。这样 Agent 收到提示后可以先去完成前置步骤再回来调用。对于依赖链比较长的情况我会考虑做一个编排技能把整个流程串起来。但这个要谨慎因为编排技能容易变得臃肿。我的原则是依赖超过三个就考虑编排少于三个让 Agent 自己组合。5. 那些文档里不会写的踩坑记录5.1 路径问题相对路径的陷阱这是我最开始踩的坑而且踩了好几次。skill 脚本里如果用相对路径运行时的工作目录可能和你预期的不一样。比如你写open(data.csv)以为读的是技能目录下的文件结果实际读的是 Agent 启动目录下的文件自然找不到。解决办法是在脚本开头统一处理路径。Python 里可以这样import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) data_path os.path.join(BASE_DIR, data.csv)这样不管从哪里调用路径都是相对技能目录的稳定可靠。其他语言也有类似的写法核心思路就是基于脚本自身位置计算绝对路径。5.2 输出格式不稳定Agent 调用技能后拿到的是脚本的输出。如果输出格式飘忽不定Agent 解析起来就会出问题。我遇到过脚本有时候返回纯文本、有时候返回 JSON、有时候返回带颜色码的字符串结果 Agent 处理得乱七八糟。后来我定了个规矩所有技能的输出都用结构化格式优先 JSON。需要给人看的内容放在某个字段里需要给 Agent 用的结构化数据放在另一些字段里。这样 Agent 永远知道该怎么解析。如果确实需要返回纯文本那也保持格式一致不要这次带标题下次不带。5.3 超时与长任务有些技能执行时间比较长比如处理大文件、调用外部服务。如果不设超时Agent 可能会一直等把整个流程卡住。我的做法是给每个技能设一个合理的超时超时后返回一个明确的任务未完成状态让 Agent 决定是重试还是换方案。对于确实需要长时间运行的技能我会把它改成异步模式技能启动任务后立即返回一个任务 IDAgent 后续用另一个技能去查询进度。这样不会阻塞主流程。这个模式稍微复杂一点但对于耗时操作是必要的。5.4 错误信息要写给 Agent 看脚本报错的时候默认的堆栈信息对 Agent 来说几乎没用。Agent 看到KeyError: name不知道该怎么办。所以我在技能里会做一层错误包装把技术错误翻译成 Agent 能理解的提示。比如try: result process(data) except KeyError as e: return {status: error, message: f输入数据缺少必要字段 {e}请检查数据格式}这样 Agent 收到后知道是输入数据的问题可以尝试修正输入再重试而不是直接放弃。5.5 权限与安全边界技能能执行脚本就意味着它能做很多事情。如果不加限制一个写得不好的技能可能删文件、改配置、发网络请求。我在实际项目里会给技能设边界只允许访问指定目录、只允许调用白名单内的外部服务、危险操作需要二次确认。具体做法因平台而异但思路是一样的最小权限原则。一个读文件的技能就不该有写文件的权限。一个查天气的技能就不该能访问本地文件系统。这些限制在开发阶段可能觉得麻烦但到了生产环境能避免很多问题。6. 技能生态的玩法复用、分享与组合创新6.1 从自己写到拿来用一开始大家都是自己写技能但很快会发现很多技能是通用的——读文件、发请求、格式转换、文本处理这些谁都需要。于是就有了技能分享和复用的需求。社区里那些skills 大全skills 推荐的整理本质上就是在做这件事。我的建议是通用技能优先找现成的领域技能自己写。通用技能别人已经踩过坑了直接用省时间领域技能和你的业务强相关别人写的不一定贴合自己写更靠谱。找现成技能的时候重点看它的描述是否清晰、有没有示例、错误处理是否完善。描述含糊、没有示例的技能用起来往往问题多。6.2 组合出意想不到的效果技能真正的威力在于组合。单个技能可能平平无奇但几个技能串起来能完成相当复杂的任务。我做过一个例子把读网页提取正文翻译生成摘要四个技能组合起来实现了一个输入网址输出中文摘要的流程。每个技能单独看都很简单组合起来就是一个挺实用的功能。组合的关键是技能之间的数据格式要对齐。前一个技能的输出要能直接作为后一个技能的输入。如果格式对不上中间就得加转换步骤流程会变复杂。所以我在设计技能的时候会尽量让输出格式标准化方便被其他技能消费。6.3 版本管理与回滚技能也是代码也需要版本管理。我遇到过改了技能之后原本能跑通的流程突然失败的情况。如果没有版本记录排查起来很痛苦。后来我给技能目录加了简单的版本标记每次修改记录一下改了什么、为什么改。出问题的时候可以快速回滚到上一个版本。对于团队协作的场景技能最好纳入代码仓库统一管理。谁改了什么、什么时候改的一目了然。评审的时候也能发现潜在问题比如某个改动会不会影响依赖它的其他技能。7. 关于 skills 的一些个人体会折腾 skills 这段时间最大的感受是它把给 Agent 加能力这件事的门槛降下来了。以前要加个功能得懂框架、懂注册机制、懂参数校验现在写个 Markdown 加个脚本就行。这让更多人可以参与到 Agent 能力的建设里来不只是专业工程师。另一个感受是技能的 quality 比 quantity 重要得多。我见过有人收集了几百个技能但真正好用的没几个。与其追求数量不如把常用的几个打磨好——描述写清楚、错误处理好、示例给到位。一个精心设计的技能价值超过十个粗糙的。还有个体会是关于边界的。技能不是越多越好也不是越细越好。太粗了 Agent 判断不准太细了组合起来麻烦。找到那个刚好的粒度需要实践和调整。我的经验是从粗开始遇到问题再拆不要一上来就设计得很细。最后说个实际的如果你刚开始接触 skills别想着一步到位做个完美的技能体系。先写一个最简单的技能跑通整个流程感受一下 Agent 是怎么发现和调用它的。有了这个体感之后再逐步扩展。技能体系是长出来的不是设计出来的。
1. 从skills这个热词说起它到底指什么最近一段时间skills这个词在技术社区里出现的频率突然高了起来。如果你只是偶尔刷到可能会以为是某个新出的前端框架或者云服务产品。但真正跟下来的人会发现它其实是一个更底层、更通用的概念——Agent Skills也就是给智能体Agent用的技能包。我最早接触这个概念是在折腾 Genkit 的时候。当时想给一个对话流程加上查天气和读本地文件两个能力按照传统做法得写两套工具函数、注册到框架里、再处理参数校验和错误返回。后来有人跟我说你试试用 skills 的方式组织把每个能力写成一个独立的技能描述文件框架会自动发现并挂载。试完之后确实省事不少——技能和主流程解耦了加一个能力就是加一个目录删一个能力就是删一个目录不用动核心代码。所以这篇文章想聊的不是某个具体产品的使用教程而是把skills这个东西从概念到落地讲清楚。它适合几类人看一是做 AI 应用开发、想让自己的 Agent 更灵活的工程师二是对 Agent Skills 这个方向好奇、想知道它和传统插件机制有什么区别的技术爱好者三是已经在用相关工具链、但总觉得配置起来磕磕绊绊、想系统梳理一遍的实践者。不管你之前有没有写过 skill读完应该都能对怎么设计一个 skill怎么组织一堆 skill怎么避免踩坑有比较具体的认识。需要先说明一点skills 这个概念目前在不同生态里有不同的实现形态。有的把它做成 Markdown 描述文件加脚本有的把它做成结构化的 JSON 配置还有的把它和 MCPModel Context Protocol这类协议结合起来用。本文不会绑定某一个具体平台而是从通用原理出发结合我实际用过的几种形态来讲。涉及具体命令的地方我会标注清楚是哪个工具链下的写法。2. Agent Skills 的本质给智能体装可插拔的手2.1 为什么不是简单的函数调用很多人第一次听到 skills第一反应是这不就是函数调用吗。表面上看确实像定义一个能力Agent 在需要的时候调用它。但如果你真的写过生产级的 Agent就会知道单纯的函数调用有几个绕不过去的问题。第一个问题是发现。当你有几十个函数的时候Agent 怎么知道该调用哪个传统做法是把所有函数的描述塞进系统提示词里但这样会迅速吃满上下文窗口。skills 的思路是分层先给 Agent 一个技能清单只有名字和一句话描述Agent 判断需要某个技能时再去加载这个技能的完整说明。这就像你手机里的 App 列表——桌面只显示图标和名字点进去才加载完整功能。第二个问题是封装。一个查数据库的技能可能涉及连接管理、SQL 生成、结果格式化、错误重试等一堆逻辑。如果把它写成一个函数这些逻辑要么全塞进去变得臃肿要么散落在各处。skills 允许你把一个技能做成一个目录里面放说明文档、脚本、模板、参考数据Agent 按需读取。这种技能即目录的组织方式让复杂能力有了自然的边界。第三个问题是可组合。真实任务往往需要多个技能配合。比如帮我分析这份销售数据并生成报告可能要用到读表格做统计画图写文档四个技能。如果每个技能都是独立封装的Agent 就能像搭积木一样组合它们。这也是为什么 skills 生态里经常能看到skills 大全skills 推荐这类整理——大家在做的是同一件事积累可复用的能力单元。2.2 一个 skill 的最小结构不同平台的 skill 格式不完全一样但核心要素是相通的。我把它归纳成四个部分组成部分作用是否必需名称与描述让 Agent 知道这个技能叫什么、什么时候用必需触发条件什么情况下应该激活这个技能强烈建议执行逻辑具体怎么做可以是脚本、提示词或两者结合必需输入输出约定参数格式、返回结构、错误处理建议拿一个最简单的例子来说假设你要做一个把 Markdown 转成 PDF的技能。名称可以叫md-to-pdf描述写将 Markdown 文件转换为 PDF 文档支持自定义样式。触发条件写当用户要求导出 PDF 或打印文档时使用。执行逻辑可以是一个调用转换库的脚本。输入输出约定里说明接受文件路径、输出路径、可选样式参数。这里有个容易被忽略的点描述要写给 Agent 看不是写给人看。我见过不少人把描述写成这是一个非常好用的转换工具这种描述对 Agent 判断何时调用毫无帮助。好的描述应该包含做什么和什么时候用两个信息比如将 Markdown 转换为 PDF当用户需要可打印或可分享的文档格式时使用。2.3 和 MCP、传统插件的边界社区里经常有人把 skills 和 MCP 混着说。我的理解是MCP 更像是一个通信协议解决的是Agent 怎么和外部服务对话的问题而 skills 更像是能力组织方式解决的是Agent 有哪些能力、怎么找到并组合它们的问题。两者可以叠加——一个 skill 内部可以通过 MCP 去调用远程服务。至于传统插件区别主要在粒度。插件通常是一个完整的功能模块装上就一直在那儿skill 更轻可以按需加载、按需卸载而且往往以文本形式存在改起来门槛低。这也是为什么skills 开发这件事很多非专业程序员也能参与——你不需要编译打包写个 Markdown 加个脚本就能跑。3. 从零写一个能跑的 skill完整流程拆解3.1 先想清楚这个技能解决什么单点问题我踩过的第一个坑就是贪多。第一次写 skill 的时候我想做一个数据处理技能结果里面塞了读 CSV、清洗、统计、画图、导出五件事。写完之后发现Agent 根本不知道该在什么时候调用它——因为它的触发条件太宽泛了几乎什么任务都能沾边。最后这个技能变成了一个什么都能干但什么都不精的怪物。后来我改成一个技能只做一件事。比如读 CSV 并返回前 N 行预览就是一个技能对数值列做描述性统计是另一个技能。这样每个技能的触发条件都很清晰Agent 判断起来也准。一个 skill 的边界应该能用一句话说清楚什么时候用它如果说不清楚说明该拆了。判断标准很简单如果你给这个技能写触发条件时需要写或者以及来连接多个场景那大概率应该拆成两个技能。3.2 目录结构怎么摆一个典型的 skill 目录大概长这样skills/ md-to-pdf/ SKILL.md # 技能说明Agent 读这个 scripts/ convert.py # 实际执行逻辑 templates/ default.css # 可选资源 examples/ input.md # 示例帮助 Agent 理解用法SKILL.md是核心Agent 通过它来理解这个技能。内容一般包括技能名称、一句话描述、触发条件、使用步骤、参数说明、注意事项。写法上我建议用结构化的 Markdown因为 Agent 解析起来更稳。scripts/放实际干活的代码。这里有个经验脚本要能独立运行。也就是说你不通过 Agent直接在命令行里跑这个脚本它也应该能正常工作。这样做的好处是调试方便——出问题的时候你可以先排除脚本本身的 bug再去查 Agent 调用环节。templates/和examples/是可选的但对复杂技能很有用。模板让输出格式统一示例让 Agent 知道正确用法长什么样。我做过一个生成周报的技能放了三个示例周报进去Agent 生成的质量明显比不放示例时稳定。3.3 SKILL.md 的写法细节这是最影响技能好不好用的部分。我总结了几条实操经验描述用动词开头说清楚动作和对象。比如提取 PDF 中的文本内容比PDF 文本提取工具好因为前者直接告诉 Agent 这个技能能执行什么动作。触发条件要具体到场景。不要写处理文档时使用要写当用户上传 PDF 并要求提取其中文字、或需要对 PDF 内容做检索时使用。越具体误触发的概率越低。参数说明要包含类型和示例。比如参数 - file_path (string, 必需): PDF 文件的绝对路径例如 /data/report.pdf - page_range (string, 可选): 页码范围例如 1-5不填则处理全部加一段常见错误。这个是我觉得最有价值的部分。把你调试时遇到的问题写进去比如如果 PDF 是扫描件本技能无法提取文字需要先做 OCR。Agent 读到这段遇到类似情况就知道该怎么处理而不是硬着头皮返回错误结果。3.4 本地测试与调试写完 skill 之后别急着往生产环境放。先在本地跑通。测试分两层第一层是脚本层测试。直接命令行调用你的脚本喂几个典型输入看输出对不对。这一步能抓出大部分逻辑 bug。第二层是Agent 层测试。把 skill 挂载到你的 Agent 环境里用自然语言提几个需求看 Agent 会不会正确触发、参数传得对不对、结果处理得合不合理。这一步经常能发现描述写得不够清楚的问题——比如 Agent 该调用的时候没调用或者不该调用的时候乱调用。我一般会准备一组测试用例覆盖正常场景、边界场景和错误场景。正常场景验证基本功能边界场景比如空输入、超大输入错误场景比如文件不存在、格式不对。跑完这一轮技能基本就稳了。4. 当技能多起来组织、发现与冲突处理4.1 技能清单的维护策略单打独斗的时候几个技能随便放放就行。但当技能数量上到几十个问题就来了Agent 怎么快速找到需要的那个我的做法是按领域分目录比如skills/data/、skills/doc/、skills/web/然后在每个目录下放一个索引文件列出该领域下所有技能的名称和一句话描述。这样 Agent 在判断阶段只需要读索引不用把所有技能的完整说明都加载进来。等确定了要用哪个再去读对应的SKILL.md。这个分层加载的思路和前面说的手机 App 列表是一个道理。索引文件我建议保持精简每个技能一行格式统一。比如- md-to-pdf: 将 Markdown 转换为 PDF 文档 - csv-preview: 读取 CSV 并返回前 N 行预览 - stat-summary: 对数值列做描述性统计维护索引的时机是新增或删除技能时。我吃过亏——有次删了一个技能但忘了更新索引结果 Agent 一直尝试调用一个不存在的技能报了一堆莫名其妙的错。后来我养成了习惯改技能必改索引两个动作绑在一起做。4.2 命名冲突与优先级技能多了之后命名冲突几乎不可避免。比如你可能有一个search技能是搜本地文件的另一个search是搜网络的。如果都叫searchAgent 就懵了。解决办法有两个一是加前缀比如local-search和web-search二是分命名空间把技能放在不同目录下引用时带上路径。我个人更倾向加前缀因为简单直接Agent 理解起来也不费劲。还有一种情况是功能重叠。比如两个技能都能读文件一个读文本、一个读二进制。这种时候要么合并成一个技能内部判断要么在描述里写清楚各自的适用场景。我一般选择合并因为对 Agent 来说技能越少、判断越简单出错的概率越低。4.3 技能之间的依赖有些技能会依赖另一些技能。比如生成报告可能依赖统计数据和画图。这种依赖关系如果处理不好会出现调用了报告技能但统计数据还没准备好的问题。我的处理方式是在 SKILL.md 里显式声明依赖写清楚使用本技能前请确保已完成 X 和 Y。同时在执行逻辑里做检查如果依赖没满足返回一个明确的提示而不是直接报错。这样 Agent 收到提示后可以先去完成前置步骤再回来调用。对于依赖链比较长的情况我会考虑做一个编排技能把整个流程串起来。但这个要谨慎因为编排技能容易变得臃肿。我的原则是依赖超过三个就考虑编排少于三个让 Agent 自己组合。5. 那些文档里不会写的踩坑记录5.1 路径问题相对路径的陷阱这是我最开始踩的坑而且踩了好几次。skill 脚本里如果用相对路径运行时的工作目录可能和你预期的不一样。比如你写open(data.csv)以为读的是技能目录下的文件结果实际读的是 Agent 启动目录下的文件自然找不到。解决办法是在脚本开头统一处理路径。Python 里可以这样import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) data_path os.path.join(BASE_DIR, data.csv)这样不管从哪里调用路径都是相对技能目录的稳定可靠。其他语言也有类似的写法核心思路就是基于脚本自身位置计算绝对路径。5.2 输出格式不稳定Agent 调用技能后拿到的是脚本的输出。如果输出格式飘忽不定Agent 解析起来就会出问题。我遇到过脚本有时候返回纯文本、有时候返回 JSON、有时候返回带颜色码的字符串结果 Agent 处理得乱七八糟。后来我定了个规矩所有技能的输出都用结构化格式优先 JSON。需要给人看的内容放在某个字段里需要给 Agent 用的结构化数据放在另一些字段里。这样 Agent 永远知道该怎么解析。如果确实需要返回纯文本那也保持格式一致不要这次带标题下次不带。5.3 超时与长任务有些技能执行时间比较长比如处理大文件、调用外部服务。如果不设超时Agent 可能会一直等把整个流程卡住。我的做法是给每个技能设一个合理的超时超时后返回一个明确的任务未完成状态让 Agent 决定是重试还是换方案。对于确实需要长时间运行的技能我会把它改成异步模式技能启动任务后立即返回一个任务 IDAgent 后续用另一个技能去查询进度。这样不会阻塞主流程。这个模式稍微复杂一点但对于耗时操作是必要的。5.4 错误信息要写给 Agent 看脚本报错的时候默认的堆栈信息对 Agent 来说几乎没用。Agent 看到KeyError: name不知道该怎么办。所以我在技能里会做一层错误包装把技术错误翻译成 Agent 能理解的提示。比如try: result process(data) except KeyError as e: return {status: error, message: f输入数据缺少必要字段 {e}请检查数据格式}这样 Agent 收到后知道是输入数据的问题可以尝试修正输入再重试而不是直接放弃。5.5 权限与安全边界技能能执行脚本就意味着它能做很多事情。如果不加限制一个写得不好的技能可能删文件、改配置、发网络请求。我在实际项目里会给技能设边界只允许访问指定目录、只允许调用白名单内的外部服务、危险操作需要二次确认。具体做法因平台而异但思路是一样的最小权限原则。一个读文件的技能就不该有写文件的权限。一个查天气的技能就不该能访问本地文件系统。这些限制在开发阶段可能觉得麻烦但到了生产环境能避免很多问题。6. 技能生态的玩法复用、分享与组合创新6.1 从自己写到拿来用一开始大家都是自己写技能但很快会发现很多技能是通用的——读文件、发请求、格式转换、文本处理这些谁都需要。于是就有了技能分享和复用的需求。社区里那些skills 大全skills 推荐的整理本质上就是在做这件事。我的建议是通用技能优先找现成的领域技能自己写。通用技能别人已经踩过坑了直接用省时间领域技能和你的业务强相关别人写的不一定贴合自己写更靠谱。找现成技能的时候重点看它的描述是否清晰、有没有示例、错误处理是否完善。描述含糊、没有示例的技能用起来往往问题多。6.2 组合出意想不到的效果技能真正的威力在于组合。单个技能可能平平无奇但几个技能串起来能完成相当复杂的任务。我做过一个例子把读网页提取正文翻译生成摘要四个技能组合起来实现了一个输入网址输出中文摘要的流程。每个技能单独看都很简单组合起来就是一个挺实用的功能。组合的关键是技能之间的数据格式要对齐。前一个技能的输出要能直接作为后一个技能的输入。如果格式对不上中间就得加转换步骤流程会变复杂。所以我在设计技能的时候会尽量让输出格式标准化方便被其他技能消费。6.3 版本管理与回滚技能也是代码也需要版本管理。我遇到过改了技能之后原本能跑通的流程突然失败的情况。如果没有版本记录排查起来很痛苦。后来我给技能目录加了简单的版本标记每次修改记录一下改了什么、为什么改。出问题的时候可以快速回滚到上一个版本。对于团队协作的场景技能最好纳入代码仓库统一管理。谁改了什么、什么时候改的一目了然。评审的时候也能发现潜在问题比如某个改动会不会影响依赖它的其他技能。7. 关于 skills 的一些个人体会折腾 skills 这段时间最大的感受是它把给 Agent 加能力这件事的门槛降下来了。以前要加个功能得懂框架、懂注册机制、懂参数校验现在写个 Markdown 加个脚本就行。这让更多人可以参与到 Agent 能力的建设里来不只是专业工程师。另一个感受是技能的 quality 比 quantity 重要得多。我见过有人收集了几百个技能但真正好用的没几个。与其追求数量不如把常用的几个打磨好——描述写清楚、错误处理好、示例给到位。一个精心设计的技能价值超过十个粗糙的。还有个体会是关于边界的。技能不是越多越好也不是越细越好。太粗了 Agent 判断不准太细了组合起来麻烦。找到那个刚好的粒度需要实践和调整。我的经验是从粗开始遇到问题再拆不要一上来就设计得很细。最后说个实际的如果你刚开始接触 skills别想着一步到位做个完美的技能体系。先写一个最简单的技能跑通整个流程感受一下 Agent 是怎么发现和调用它的。有了这个体感之后再逐步扩展。技能体系是长出来的不是设计出来的。
