1. 从“skills”这个热词说起它到底是什么为什么突然火了最近半年不管是在开发者社区还是各种技术群里“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到skills、claude code、codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词几乎绑在一起出现。很多人第一次看到“skills”会以为是某种新框架或者新语言其实不是。它更像是一种能力封装机制——把一段可复用的指令、工具调用逻辑、上下文约束打包成一个独立单元让 AI 代理agent在需要的时候直接加载使用。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让它在项目里自动完成一些重复性工作比如按团队规范生成组件、跑测试、整理变更日志。一开始我把所有要求都塞进一个巨大的系统提示里结果就是提示词越写越长模型开始“忘事”改一个地方影响另一个地方维护成本极高。后来我把这些要求拆成一个个独立的 skill每个 skill 只负责一件事需要哪个加载哪个整个流程立刻清爽了。这就是 skills 的核心价值模块化、可组合、按需加载。那它解决了什么问题简单说三个痛点。第一上下文污染。一个 agent 如果同时背着几十条规则它的注意力会被稀释输出质量下降。skills 让你只在当前任务需要时才注入相关能力。第二复用困难。以前你写好的一套提示词换个项目就得复制粘贴再改现在打包成 skill 可以直接迁移。第三协作混乱。团队里每个人对 AI 的用法不一样skills 提供了一种标准化的“能力接口”大家可以共享、版本管理、按需组合。适合谁来参考我觉得三类人最该看。一是日常用 Claude Code、Codex 这类工具干活的开发者你不需要懂底层实现但得知道怎么找 skill、装 skill、写 skill。二是团队里负责搭建 AI 工作流的人你需要理解 skills 的组织方式和加载逻辑才能设计出可维护的流程。三是对 agent 架构感兴趣的技术爱好者skills 是理解“代理能力扩展”这件事最直观的入口。下面我会从设计思路、核心细节、实操过程到问题排查把我踩过的坑和总结的方法完整讲一遍。2. 内容整体设计与思路拆解为什么是“技能”而不是“插件”或“提示词”2.1 skills 与 plugin、agent 的关系到底怎么理解很多人会把 skills 和 plugin 混为一谈其实两者定位不同。我用一个生活化的类比agent 是一个人plugin 是他手里的工具比如螺丝刀、计算器skill 是他脑子里的操作流程比如“怎么拧螺丝”“怎么算折扣”。工具是外部能力技能是内部知识。你给一个人一把螺丝刀plugin他未必知道怎么用你教他一套拧螺丝的流程skill他拿到任何螺丝刀都能干活。在 Claude Code 和 Codex 的语境里这个区分更明显。plugin 通常指对宿主环境的扩展比如给编辑器加个面板、给 CLI 加个子命令。而 skill 是一段结构化的指令集合它告诉 agent“遇到这类任务时按这个步骤、用这些工具、遵守这些约束来做”。热搜词里出现的claude agent skills: a first principles deep dive和codex skills其实都在讨论同一件事如何把领域知识封装成 agent 可加载的能力单元。那为什么不用纯提示词因为纯提示词没有结构。一个 skill 通常包含几个固定部分名称、触发条件、执行步骤、可用工具、输出格式、边界约束。这种结构让 agent 在加载时能快速定位“这个 skill 是干什么的、什么时候用、怎么用”。而一堆散落的提示词模型需要自己猜哪条适用效率低且容易出错。2.2 方案选型背后的考量为什么我最终选择“按需加载”而不是“全量注入”我试过三种方案这里直接给对比。方案做法优点缺点适用场景全量注入把所有规则写进系统提示实现简单一次配置上下文膨胀规则互相干扰维护困难规则极少且稳定的场景固定分组按任务类型分成几组提示词手动切换比全量好一些切换靠人容易忘组内仍会膨胀任务类型固定的个人使用按需加载 skills每个能力独立成 skillagent 根据任务自动或手动加载上下文干净复用性强可版本管理需要设计触发逻辑初期搭建成本高多任务、多项目、团队协作我最终选按需加载核心原因是上下文窗口是稀缺资源。你塞进去的每一条无关规则都在消耗模型的注意力。实测下来当一个系统提示超过一定长度后模型对后面内容的遵循度会明显下降。skills 的按需加载让每次任务只带相关能力输出稳定性提升非常明显。另一个考量是可测试性。一个 skill 独立之后你可以单独测它给它一个输入看输出是否符合预期。而混在一起的提示词你改一处整个行为都可能变回归测试几乎没法做。热搜词里有个agent skills测试说明已经有人在做这件事了这是很自然的需求。2.3 一个 skill 的典型结构长什么样虽然不同平台的具体格式有差异但核心字段大同小异。我按通用结构拆一下name唯一标识最好用动宾短语比如generate-component、run-migration。description一句话说明这个 skill 干什么agent 靠它判断是否加载。trigger触发条件可以是关键词、文件类型、命令前缀等。steps执行步骤按顺序列出每步说明用什么工具、输入什么、期望输出什么。constraints边界约束比如“不要修改测试文件”“必须使用项目已有的工具函数”。output输出格式要求比如 JSON schema、Markdown 模板。这个结构的好处是人机都能读。人看一遍就知道这个 skill 的职责边界agent 加载后也能按步骤执行。我建议你在写第一个 skill 时就把这几个字段填满哪怕有些暂时用不上留着占位也比后面补要省事。3. 核心细节解析与实操要点从找 skill 到写 skill 的关键环节3.1 怎么找到靠谱的 skill官方市场、社区仓库与自建热搜词里有find skills、skills推荐、claude 国内安装skills 官方市场说明“找 skill”是很多人的第一道坎。我按可靠性从高到低排一下来源。第一优先级是官方或半官方市场。Claude Code 和 Codex 都有自己的 skill 分发渠道里面的 skill 经过基本审核格式规范兼容性好。安装方式通常是命令行一条指令或者把 skill 目录放到指定路径。这里要注意版本匹配不同版本的宿主工具对 skill 格式的支持可能有差异装之前先看 skill 的兼容说明。第二优先级是社区仓库。GitHub 上有很多人分享自己写的 skill 集合质量参差不齐。我筛选的标准是看 star 数、看最近更新时间、看有没有测试用例、看 README 写得是否清楚。一个连 README 都懒得写的 skill大概率作者自己都没怎么用过。热搜词里前任skills官方下载这种明显是误匹配不用理会。第三优先级是自建。当你发现现有 skill 都不完全符合需求时就该自己写了。自建的好处是完全贴合你的工作流坏处是要花时间调试。我的建议是先从改别人的 skill 开始改着改着就知道怎么写自己的了。提示不管从哪找 skill装之前先读一遍它的 steps 和 constraints。有些 skill 会执行文件写入或命令调用不看清楚就装可能把你项目搞乱。3.2 写一个 skill 的核心步骤我总结的五步法写 skill 这件事说难不难说简单也不简单。我按自己写了几十个 skill 的经验总结成五步。第一步明确单一职责。一个 skill 只做一件事。如果你发现描述里出现了“并且”“同时”“顺便”那说明该拆了。比如“生成组件并且跑测试并且更新文档”这是三个 skill不是一个。第二步写清楚触发条件。触发条件决定了 agent 什么时候加载这个 skill。写得太宽会频繁误触发写得太窄该用的时候用不上。我的经验是用具体的文件路径、命令前缀、关键词组合来限定。比如“当用户提到 .vue 文件且要求新建时触发”就比“当用户要求新建文件时触发”精确得多。第三步把步骤拆到可执行粒度。每一步都要说明用什么工具、输入是什么、输出是什么、失败怎么办。不要写“处理数据”这种模糊描述要写“读取 src/data 下的 JSON 文件用项目已有的 parseData 函数解析输出标准化对象”。粒度越细agent 执行越稳定。第四步加约束和边界。这是最容易被忽略但最重要的一步。约束包括不能改哪些文件、必须用哪些已有函数、输出必须符合什么格式、遇到不确定情况时是询问还是跳过。我踩过的坑是没写约束agent 自作主张重构了我的工具函数导致其他模块报错。从那以后我每个 skill 都加一条“不要修改 utils 目录下的任何文件”。第五步写测试用例。至少准备三个输入正常情况、边界情况、异常情况。跑一遍看输出是否符合预期。热搜词里agent skills测试说的就是这个环节。测试通过后再发布或共享能省掉后面很多麻烦。3.3 参数与配置几个容易搞错的地方skill 的配置里有一些参数容易让人困惑我挑几个高频的讲。加载优先级。当多个 skill 的触发条件重叠时谁先加载一般平台会按优先级字段排序没写的按加载顺序。我的做法是给核心 skill 设高优先级辅助性的设低优先级避免辅助 skill 抢了主流程的注意力。上下文预算。每个 skill 加载后都会占用上下文。如果一个任务需要加载很多 skill总占用可能超限。我的经验是单个 skill 的指令部分控制在 500 字以内超过就考虑拆分或精简。实测下来精简后的 skill 执行效果反而更好因为模型能抓住重点。工具权限。有些 skill 需要调用文件写入、命令执行等敏感操作。配置时要明确声明需要哪些权限不要一股脑全开。最小权限原则在这里同样适用只给完成这个 skill 所必需的权限。版本锁定。如果你在团队里共享 skill建议锁定版本。skill 更新后行为可能变化锁定版本能保证大家用的是同一套逻辑。热搜词里codex无法加载组织设置这类问题有时候就是版本不一致导致的。4. 实操过程与核心环节实现从零搭一个可用的 skill 工作流4.1 环境准备Claude Code 与 Codex 的安装要点热搜词里claude code安装、codex安装、codex安装教程、claude code windows、ubuntu配置claude code出现频率很高说明安装是很多人的第一道门槛。我按自己的安装经验讲几个关键点。Claude Code 的安装。主流方式是通过包管理器或官方安装脚本。Windows 用户注意如果你在 WSL 里用路径和权限跟纯 Linux 环境有差异skill 目录的位置要确认清楚。Ubuntu 用户相对省事按官方文档走基本没问题。安装完成后先跑一个最简单的命令验证环境比如让它读一个文件、输出一句话确认基础功能正常再往下走。Codex 的安装。Codex 的安装包和安装教程网上很多但要注意版本。热搜词里codex官网下载、codex下载、codex安装 csdn说明大家找安装包的需求很旺。我的建议是优先从官方渠道获取第三方来源的安装包有被篡改的风险。安装后同样先做基础验证。编辑器集成。热搜词里vscode配置claude code、claude code for vs code、idea使用skills、idea设置plugin中插件仓库地址都是关于编辑器集成的。我的经验是先在命令行里把工具跑通再配编辑器插件。因为编辑器插件出问题时你很难判断是工具本身的问题还是插件的问题。命令行跑通了插件只是多一层壳排查起来简单得多。注意安装过程中如果遇到网络相关的报错先检查本地环境配置不要盲目改配置。很多问题其实是路径、权限或版本不匹配导致的。4.2 搭建第一个 skill一个完整的实操记录我拿一个真实场景来演示自动生成符合团队规范的 React 组件。这个场景足够具体又能体现 skill 的核心价值。第一步建目录。在项目的 skills 目录下新建一个文件夹命名generate-component。里面放一个主文件按平台要求的格式写。第二步写描述和触发条件。描述写“根据给定名称和类型生成符合团队规范的 React 组件文件”。触发条件写“当用户要求新建 React 组件且指定了组件名称时”。第三步写步骤。我列了五步读取templates/component.template模板文件。用用户提供的组件名称替换模板中的占位符。根据组件类型函数组件/类组件选择对应的代码结构。在src/components下创建同名文件夹和index.tsx文件。更新src/components/index.ts的导出列表。第四步加约束。我加了三条不要修改模板文件本身不要覆盖已存在的组件文件如果存在则提示用户生成的代码必须通过项目的 ESLint 检查。第五步测试。我准备了三个用例正常新建一个函数组件、新建一个已存在的组件名、新建一个类组件。跑下来前两个符合预期第三个发现模板里类组件的结构没写全补上后通过。这个 skill 写完后我每天新建组件的时间从几分钟降到几秒而且再也不会忘记更新导出列表。这就是 skill 的价值把容易忘、容易错的重复流程固化下来。4.3 组合多个 skill让 agent 处理复杂任务单个 skill 解决单点问题组合起来才能处理复杂任务。我举一个实际例子提交代码前的检查流程。这个流程涉及多个步骤我拆成了三个 skill。lint-check跑 ESLint 和 TypeScript 类型检查。test-run跑相关测试用例。changelog-update根据 git diff 更新变更日志。然后在主流程里按顺序加载这三个 skill。agent 收到“准备提交”的指令后依次执行先 lint通过后跑测试测试通过后更新日志最后输出一份检查报告。如果中间任何一步失败就停下来报告问题不继续往下走。这种组合方式的好处是每个 skill 可以独立维护和测试。lint 规则变了只改lint-check测试框架换了只改test-run互不影响。热搜词里superpower skills和skills开发讨论的其实就是这种组合能力。4.4 本地模型接入Claude Code 调用本地模型的注意事项热搜词里claude code 调用lmstudio的本地模型和codex接入deepseek说明很多人想把 skill 工作流接到本地或第三方模型上。我试过这条路讲几个关键点。接口兼容性。不同模型对接口格式的支持程度不一样。有些模型对工具调用的支持不完整skill 里的工具步骤可能执行不了。接入前先确认模型是否支持你 skill 里用到的所有能力。上下文长度。本地模型的上下文窗口通常比云端小。如果你的 skill 组合起来占用上下文较多本地模型可能装不下。解决办法是精简 skill或者减少单次加载的数量。响应稳定性。本地模型的输出稳定性跟硬件、量化程度有关。同样的 skill在不同配置下表现可能差异很大。建议先在简单任务上验证再逐步上复杂流程。提示接入本地模型时先把 skill 的约束写得更严格一些。本地模型对模糊指令的遵循度通常不如云端模型明确的边界能减少跑偏。5. 常见问题与排查技巧实录我踩过的坑和解决方法5.1 skill 不触发或误触发怎么办这是最高频的问题。表现是该用 skill 的时候 agent 没加载不该用的时候反而加载了。排查思路如下。先看触发条件是否太宽或太窄。太宽就加限定词比如加上文件类型、目录路径、命令前缀。太窄就放宽一点或者增加同义词。我一般会看 agent 的日志确认它收到任务后判断加载了哪些 skill再对照触发条件找原因。再看优先级是否冲突。如果两个 skill 触发条件重叠优先级高的会先加载可能把另一个挤掉。解决办法是明确区分两者的适用场景或者合并成一个 skill。最后看描述是否清晰。agent 靠描述判断是否加载。如果描述写得含糊比如“处理文件相关操作”agent 很难判断该不该用。改成“当用户要求批量重命名 src 下的图片文件时触发”就明确多了。5.2 skill 执行到一半失败怎么排查执行失败的原因通常分三类工具调用失败、输入不符合预期、约束冲突。我整理了一个速查表。现象可能原因排查方法解决方式工具调用报错权限不足或工具不存在检查 skill 声明的权限和实际环境补权限或换工具输入解析失败上游输出格式变了看上游步骤的实际输出加格式校验或容错约束冲突两条约束互相矛盾逐条检查 constraints删掉或改写冲突项中途停止无报错上下文超限看加载的 skill 总长度精简或拆分 skill输出格式不对输出要求不明确对照 output 字段补充示例或 schema我遇到最多的是输入解析失败。上游 skill 的输出格式稍微变了一点下游就崩了。后来我养成了一个习惯每个 skill 的输入输出都加校验不符合就明确报错而不是让 agent 猜。这样问题定位快很多。5.3 团队协作中 skill 管理的经验团队里用 skill最大的问题是版本混乱。张三改了一个 skill李四不知道用的时候行为对不上。我的做法是三条。第一skill 进版本控制。跟代码一样skill 也放 Git 里管理。每次修改走 PR有人 review。这样谁改了什么、为什么改都有记录。第二写变更说明。每个 skill 的修改都要写清楚改了什么、影响范围是什么。特别是改了触发条件或约束的一定要标注因为这两类改动最容易影响使用者。第三定期清理。用不上的 skill 及时删掉或归档。我见过一个团队积累了上百个 skill一半没人用新人进来根本不知道从哪看起。定期清理能保持 skill 库的可维护性。5.4 几个容易被忽略的细节skill 命名要一致。用统一的命名风格比如全用 kebab-case全用动宾结构。这样找起来快也不容易重名。描述里不要写实现细节。描述是给 agent 判断用的写清楚“做什么”就行“怎么做”放在 steps 里。描述太长反而影响判断。约束要具体可验证。“不要写烂代码”这种约束没法验证等于没写。“函数不超过 50 行”“必须用项目已有的 request 函数”这种才能验证。定期回顾 skill 的使用频率。如果一个 skill 半年没被触发过要么是触发条件有问题要么是需求变了。该修就修该删就删。6. 关于 skills 后续可以怎么扩展我现在的工作流里skill 已经成了基础设施的一部分。除了前面讲的代码生成和提交流程我还在几个方向上做了扩展这里分享出来供参考。一个是把 skill 和项目文档打通。比如写一个 skill在生成代码的同时自动从项目文档里拉取相关的接口说明和字段定义保证生成的代码跟文档一致。这样文档更新后代码生成也跟着更新减少不一致。另一个是给 skill 加反馈回路。每次 skill 执行完记录执行结果和耗时。积累一段时间后能看出哪些 skill 经常失败、哪些步骤最耗时据此优化。这个思路跟热搜词里agent skills测试是相通的只是从单次测试变成了持续监控。还有一个方向是跨项目复用。我把通用的 skill 抽出来放在一个共享目录项目特有的 skill 放在项目目录。加载时先找项目目录找不到再找共享目录。这样通用能力不用每个项目复制一遍维护成本低很多。最后分享一个小技巧写 skill 的时候先别急着写完整先写一个最小可用的版本跑通一个最简单的用例然后再逐步加步骤和约束。我一开始总想一次写完美结果调试起来特别痛苦。后来改成小步迭代每个 skill 从十行开始跑通了再加效率高很多也不容易出错。