1. 从“skills”这个词说起它到底在解决什么问题如果你最近在折腾 Claude Code、Codex 或者各类 agents 工具大概率会频繁撞见一个词——skills。它不是一个新框架也不是某个具体产品而是一套让 AI 编程助手“长出手艺”的机制。简单说skills 就是给 agent 预先封装好的能力包一段提示词、一组脚本、一套工作流打包成一个可被调用的单元。你让它写 React 组件它知道你的目录约定你让它跑数据库迁移它知道你的命名规范。没有 skills 的 agent 像个聪明但没上过岗的实习生有 skills 的 agent 才像个熟悉你项目的老手。我最初接触这个概念是在 Claude Code 里当时官方市场里已经有一批现成的 skills 可以直接装。后来 Codex 也跟进了类似的能力社区里开始出现“skills 推荐”“好用的 skills”“skills 开发”这类讨论。热词里还混着不少安装报错、插件仓库配置、本地模型接入的问题说明大家已经从“这是什么”进入到“怎么装、怎么用、怎么自己写”的阶段了。这篇内容就是把我这段时间在 Claude Code、Codex 以及 VS Code、IDEA 这些环境里折腾 skills 的经验整理出来从概念到实操从安装到自研尽量让刚上手的人也能跟着走一遍。适合谁看如果你已经在用 Claude Code 或 Codex但还停留在“聊天式提问”那 skills 能让你的效率上一个台阶如果你正在做 agent 相关的开发想理解 skills 的设计思路这里也有从第一性原理出发的拆解如果你只是被各种安装报错卡住第四部分的问题排查表可以直接拿去对照。我不打算写成官方文档的复述而是按一个实际使用者的视角把踩过的坑和验证过的路径讲清楚。2. skills 的核心设计思路为什么是“技能包”而不是“插件”2.1 从 plugin 到 skills 的演进逻辑早期大家给编辑器加能力习惯叫 plugin插件。VS Code 的插件市场、IDEA 的插件仓库都是这个思路你装一个插件它往宿主程序里注入代码扩展功能。但到了 AI agent 这一层plugin 这个模型开始不太够用。原因在于传统插件是“代码级扩展”而 agent 需要的是“行为级扩展”。你没法用一段 Java 代码告诉模型“遇到这种需求时应该先读哪个文件、再跑哪条命令”。skills 的出现正好补上这一层。它更像是一份“岗位说明书 操作手册”的组合用自然语言描述这个技能什么时候触发、需要哪些输入、按什么步骤执行、产出什么结果。模型读到这份说明后就能在合适的时机调用它。热词里出现的 “claude agent skills: a first principles deep dive” 其实就是在讨论这个本质区别——plugin 扩展的是程序的能力边界skills 扩展的是 agent 的决策边界。这个区别带来的直接好处是skills 可以用自然语言写不需要编译不需要处理宿主程序的 API 兼容问题。你写一个“生成数据库迁移文件”的 skill本质上就是写清楚触发条件、输入参数、执行步骤和校验规则。模型负责理解脚本负责执行两边各干各擅长的事。2.2 skills 的组成结构拆解一个典型的 skill 通常包含几个部分。第一是元信息包括名称、描述、触发关键词这部分决定了 agent 什么时候会想到用它。第二是指令正文也就是告诉模型该怎么做可以是分步骤的说明也可以是带条件的决策树。第三是配套资源比如要调用的脚本、模板文件、参考文档。第四是约束与校验说明什么情况下不该用这个 skill以及产出需要满足什么标准。拿一个“前端组件生成”的 skill 举例。元信息里写清楚“当用户要求创建 React 组件时触发”。指令正文里规定先读项目里的组件目录结构确认命名风格再检查是否已有类似的组件可以复用然后按项目的样式方案CSS Modules 还是 Tailwind生成代码最后跑一遍 lint。配套资源里放一个组件模板文件。约束里写明“不要生成 class 组件项目统一用函数组件加 hooks”。这样一套下来模型每次生成的组件都能贴合项目规范而不是每次都要你重新解释一遍。这种结构的好处在于可复用和可组合。你可以把“读目录结构”抽成一个基础 skill把“生成组件”做成上层 skill后者调用前者。社区里讨论的 “superpower skills” 其实就是这种组合思路的延伸——把多个基础技能编排成一套完整的工作流。2.3 为什么 agent 时代需要 skills 这一层抽象有人会问我直接在对话里把要求说清楚不就行了为什么要封装成 skill短期看确实可以但长期看有三个问题。第一是一致性你每次描述需求的方式可能不一样模型每次的理解也会有偏差封装成 skill 相当于把最佳实践固化下来。第二是上下文成本一段复杂的操作说明可能有上千字每次都贴进对话里既浪费 token 又容易遗漏skill 可以被按需加载。第三是团队协作一个人的提示词技巧很难传递给整个团队但 skill 可以作为文件提交到仓库里所有人共享。热词里 “agents anywhere” 和 “find skills” 这两个词很能说明趋势大家希望 agent 能力可以跨工具、跨环境迁移也希望有一个地方能找到别人写好的 skill。这跟当年 npm 生态起来时的逻辑是一样的——先有包管理再有生态繁荣。skills 现在正处在从“个人技巧”向“可分发资产”过渡的阶段。3. 主流工具里的 skills 实操Claude Code 与 Codex 对比3.1 Claude Code 的 skills 安装与使用Claude Code 目前对 skills 的支持相对成熟官方市场里有一批可以直接安装的 skill。安装路径通常是在项目根目录或者用户配置目录下建一个 skills 文件夹每个 skill 一个子目录里面放说明文件和资源。安装方式有几种一种是从官方市场直接拉取一种是把别人分享的 skill 目录复制进来还有一种是自己在本地写。我实测下来最稳的方式是先在用户级配置目录里放通用 skill比如代码格式化、提交信息生成这类跨项目通用的然后在项目级目录里放项目专属的 skill比如这个项目的数据库迁移规范、API 路由约定。这样既避免了每个项目重复配置又保证了项目特有的规则能被正确加载。配置的时候有个细节要注意skill 的触发描述要写得足够具体但又不能太窄。写得太宽模型会在不相关的场景乱用写得太窄该触发的时候又触发不了。我的经验是描述里同时包含“做什么”和“什么时候做”比如“当需要为新接口生成单元测试时使用适用于项目使用 Jest 且测试文件放在tests目录的情况”。这样模型判断起来准确率高很多。3.2 Codex 的 skills 接入方式Codex 这边的 skills 机制跟 Claude Code 思路类似但配置入口和加载逻辑有差异。热词里 “codex skills” 和 “codex接入deepseek” 同时出现说明不少人在尝试把 Codex 接到不同的模型后端同时保留 skills 能力。这里要提醒一点skills 的效果跟底层模型的理解能力关系很大。同一个 skill在理解能力强的模型上触发准确、执行到位换到能力弱的模型上可能就时灵时不灵。Codex 的 skill 配置一般也是目录形式但要注意它的加载优先级。我遇到过项目级 skill 和用户级 skill 同名的情况结果加载的是用户级那个导致项目特有的规则没生效。后来查了加载顺序才明白得给项目级的 skill 起一个更具体的名字或者在描述里明确标注适用范围。这个坑在 Claude Code 里相对少见因为它的加载逻辑对项目级有更高优先级。另外 Codex 在 Windows 上的路径处理偶尔会出问题尤其是 skill 里引用了脚本的时候。如果你的 skill 需要调用 shell 脚本建议在说明里写清楚路径分隔符的处理方式或者干脆用跨平台的脚本语言写。我在 Windows 上跑一个带 Python 脚本的 skill 时就因为路径里的反斜杠被转义导致脚本找不到改成用 pathlib 处理路径后就正常了。3.3 两个工具在 skills 上的关键差异对比对比维度Claude CodeCodex官方市场有可直接安装相对较少多靠社区分享加载优先级项目级优先于用户级需注意同名覆盖问题脚本执行对 shell 脚本支持好跨平台脚本需额外处理触发判断描述匹配较精准依赖底层模型理解能力本地模型可接 LM Studio 等可接 DeepSeek 等这个表不是绝对的版本更新后可能会有变化但大方向上的差异是存在的。选哪个工具更多取决于你现有的工作流和模型偏好而不是 skills 能力本身的高低。4. 自己动手写一个 skill从需求到落地4.1 确定 skill 的边界与触发条件写 skill 的第一步不是写代码而是想清楚这个 skill 到底解决什么问题、什么时候该用、什么时候不该用。我见过不少人一上来就写一大段指令结果模型根本不知道什么时候该调用它。正确的做法是先写“触发条件”和“排除条件”。举个例子我想写一个“生成 API 接口文档”的 skill。触发条件可以写成当用户要求为某个接口生成文档或者当新增了接口文件需要补充文档时。排除条件可以写成当接口还在设计阶段、字段未确定时不使用当项目使用自动生成文档工具时不使用。把这两条写清楚模型判断起来就有依据了。边界确定之后再考虑这个 skill 需要哪些输入。是只需要接口文件路径还是需要额外的配置信息输入越明确skill 的复用性越强。我一般会把输入分成“必需”和“可选”两类必需的在说明里强调可选的给出默认值。4.2 编写指令正文的实用技巧指令正文是 skill 的核心写法上我总结了几个要点。第一是分步骤把操作拆成有序的步骤每步说清楚做什么、为什么做。第二是给示例尤其是输出格式给一个具体的例子比描述十句都管用。第三是设检查点在关键步骤后加一句“确认 XXX 后再继续”避免模型跳步。还有一个技巧是用条件分支。很多操作不是线性的需要根据情况走不同路径。比如“如果项目用 TypeScript 就生成 .ts 文件否则生成 .js 文件”。这种分支写清楚模型执行时就不会一刀切。指令的语言风格也有讲究。我试过用很正式的技术文档口吻写也试过用口语化的方式写实测下来口语化一点效果反而更好。因为模型本身就是在自然语言上训练的太生硬的表述反而容易让它理解偏差。当然也不能太随意关键的技术术语和约束还是要准确。4.3 配套资源与脚本的组织方式skill 目录里除了说明文件通常还会有脚本和模板。组织方式我建议按功能分文件夹比如 scripts 放脚本templates 放模板references 放参考文档。脚本的命名要能自解释比如 generate_migration.py 比 script1.py 好得多。脚本的健壮性很重要。因为 skill 可能在不同环境下被调用脚本要能处理常见的异常情况。比如读文件时文件不存在、写文件时目录不存在、调用外部命令时命令找不到。这些情况都要有明确的错误提示而不是直接抛一个看不懂的堆栈。我在一个 skill 的脚本里加了参数校验和错误处理之后模型调用时的成功率明显提升因为它能根据错误提示做出调整。模板文件建议用占位符标注需要替换的部分比如 {{COMPONENT_NAME}}、{{API_PATH}}。这样模型在生成内容时知道哪些地方要填什么不容易漏。4.4 测试与迭代怎么判断一个 skill 写得好不好skill 写完不是就完事了得测。测试的方法很简单找几个典型的场景看模型能不能正确触发、正确执行、正确产出。我一般会准备三组测试用例一组是应该触发的一组是不该触发的一组是边界情况。如果发现该触发的时候没触发通常是触发描述写得太窄或者太模糊需要调整关键词。如果发现不该触发的时候触发了通常是排除条件没写清楚或者描述里包含了太宽泛的词。如果触发了但执行结果不对那就要看指令正文是不是有歧义或者步骤是不是漏了。迭代的时候建议小步改每次只调一个地方然后重新测。一次性改太多出了问题都不知道是哪个改动导致的。我写第一个 skill 的时候改了七八版才稳定下来后面摸清套路后就快多了。5. 常见问题与排查技巧实录5.1 安装与加载类问题问题一skill 装了但模型不调用。这是最常见的问题。排查顺序是先确认 skill 目录位置对不对再确认说明文件的格式是否符合要求然后看触发描述是不是太窄。我遇到过一次是说明文件的文件名不对工具根本没识别到。还有一次是描述里用了工具不支持的标点符号导致解析失败。问题二多个 skill 冲突。当两个 skill 的触发条件有重叠时模型可能随机选一个或者两个都不选。解决办法是在描述里明确各自的适用范围或者把重叠的部分抽出来做成一个基础 skill让两个上层 skill 都调用它。问题三项目级 skill 不生效。检查加载优先级确认项目级目录的位置是否正确。有些工具需要在配置文件里显式声明项目级 skill 的路径光放文件还不够。5.2 执行与产出类问题问题四脚本执行报错。先看错误信息如果是路径问题检查路径分隔符和相对路径的基准目录。如果是权限问题检查脚本有没有执行权限。如果是依赖问题确认脚本需要的库有没有装。我在 Windows 上跑 shell 脚本时经常遇到路径问题后来统一用 Python 写脚本就少了很多麻烦。问题五产出格式不对。通常是指令正文里对输出格式的描述不够具体。解决办法是给一个完整的输出示例把格式、字段、顺序都写清楚。模型在模仿示例方面能力很强给个好例子比写一堆规则管用。问题六执行到一半停了。可能是步骤太长导致模型丢失上下文也可能是某个步骤的产出不符合预期导致后续步骤无法进行。解决办法是把长步骤拆短在关键节点加确认让模型有机会检查再继续。5.3 常见问题速查表现象可能原因排查动作skill 不触发描述太窄/格式错误检查文件名、格式、关键词错误触发排除条件缺失补充排除条件收窄描述脚本报错路径/权限/依赖逐项检查加错误处理产出格式乱示例不清晰补充完整输出示例执行中断步骤过长/上下文丢失拆分步骤加检查点多 skill 冲突触发条件重叠明确边界或抽公共部分5.4 几个我踩过的坑和独家技巧第一个坑是在 skill 里写太具体的路径。我一开始把项目路径硬编码在 skill 里结果换个项目就不能用了。后来改成用相对路径加环境变量通用性好了很多。第二个坑是忽略模型的上下文限制。skill 的说明写得太长加上项目本身的上下文很容易超出模型的窗口限制。后来我把不常用的参考文档拆出去只在需要时加载主说明文件控制在合理长度内。一个实用技巧是给 skill 加版本号。在说明文件里标注版本和更新日期方便追踪改动。尤其是团队协作时能避免有人用了旧版本的 skill 导致结果不一致。另一个技巧是把常用的 skill 组合成工作流。比如“新建功能”这个流程可以拆成“创建分支”“生成代码”“写测试”“提交”几个 skill然后用一个上层 skill 把它们串起来。这样既保持了每个 skill 的独立性又能一键完成整个流程。6. 跨环境使用 skills 的注意事项6.1 在 VS Code 和 IDEA 里的配置差异VS Code 和 IDEA 对 skills 的支持方式不太一样。VS Code 更多是通过扩展来接入 Claude Code 或 Codexskills 的配置通常跟着扩展走。IDEA 这边则需要在插件设置里配置插件仓库地址热词里 “idea设置plugin中插件仓库地址” 说的就是这个。配置的时候要注意仓库地址的格式以及是否需要额外的认证信息。在 IDEA 里用 skills我建议先确认插件版本和工具版本的兼容性。我遇到过一次插件版本太旧不支持新版 skill 的格式升级后就正常了。另外 IDEA 的项目级配置和全局配置要分清楚别把项目专属的 skill 放到全局目录里不然换个项目会出问题。6.2 本地模型接入时的 skills 适配热词里 “claude code 调用lmstudio的本地模型” 和 “codex接入deepseek” 说明不少人在用本地或第三方模型。这里要注意skills 的效果跟模型能力直接相关。本地小模型可能在触发判断上就不太准执行复杂步骤时也容易跑偏。我的建议是如果要用本地模型先从简单的 skill 开始确认模型能稳定执行后再逐步增加复杂度。另外本地模型的上下文窗口通常比云端模型小skill 的说明要写得更精简。可以把详细的参考文档做成按需加载的形式而不是一股脑塞进主说明里。6.3 团队协作中的 skills 管理团队里用 skills最重要的是统一管理。我建议把 skill 目录纳入版本控制跟代码一起提交。每个 skill 的改动都走正常的代码评审流程这样能保证质量。同时要有一个 README 说明每个 skill 的用途和使用方式新人进来能快速上手。还要注意 skill 的命名规范。团队里最好约定一个前缀或者分类方式比如 frontend-xxx、backend-xxx这样找起来方便也不容易冲突。定期清理不再使用的 skill避免目录越来越臃肿。7. 关于 skills 生态的一些个人观察skills 这个方向目前还在快速演进。从热词里能看出来大家关注的点已经从“有没有”转向“好不好用”和“怎么自己写”。社区里分享的 skill 越来越多但质量参差不齐。我的建议是用别人的 skill 之前先读一遍说明确认它的假设跟你的项目一致别直接拿来就用。另一个观察是skills 正在从单点能力向工作流编排发展。单个 skill 解决一个具体问题多个 skill 组合起来能完成一个完整任务。这个趋势跟当年从函数到模块再到框架的演进很像。未来可能会出现专门做 skill 编排的工具或者平台让非技术人员也能组装出自己的 agent 工作流。我自己现在的做法是把日常重复性高的操作都尽量封装成 skill。写代码、写测试、生成文档、处理数据能封装的都封装。一开始投入时间写 skill后面省下来的时间远超投入。而且 skill 写多了之后对怎么跟模型有效沟通的理解也更深了反过来又能写出更好的 skill形成正向循环。最后分享一个小技巧写 skill 的时候把自己想象成在给一个新同事写操作手册。你会怎么写就怎么让模型理解。这个视角转换过来之后很多之前觉得模糊的地方就清晰了。