1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到skills、claude code、codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词几乎都指向同一个东西——给 AI 编程助手装上一套可复用的“技能包”。我先用大白话解释一下这个概念。你可以把 Claude Code、Codex 这类 AI 编程工具想象成一个刚入职的实习生脑子很聪明但对你公司的代码规范、项目结构、常用命令一无所知。每次你让它干活都得从头交代一遍“我们用的是 pnpm 不是 npm”“提交信息要遵循 Conventional Commits”“测试跑 vitest 不是 jest”。说一次两次还行天天说谁都受不了。skills 就是把这些重复交代的东西固化下来变成 AI 可以自动加载的“技能说明书”。一个 skill 本质上就是一个结构化的文件夹里面包含一段描述告诉 AI 这个技能是干什么的、什么时候该用加上具体的指令、脚本或者参考资料。AI 在接到任务时会先扫描有哪些可用的 skills然后按需加载对应的那个就像人翻手册一样。这件事为什么重要因为它把 AI 编程从“每次都要手把手教”推进到了“一次配置、长期复用”的阶段。对于每天都要和 AI 结对编程的人来说skills 直接决定了你是在高效产出还是在反复解释。适合读这篇内容的人很明确已经在用或者准备用 Claude Code、Codex 这类工具的开发者尤其是那些觉得“AI 挺好用但总差一口气”的人。我下面会从设计思路、核心机制、实操落地、踩坑排查几个角度把 skills 这套东西彻底拆开讲清楚。内容会涉及 Claude Code 和 Codex 两个主流平台也会提到 plugin、agents 这些相关概念怎么和 skills 配合。2. skills 的整体设计与核心思路拆解2.1 为什么是“技能包”而不是“配置文件”很多人第一次接触 skills 会有一个疑问我直接写一个.cursorrules或者CLAUDE.md不就行了吗为什么要搞这么复杂的文件夹结构这个问题的答案藏在上下文窗口的经济学里。你写的每一段指令都会占用 AI 的上下文 token而上下文是有限且昂贵的。如果你把所有规范、所有命令、所有项目背景都塞进一个全局配置文件那每次对话一开始就消耗掉大量 token而且大部分内容跟当前任务根本无关。skills 的设计精髓在于渐进式披露progressive disclosure。AI 启动时只加载每个 skill 的“元数据”——也就是名字和一句简短描述这部分非常轻量。只有当 AI 判断当前任务需要用到某个 skill 时才会把它的完整内容读进来。这就像你书架上摆了一排工具书你不需要把每本书都背下来只需要知道哪本书讲什么用到的时候再翻。提示这个设计思路直接决定了你写 skill 描述的方式。描述写得好不好直接决定 AI 能不能在正确的时机找到正确的技能。描述写得太笼统AI 要么该用的时候想不起来要么不该用的时候乱加载。2.2 Claude Code 和 Codex 在 skills 上的路线差异虽然都叫 skills但 Claude Code 和 Codex 的实现路线有明显区别理解这个差异对你选型很关键。Claude Code 的 skills 体系更偏向文件系统驱动。它有一套约定俗成的目录结构skill 放在特定路径下通过SKILL.md文件来定义。Claude Code 还支持从官方市场或者团队仓库拉取 skills社区生态相对活跃。你在热搜里看到的claude 国内安装skills 官方市场、claude code 安装这些词反映的就是大家在找怎么把 skills 装进 Claude Code。Codex 这边的 skills 更强调和 agent 工作流的绑定。Codex 本身就是一个 agent 化的编程助手skills 在它这里更像是给 agent 扩展能力的插件。热搜里的codex skills、codex接入deepseek、codex好用的skills说明大家关心的是怎么让 Codex 通过 skills 接入不同的模型或者工具链。我的建议是如果你主要用 Claude Code重点研究它的目录约定和官方市场如果你用 Codex重点研究它怎么把 skill 和 agent 任务编排结合起来。两者不是互斥的很多人两个都在用。2.3 plugin、agents、skills 三者的关系这三个词经常一起出现但很多人搞不清它们的边界。我用一个类比来说明skills是“技能”比如“会写单元测试”“会做代码审查”“会生成数据库迁移脚本”。agents是“执行者”是一个能自主规划、调用工具、完成多步任务的智能体。一个 agent 可以拥有多个 skills。plugin是“插件”是更外层的打包和分发机制。一个 plugin 里可以包含若干个 skills甚至包含 agent 的配置。所以它们的关系是层层包含的plugin 打包 skillsagent 使用 skills。热搜里的dsh plugin --profile web add dshmarket、idea设置plugin中插件仓库地址这些说的就是 plugin 层面的安装和配置。理解了这层关系你在看各种文档时就不会晕。3. 核心细节解析与实操要点3.1 一个 skill 的最小结构长什么样不管哪个平台一个 skill 的核心结构都差不多。我以最常见的SKILL.md形式来说明这是 Claude Code 体系里最标准的做法。一个 skill 文件夹通常包含my-skill/ ├── SKILL.md # 必需技能的主定义文件 ├── scripts/ # 可选放可执行脚本 ├── references/ # 可选放参考资料 └── assets/ # 可选放模板、图片等SKILL.md本身由两部分组成YAML frontmatter和Markdown 正文。frontmatter 里最关键的是name和description两个字段。--- name: api-test-generator description: 当用户需要为 REST API 生成集成测试时使用。适用于 Express、Fastify、NestJS 项目输出 vitest 或 jest 格式的测试文件。 --- # API 测试生成器 ## 使用场景 当用户提到给这个接口写测试生成 API 测试补充集成测试时触发。 ## 执行步骤 1. 读取目标路由文件识别 HTTP 方法和路径 2. 检查项目使用的测试框架看 package.json 3. 按照项目现有的测试风格生成测试用例 4. 覆盖正常路径、边界条件、错误处理三类场景 ## 注意事项 - 不要生成 mock 数据库的测试本项目用真实测试库 - 测试文件命名遵循 *.test.ts 规范这个结构看起来简单但每个部分都有讲究。description字段是 AI 决定是否加载这个 skill 的唯一依据所以它必须同时说清楚“做什么”和“什么时候用”。我见过太多人把 description 写成“一个测试生成工具”结果 AI 永远想不起来用它。3.2 description 的写法决定了 skill 的命中率这是我要重点强调的一点也是很多人踩坑的地方。description 不是给你看的是给 AI 做语义匹配用的。它需要包含三类信息第一类是能力描述说明这个 skill 能做什么。第二类是触发条件说明什么情况下应该用。第三类是适用范围说明它适合什么技术栈或场景。我对比两种写法你就明白了写法description 内容实际效果差生成测试AI 不知道什么时候该用经常漏掉好当用户需要为 REST API 生成集成测试时使用。适用于 Express、Fastify、NestJS 项目输出 vitest 或 jest 格式的测试文件AI 能在用户提到 API 测试时准确命中实测下来description 里包含具体的技术栈名称和用户可能说的自然语言短语命中率能提升一大截。你可以把用户可能说的原话都塞进去比如“写测试”“补测试”“生成测试用例”这些。3.3 脚本和参考资料怎么放skill 不只是文字指令它还可以带可执行脚本。这是它比普通配置文件强大的地方。举个例子你有一个 skill 是“生成数据库迁移文件”。你可以放一个scripts/gen-migration.sh脚本然后在SKILL.md里写“执行scripts/gen-migration.sh table_name来生成迁移文件”。AI 在需要的时候会直接调用这个脚本而不是自己瞎编一个迁移文件。参考资料references则适合放那些“AI 需要知道但不需要每次都读”的内容。比如你项目的 API 规范文档、数据库 schema 说明、第三方服务的接口文档。AI 在需要的时候会去读这些文件平时不占用上下文。注意脚本一定要做好参数校验和错误处理。AI 调用脚本时可能传错参数如果脚本直接崩了AI 会陷入困惑。我一般会在脚本开头加一段参数检查参数不对就输出清晰的错误信息这样 AI 能自己纠正。3.4 安装路径和加载机制不同平台的 skill 存放路径不一样这是新手最容易卡住的地方。Claude Code 通常会在项目根目录或者用户主目录下寻找 skills。项目级的 skills 放在.claude/skills/下用户级的放在~/.claude/skills/下。项目级的优先级更高适合放跟当前项目强相关的技能用户级的适合放你个人通用的技能。Codex 的路径约定略有不同具体要看版本。热搜里codex安装、codex安装教程、codex安装包这些词热度很高说明很多人在初次配置阶段。我的建议是先把官方文档的路径约定确认清楚别凭感觉放放错地方 AI 根本扫不到。加载机制上AI 启动时会扫描所有 skill 目录读取每个SKILL.md的 frontmatter。这个过程很快因为只读元数据。当对话进行到某个节点AI 判断需要某个 skill 时才会读取完整内容。所以你不用担心装了几十个 skill 会拖慢启动。4. 实操过程与核心环节实现4.1 从零搭建第一个 skill 的完整流程我拿一个真实场景来演示给一个用 pnpm vitest 的 TypeScript 项目做一个“代码审查”skill。第一步确定目录。在项目根目录创建.claude/skills/code-review/SKILL.md。第二步写 frontmatter。这一步最关键我反复打磨过很多次--- name: code-review description: 当用户要求审查代码、检查代码质量、review PR 或者提到看看这段代码有没有问题时使用。适用于 TypeScript/JavaScript 项目重点关注类型安全、错误处理、性能隐患和测试覆盖。 ---第三步写正文。正文要分清楚“什么时候用”“怎么做”“注意什么”# 代码审查技能 ## 审查维度 1. 类型安全有没有 any、类型断言是否滥用 2. 错误处理异步操作有没有 catch、边界条件有没有处理 3. 性能有没有不必要的循环、有没有 N1 查询 4. 测试新增逻辑有没有对应测试 ## 执行步骤 1. 先用 git diff 看本次改动范围 2. 逐个文件审查按上面的维度打分 3. 输出审查报告按严重程度排序 4. 对每个问题给出具体的修改建议 ## 输出格式 用表格列出问题包含文件路径、行号、问题描述、严重程度、修改建议第四步测试。故意写一段有问题的代码让 AI 审查看它能不能触发这个 skill。如果没触发回去改 description。第五步迭代。用了几次之后你会发现有些问题 AI 总是漏掉把这些补充到审查维度里。skill 是活的要持续打磨。4.2 参数计算skill 数量多少合适很多人一上来就想装几十个 skill觉得越多越强大。这是个误区。每个 skill 的元数据都会占用一点上下文虽然不多但几十个加起来也可观。更重要的是skill 太多会导致 AI 的选择困难——两个 skill 的 description 有重叠时AI 可能选错。我的经验值是项目级 skill 控制在 5 到 10 个用户级 skill 控制在 10 到 15 个。超过这个数量就要考虑合并或者删减。怎么判断该不该合并如果两个 skill 经常在同一个任务里一起被用到那它们大概率应该合并成一个。比如“写测试”和“跑测试”经常一起出现可以合并成“测试工作流”。4.3 用 plugin 机制批量分发 skills当你有一套成熟的 skills想分享给团队或者社区时plugin 机制就派上用场了。一个 plugin 本质上是一个包含多个 skills 的仓库加上一个清单文件。清单文件里声明这个 plugin 包含哪些 skills、版本号、依赖关系等。团队成员通过一条命令就能把整套 skills 装到本地。热搜里的dsh plugin --profile web add dshmarket就是这类操作的典型命令。不同平台的命令格式不一样但思路是一致的指定一个源把 plugin 拉下来解压到对应的 skills 目录。提示做团队级 plugin 时一定要做版本管理。skills 的更新会直接影响团队所有人的 AI 行为没有版本管理的话某天你改了一个 skill别人那边行为突然变了排查起来很痛苦。我一般用语义化版本破坏性变更升大版本。4.4 让 skill 和 agent 工作流配合起来单独的 skill 是静态的只有和 agent 的动态执行结合起来才能发挥最大价值。举个例子你可以配置一个“PR 审查 agent”它的工作流是拉取 PR 的 diff调用 code-review skill 做审查调用 test-runner skill 跑测试最后把结果汇总成评论发到 PR 上。整个流程里agent 负责编排skills 负责具体能力。Codex 在这方面做得比较自然因为它本身就是 agent 优先的设计。Claude Code 则需要你通过配置或者提示词来引导 agent 行为。热搜里的langchain deep agents、agents anywhere反映的就是大家在探索 agent 编排的各种方案。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。你辛辛苦苦写了一个 skill结果 AI 该用的时候不用急死人。排查顺序是这样的第一检查路径。确认 skill 放在正确的目录下文件名是SKILL.md而不是skill.md或者SKILLS.md。大小写敏感的系统上这个错误很常见。第二检查 frontmatter 格式。YAML 对缩进极其敏感多一个空格少一个空格都可能解析失败。我建议用在线 YAML 校验工具过一遍。第三检查 description。这是最常见的原因。把 description 读一遍问自己如果我是 AI看到用户说“帮我看看这段代码”我会想到加载这个 skill 吗如果答案是否定的就改 description。第四检查是否有冲突。如果两个 skill 的 description 高度相似AI 可能选了另一个。把它们的触发条件区分得更明确一些。5.2 skill 加载了但行为不对有时候 skill 确实触发了但 AI 的执行结果不符合预期。这通常是正文写得不够明确。AI 不是人它不会“领会精神”。你写“注意代码质量”它不知道具体指什么。你写“检查有没有 any 类型、有没有未处理的 Promise rejection、有没有硬编码的密钥”它就能准确执行。我的经验是正文里的每一条指令都要具体到可以机械执行的程度。模糊的形容词是 skill 的天敌。5.3 常见问题速查表问题现象可能原因解决方法skill 完全不触发路径错误或文件名不对确认目录结构和文件名大小写skill 偶尔触发description 不够具体补充技术栈和用户常用短语skill 触发但结果差正文指令太模糊把每条指令具体化、可执行化多个 skill 冲突description 重叠明确区分触发条件或合并脚本调用失败参数校验缺失脚本开头加参数检查和清晰报错更新 skill 后行为没变缓存未刷新重启 AI 工具或清理缓存团队协作时行为不一致版本不同步用 plugin 版本管理统一分发5.4 几个我踩过的坑第一个坑是在 description 里写太多技术细节。我一开始觉得写得越详细越好结果 description 太长AI 匹配时反而抓不住重点。后来我改成description 只写“做什么”和“什么时候用”技术细节全部放到正文里。第二个坑是skill 之间互相依赖但没声明。我有一个 skill 依赖另一个 skill 生成的输出格式但没在文档里说明。结果单独用第二个 skill 时AI 不知道输入格式输出乱七八糟。后来我在每个有依赖的 skill 里都明确写了“前置条件”和“输入格式要求”。第三个坑是忽略了不同 AI 工具的差异。同一个 skill 在 Claude Code 里工作正常换到 Codex 就行为不对。原因是两个平台对 skill 的解析细节有差异比如对 frontmatter 字段的支持程度不同。所以跨平台使用时要针对每个平台做适配测试。第四个坑是skill 写得太“聪明”。我试图让一个 skill 处理所有类型的测试生成结果它什么都做不好。后来拆成三个单元测试、集成测试、端到端测试每个都专注一个场景效果立刻上来了。skill 要专一不要贪多。5.5 关于安全和权限的提醒skill 里的脚本是有执行权限的这一点必须重视。你从社区下载的 skill里面的脚本可能做任何事。我建议安装第三方 skill 前把里面的脚本通读一遍不要在 skill 脚本里硬编码密钥或敏感信息团队共享的 skill 要走代码审查流程定期清理不再使用的 skill减少攻击面热搜里agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个词反映的就是 agent 和 skill 被投毒的风险。虽然这是研究性质的话题但提醒我们skill 作为一种能被 AI 自动加载和执行的东西它的安全性值得认真对待。6. 进阶玩法让 skills 真正融入你的开发流6.1 按项目阶段组织 skills我现在的做法是按开发阶段来组织 skills而不是按功能。具体来说分四组规划阶段需求拆解、技术方案设计、任务拆分。编码阶段代码生成、代码审查、重构建议。测试阶段测试生成、测试运行、覆盖率分析。交付阶段提交信息生成、PR 描述生成、变更日志生成。这样组织的好处是AI 在不同阶段能快速找到对应的技能组不会在编码时去加载测试相关的 skill。6.2 用 skill 固化团队规范这是 skills 最有价值的应用场景之一。每个团队都有自己的规范但规范文档写出来没人看AI 更不会主动遵守。把规范做成 skillAI 在干活时自动遵守效果立竿见影。比如你们团队的提交信息规范是 Conventional Commits那就做一个commit-messageskill里面写清楚格式、类型枚举、示例。以后 AI 生成提交信息时自动就符合规范了。再比如你们的 API 设计规范、数据库命名规范、日志格式规范都可以做成 skill。新成员加入时不用花一周时间读文档AI 直接带着规范干活。6.3 skill 的测试和迭代skill 也需要测试。我的做法是建一个skill-tests目录里面放一些典型的用户输入然后手动跑一遍看 AI 的行为是否符合预期。比如测试code-reviewskill我会准备三段代码一段有明显 bug 的、一段有性能问题的、一段没问题的。然后分别让 AI 审查看它能不能准确识别。迭代节奏上我一般每两周回顾一次 skill 的使用情况。哪些经常触发、哪些从不触发、哪些触发后效果不好根据实际情况调整。skill 不是写完就完事的它需要像代码一样维护。6.4 跨工具复用的现实考量很多人问能不能一套 skill 在 Claude Code、Codex、Cursor 之间通用。现实是核心内容可以复用但需要适配层。SKILL.md的正文部分基本是通用的因为都是自然语言指令。差异主要在 frontmatter 字段和加载机制上。我的做法是维护一份“源 skill”然后用脚本生成各平台需要的格式。这样改一处处处更新。热搜里vscode配置claude code、claude code for vs code、idea使用skills这些词说明大家在不同 IDE 里用这些工具。好消息是 skills 本身和 IDE 关系不大它依赖的是 AI 工具本身不是编辑器。所以你在 VS Code 里配好的 skill换到 IDEA 里只要 AI 工具一样skill 照样能用。6.5 我个人的一些使用心得用了大半年 skills最大的感受是它把 AI 编程从“对话”变成了“协作”。以前是我说一句 AI 做一步现在是我定义好规则和技能AI 自己按规则干活。这个转变带来的效率提升是数量级的。另一个感受是写 skill 的过程其实是在梳理你自己的知识。很多时候你以为自己很清楚某个流程但真要写成 skill 时才发现有很多模糊地带。这个过程逼你把隐性知识显性化对个人成长也有好处。最后一个建议从一个小 skill 开始别一上来就搞大而全的体系。先做一个你每天都要重复交代的事情把它变成 skill用一周感受一下效果。有感觉了再扩展。skills 这东西用起来比看起来简单但用好需要时间打磨。如果你现在还在纠结claude code安装、codex安装这些基础问题我的建议是先装好工具跑通一个最简单的 skill再逐步深入。工具是死的skill 是活的把精力花在打磨 skill 上回报率最高。
