1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看这里说的 skills 显然不是人类的能力而是给 AI agent 使用的一套可插拔能力包。你可以把它理解成给一个刚入职的实习生配的“操作手册 工具箱”手册告诉它遇到什么场景该做什么工具箱给它现成的脚本、模板、命令去执行。我最早接触这个概念是在折腾 Claude 的 agent 能力时。当时我手上有一堆重复性的活儿比如批量整理 Markdown 文档、自动生成项目脚手架、跑一遍前端构建再截图对比。每次都要手动写一长串提示词还得反复纠正 agent 的输出格式。后来发现有人把这类固定流程封装成了一个个 skillagent 在需要的时候自己去调用不用我每次重复交代。这个体验上的差别就像你每次做饭都要从头切菜备料和厨房里已经摆好了半成品料理包——后者不一定更高级但确实省事。所以这篇内容我想聊的是skills 这套机制到底是什么、它解决了什么问题、怎么从零开始做一个能用的 skill、以及在实际使用中会踩哪些坑。适合两类人看一类是已经在用 AI agent 做开发或自动化、想进一步提升效率的人另一类是听说过 Agent Skills 但还没搞明白它和普通提示词、和 MCP server 有什么区别的人。我会尽量把原理讲透同时给出可以直接抄的操作步骤。需要先说明一点skills 目前并没有一个完全统一的行业标准不同平台Claude、Codex、以及各类 agent 框架对它的实现细节有差异。我下面讲的内容是基于常见的 agent skills 实践模式来展开的具体到某个平台时我会标注出来。你如果用的是别的框架思路是通的细节需要对照官方文档调整。2. skills 的核心设计思路为什么不是简单的提示词2.1 提示词、MCP server、skill 三者的分工要理解 skills 的价值得先把它和另外两个容易混淆的东西区分开提示词prompt和MCP server。提示词是你直接告诉 agent “做什么、怎么做”的一段文字。它的优点是灵活缺点是每次都要重复而且当流程变长时提示词会变得又臭又长agent 容易在中途跑偏。我试过用一段 800 字的提示词让 agent 完成“读取 CSV → 清洗数据 → 生成图表 → 导出报告”这个流程结果它在第三步就开始自由发挥图表格式每次都不一样。MCP server 则是给 agent 提供外部工具能力的协议层。比如你想让 agent 能查数据库、能调用某个 API、能操作文件系统这些能力通过 MCP server 暴露给 agent。它解决的是“agent 能不能做某件事”的问题但不解决“这件事该按什么流程做”的问题。skill 的位置在两者之间。它更像一个封装好的任务单元里面包含了完成某个特定任务所需的指令、脚本、模板、参考资料。agent 遇到匹配的场景时加载这个 skill按照里面定义的流程去执行。它既不是单纯的提示词也不是底层工具而是“提示词 工具调用 执行逻辑”的组合包。维度提示词MCP serverskill解决的问题告诉 agent 做什么给 agent 提供工具能力封装完整任务流程复用性低每次重写高一次配置多次调用高按需加载复杂度低中高中典型场景一次性任务数据库、API、文件操作固定流程的重复任务维护成本随提示词变长而升高需要维护服务需要维护 skill 内容这个分工带来的直接好处是agent 的上下文不会被无关信息占满。以前我把所有流程都塞进系统提示词里agent 每次启动都要读一遍浪费 token 还容易混淆。现在把不同任务拆成不同 skillagent 只在需要时加载对应的那个上下文干净很多。2.2 skill 的目录结构与加载机制一个标准的 skill 通常是一个文件夹里面至少包含一个描述文件常见的是SKILL.md或skill.yaml以及可选的脚本、模板、参考文档。描述文件里会写明这个 skill 叫什么、什么时候该用、具体步骤是什么。我拿一个实际做过的例子来说明。之前我经常需要把一堆散落的 Markdown 笔记合并成一份结构化文档流程固定但琐碎。我把它做成了一个 skill目录结构大概是这样markdown-merger/ ├── SKILL.md ├── scripts/ │ └── merge.py └── templates/ └── output-template.mdSKILL.md里写清楚了三件事触发条件当用户要求合并多个 Markdown 文件时使用、执行步骤读取文件列表 → 按标题层级排序 → 去重 → 套用模板输出、注意事项保留原始文件的代码块格式不要自动转换。scripts/merge.py是实际干活的脚本agent 在需要时调用它。templates/里放输出格式的参考。agent 的加载机制通常是这样的启动时只读取所有 skill 的元信息名称和简短描述不加载完整内容。当用户的请求匹配到某个 skill 的描述时agent 才把完整的SKILL.md读进上下文然后按里面的步骤执行。这个“按需加载”的设计很关键它让 agent 可以挂载几十个 skill 而不至于上下文爆炸。注意不同平台对 skill 的发现和加载方式不一样。有的平台要求 skill 放在特定目录下有的支持通过 npx 命令安装有的需要手动注册。你在动手之前先确认自己用的 agent 支持哪种方式。2.3 为什么这个设计对 AI agent 特别重要AI agent 和普通聊天机器人的核心区别在于它要执行多步骤任务。多步骤任务最容易出的问题不是某一步做不对而是步骤之间的衔接和状态管理。人类做多步骤任务时会用清单、笔记、文件夹来管理agent 也需要类似的东西。skill 本质上就是给 agent 提供了一套“外部化的流程记忆”。它把“先做什么、再做什么、遇到什么情况怎么处理”这些逻辑从模型的隐式知识里抽出来变成显式的、可检查的、可修改的文件。这样做的好处有三个第一可调试。当 agent 执行出错时你可以直接看 skill 文件里哪一步写得不清楚改掉就行不用去猜模型为什么跑偏。我之前有个 skill 总是漏掉最后一步的格式校验后来发现是SKILL.md里那一步写得太笼统改成“检查输出中是否包含 YAML front matter如果没有则补上”之后就稳定了。第二可版本控制。skill 是文件可以放进 Git 管理。团队里谁改了哪个流程一目了然。这比把流程藏在某个人的提示词收藏夹里靠谱得多。第三可组合。一个 skill 可以调用另一个 skill或者引用另一个 skill 的输出。这让复杂流程可以拆成小块每块单独维护。比如我有一个“生成周报”的 skill它内部会调用“读取任务列表”和“格式化 Markdown 表格”两个子 skill。3. 动手做一个 skill从需求到落地3.1 先想清楚什么任务值得做成 skill不是所有任务都值得封装成 skill。我的判断标准是三条重复频率高、流程相对固定、有明确的输入输出。三条都满足才值得花时间做。举个例子。“帮我写一封邮件”这种任务虽然重复但每次的内容差异太大流程也不固定做成 skill 反而限制发挥。“把 CSV 转成 Markdown 表格”这种任务重复频率高、流程固定、输入输出明确就非常适合。再比如热搜词里提到的“codex 写论文的 skills”这背后对应的任务可能是“根据大纲生成论文章节草稿”或者“检查参考文献格式”。前者流程不够固定后者就很适合做成 skill——格式检查有明确的规则输入是一段文本输出是问题列表。我自己的经验是先手动做三遍再决定要不要封装。如果三遍下来流程基本一致只是参数不同那就值得做。如果每遍都要临时调整思路说明这个任务还没稳定到可以封装的阶段。3.2 写一份合格的 SKILL.mdSKILL.md是整个 skill 的核心。它写得好不好直接决定 agent 能不能正确使用这个 skill。我踩过的坑是一开始写得太简略agent 经常误解触发条件在不该用的时候用了或者该用的时候没反应。一份合格的SKILL.md通常包含这几个部分名称和描述。名称要短且唯一描述要写清楚“这个 skill 做什么”和“什么时候该用”。描述里最好包含一些关键词方便 agent 做匹配。比如name: csv-to-markdown-table description: 将 CSV 文件转换为 Markdown 表格。当用户提供 CSV 文件并要求转换为表格格式、或要求整理数据为可读表格时使用。触发条件。明确写出什么情况下应该加载这个 skill。写得越具体误触发的概率越低。我一般会写“当用户明确提到 X 或要求 Y 时使用”而不是“当用户需要处理数据时使用”——后者太宽泛。执行步骤。这是最关键的部分。步骤要写成可执行的指令而不是模糊的描述。对比一下模糊写法“处理 CSV 文件并生成表格”可执行写法“1. 读取用户指定的 CSV 文件路径2. 解析表头确认列数3. 对每列数据去除首尾空格4. 按 Markdown 表格语法生成输出表头与数据行之间用|---|分隔5. 如果某列包含|字符将其转义为\|”后者 agent 基本能一次做对前者就要靠运气。注意事项。把容易出错的边界情况写在这里。比如“如果 CSV 文件超过 1000 行先询问用户是否需要分页输出”“如果某列全部为空保留该列但标注为空”。示例。给一个输入输出的例子agent 看了之后对期望结果的理解会准确很多。这个投入产出比很高我建议每个 skill 都加。3.3 脚本和模板什么时候需要怎么组织不是所有 skill 都需要脚本。如果任务纯粹是文本处理SKILL.md里的指令就够了。但如果任务涉及文件操作、数据计算、调用外部命令就需要写脚本。我判断的标准是如果某一步用自然语言描述起来很啰嗦但用代码几行就能搞定那就写脚本。比如“计算两个日期之间的工作日天数”用自然语言描述要考虑周末、节假日、起始日是否包含写代码就是一个函数的事。脚本放在scripts/目录下在SKILL.md里注明调用方式。我一般会写清楚脚本的入参和出参格式以及失败时的返回码含义。这样 agent 调用脚本失败时能根据返回码判断是重试还是报错。模板放在templates/目录下用于输出格式固定的场景。比如生成报告、生成配置文件、生成项目脚手架。模板里可以用占位符标记需要替换的部分在SKILL.md里说明替换规则。提示脚本尽量用标准库少依赖第三方包。因为 agent 运行环境不一定装了你本地的那堆依赖。如果必须用第三方包在SKILL.md里写明安装命令并说明如果安装失败该怎么降级处理。3.4 测试你的 skill怎么判断它真的能用写完 skill 只是第一步测试才是重头戏。我的测试流程分三轮第一轮正常路径测试。用最典型的输入跑一遍看输出是否符合预期。这一轮主要检查流程是否走通。第二轮边界测试。用空文件、超大文件、格式不规范的文件各跑一遍看 agent 会不会卡住或者输出乱七八糟的东西。我遇到过 agent 在遇到空 CSV 时直接崩溃的情况后来在SKILL.md里加了“如果文件为空输出提示信息并结束”才解决。第三轮干扰测试。在对话中混入其他任务看 agent 会不会错误地触发这个 skill。比如我先让 agent 做别的事然后突然提到“表格”这个词看它会不会误加载 CSV 转换 skill。这一轮能暴露触发条件写得不够精确的问题。测试通过之后我建议把 skill 放进版本控制并在SKILL.md顶部加一个版本号和更新日志。这样以后修改时能追溯。4. 实际使用中的常见问题与排查4.1 skill 不触发或误触发怎么办这是最常见的问题。agent 要么该用 skill 的时候不用要么不该用的时候乱用。原因通常出在description和触发条件上。如果不触发先检查描述里有没有包含用户可能用到的关键词。比如用户说“把这个表格整理一下”而你的描述里只写了“CSV 转换”那 agent 可能匹配不上。解决办法是在描述里补充同义词和常见表达。如果误触发说明触发条件太宽泛。比如你写了“当用户提到数据时使用”那 agent 看到任何跟数据沾边的请求都会加载。解决办法是把条件收窄写成“当用户提供 CSV 文件并明确要求转换为 Markdown 表格时使用”。还有一个容易被忽略的点skill 之间的优先级。如果你装了多个功能相近的 skillagent 可能不知道该选哪个。这时候需要在描述里写清楚各自的适用边界或者在系统层面设置优先级。4.2 脚本执行失败的排查思路脚本失败的原因五花八门我整理了一个排查顺序基本能覆盖大部分情况现象可能原因排查方法命令找不到脚本没有执行权限检查文件权限必要时chmod x依赖缺失运行环境没装对应包在脚本里加依赖检查或改用标准库路径错误相对路径基准不对统一用绝对路径或在脚本里打印当前目录编码问题文件编码不是 UTF-8在脚本里显式指定编码超时处理数据量过大加分页或流式处理设置超时上限输出格式不对脚本逻辑与预期不符单独跑脚本对比输入输出我踩过最坑的一次是脚本在本地跑得好好的放到 agent 环境里就报“文件不存在”。查了半天发现是 agent 的工作目录和我本地不一样脚本里用了相对路径。后来改成用环境变量传绝对路径就稳了。注意agent 调用脚本时通常不会给你交互式的终端。所以脚本里不要写需要用户输入的部分所有参数通过命令行参数或环境变量传入。4.3 上下文被占满导致 skill 加载失败如果你的 agent 同时挂了很多 skill或者当前对话已经很长可能会出现 skill 加载失败的情况。这是因为 agent 的上下文窗口有限元信息加上对话历史已经占满了没有空间再加载完整的SKILL.md。解决办法有几个一是精简 skill 的元信息描述控制在两句话以内二是把长对话拆成多个会话三是把不常用的 skill 暂时移除。我自己的习惯是常用 skill 保持在 5 个以内其他的按需临时挂载。另外SKILL.md本身也不要写得太长。我见过有人把整个项目的文档都塞进去结果加载一次就吃掉大半上下文。正确的做法是SKILL.md只写流程和关键注意事项详细的参考资料放到单独的文件里agent 需要时再去读。4.4 跨平台使用 skill 的兼容性问题不同 agent 平台对 skill 的支持程度不一样。有的平台原生支持 skill 目录结构有的需要你手动把SKILL.md的内容粘贴到系统提示词里有的通过 npx 命令安装。热搜词里提到的“claude 国内安装 skills 官方市场”“skills 下载平台有哪些”反映的就是大家在找统一的安装渠道。我的建议是把 skill 写成平台无关的格式。核心逻辑放在SKILL.md和脚本里平台相关的配置单独抽出来。这样换平台时只需要改配置层不用重写整个 skill。具体做法是在SKILL.md里用占位符标记平台相关的部分比如{{PLATFORM_SKILL_DIR}}然后在不同平台用不同的值替换。5. 进阶玩法让 skills 组合出更大的价值5.1 skill 之间的调用与编排单个 skill 能解决的问题有限真正有意思的是把多个 skill 串起来。比如我有一个“生成项目周报”的 skill它内部会依次调用“读取任务管理工具数据”“计算本周完成任务数”“生成 Markdown 报告”三个子 skill。每个子 skill 单独维护主 skill 只负责编排。这种编排方式的好处是子 skill 可以被其他主 skill 复用。比如“生成 Markdown 报告”这个子 skill既可以用在周报里也可以用在月报、项目总结里。改一处所有用到的地方都生效。实现编排的关键是定义清楚子 skill 的输入输出契约。主 skill 调用子 skill 时传什么参数、期望什么格式的返回都要写明白。我一般会在SKILL.md里用一个简单的表格列出每个子 skill 的接口。5.2 根据场景动态选择 skill有些任务有多种处理方式需要根据输入特征动态选择。比如“处理图片”这个任务如果图片是截图走 OCR 流程如果是照片走压缩和裁剪流程。这时候可以写一个“调度 skill”根据输入类型决定调用哪个子 skill。调度 skill 的SKILL.md里主要写判断逻辑。判断条件要写得可执行比如“如果文件扩展名是 .png 且尺寸小于 500x500判定为截图”。不要写“如果看起来像截图”agent 没法执行这种判断。5.3 把 skill 分享给团队使用skill 做多了之后自然会有分享的需求。团队共用一套 skill能保证流程一致减少重复劳动。分享时要注意几点一是统一目录结构。大家约定好 skill 放在哪个目录、命名规范是什么避免混乱。我们团队用的是skills/skill-name/SKILL.md这个结构。二是写清楚依赖。每个 skill 需要什么环境、什么包、什么权限在SKILL.md里列出来。新同事拿到 skill 后照着装一遍就能用。三是建立更新机制。skill 是会迭代的谁改了、改了什么、为什么改要有记录。我们用 Git 管理每次修改提 PRreview 通过后合并。四是提供测试用例。每个 skill 配一个test/目录里面放几个典型输入和期望输出。新人改完 skill 后跑一遍测试确认没破坏原有功能。5.4 从 skills 到个人知识库的沉淀用久了之后我发现skills 其实不只是给 agent 用的它也是个人和团队知识沉淀的好载体。以前很多操作经验散落在聊天记录、笔记、脑子里做成 skill 之后就变成了结构化的、可检索的、可执行的文档。我现在会把一些常用的操作流程都做成 skill哪怕 agent 不一定会用到。因为写SKILL.md的过程本身就是一次梳理逼着自己把模糊的经验变成清晰的步骤。这个过程里经常能发现以前没注意到的细节和坑。而且 skill 是可以被搜索的。当我想回忆“上次那个数据清洗是怎么做的”时直接搜 skill 目录比翻聊天记录快得多。从这个角度看skills 既是给 AI 的能力包也是给人看的操作手册。6. 我踩过的几个坑和对应的解法第一个坑是过度封装。刚开始做 skill 时我恨不得把每个操作都封装成一个 skill结果 skill 数量爆炸agent 反而不知道该用哪个。后来我给自己定了个规矩只有每周至少用三次的任务才做成 skill其他的先手动做。第二个坑是描述写得太抽象。我写过一个“处理文档”的 skill描述是“当用户需要处理文档时使用”。结果 agent 在任何跟文档沾边的场景都加载它包括只是问一个文档相关的问题。后来改成“当用户提供具体文档文件并要求格式转换或内容提取时使用”误触发就少了很多。第三个坑是脚本没有错误处理。早期写的脚本假设输入永远正确结果遇到格式不对的文件就直接抛异常agent 拿到一堆报错信息也不知道怎么办。后来我在每个脚本里都加了输入校验和友好的错误提示agent 看到提示后能自己决定是重试还是询问用户。第四个坑是忘记更新 skill。流程改了但 skill 文件没同步更新导致 agent 按旧流程执行输出不对。现在我养成了习惯每次手动做完一个任务如果发现流程和 skill 里写的不一样立刻去改 skill。第五个坑是把敏感信息写进 skill。有一次我在脚本里硬编码了一个 API key差点提交到仓库。后来改成从环境变量读取并且在SKILL.md里注明需要配置哪些环境变量。这个坑提醒我skill 文件也是代码要用对待代码的态度对待它。7. 关于 skills 的一些个人体会折腾了这段时间我最大的感受是skills 的价值不在于它有多智能而在于它把“怎么做”这件事从模型的黑盒里拿出来变成了白盒。以前 agent 做错了我只能反复调提示词像在跟一个看不见的人猜谜。现在我可以直接看 skill 文件哪一步不清楚就改哪一步改完立刻见效。另一个感受是skills 让 AI agent 的使用从“一次性对话”变成了“可积累的工程”。每次踩的坑、每次优化的流程都能沉淀成文件下次直接复用。这种积累感是单纯用聊天机器人时没有的。如果你刚开始接触 skills我的建议是从一个最小的任务开始不要一上来就搞复杂的编排。先做一个“读取文件并输出行数”的 skill跑通整个流程理解加载机制和调用方式再逐步增加复杂度。这个过程里你会遇到各种小问题但每解决一个对 agent 的理解就深一层。最后分享一个我常用的小技巧在SKILL.md的末尾加一个“变更记录”小节每次修改都记一笔。看起来不起眼但当 skill 多起来之后这个记录能帮你快速回忆起某个改动的原因。我现在的习惯是改完 skill 顺手写一行变更记录花不了十秒钟但省下了以后很多困惑。