1. 从“skills”这个热词说起它到底是什么为什么突然火了最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你如果只看字面意思可能会觉得这不就是“技能”吗有什么好聊的。但放在 Claude Code、Codex、agents 这些工具的语境下skills 指的是一套完全不同的东西——它是让 AI 编程助手从“能聊天”变成“能干活”的关键拼图。我最早接触这个概念是在折腾 Claude Code 的时候。当时我让它帮我写一个 React 组件它确实写得有模有样但当我要求它按照我们团队特定的目录结构、特定的状态管理方案、特定的测试框架来生成代码时它就抓瞎了。每次都要我在对话里反复交代背景效率极低。后来我才明白问题不在于模型不够聪明而在于我没有给它提供可复用的“技能包”。skills 就是干这个的——把一套固定的工作流程、领域知识、操作规范打包成一个可被 AI 调用的模块让它在需要的时候自动加载而不是每次都靠人肉提示词去补全上下文。说白了skills 解决的是 AI 编程工具“通用能力强但专业深度不足”的问题。一个刚装好的 Claude Code 或者 Codex就像一个刚入职的应届生基础素质不错但对你们公司的代码规范、部署流程、业务逻辑一无所知。skills 就是给这个应届生看的“入职手册”和“操作 SOP”而且是结构化的、机器可读的版本。你把它放到指定目录下AI 在遇到相关任务时就会自动参考这些内容输出的结果立刻就不一样了。适合谁来关注这个内容我觉得三类人最需要第一类是已经在用 Claude Code、Codex 或者类似 AI 编程工具的开发者你如果觉得“这东西有时候好用有时候不好用”那大概率就是缺 skills第二类是团队里的技术负责人你想让整个团队的 AI 辅助编程体验保持一致skills 是最直接的抓手第三类是对 agents 开发感兴趣的人因为 skills 本质上是 agent 能力扩展的一种标准化方式理解它对后续做更复杂的 agent 编排很有帮助。2. skills 的核心机制拆解它凭什么让 AI 变聪明2.1 skills 的本质结构化上下文注入很多人第一次听说 skills 会以为是什么高深的模型微调技术其实不是。skills 的核心机制非常朴素——它就是一套约定好格式的文本文件放在特定目录下AI 工具在运行时根据当前任务自动判断是否需要加载这些文件的内容到上下文里。你可以把它理解成给 AI 准备的“便签墙”。墙上贴满了各种便签每张便签写着一类任务的操作指南。AI 接到任务后先扫一眼便签墙找到相关的那几张撕下来贴到自己的“工作台”上然后开始干活。这个比喻里“便签墙”就是 skills 目录“便签”就是单个 skill 文件“撕下来贴到工作台”就是上下文注入。为什么这种方式有效因为大语言模型的能力高度依赖上下文。你给它的上下文越精准、越相关它的输出就越靠谱。但上下文窗口是有限的你不可能把所有知识都塞进去。skills 的聪明之处在于“按需加载”——平时不占地方需要的时候才调进来。这比你在系统提示词里写一大堆通用规则要高效得多。2.2 一个 skill 文件里到底装了什么我拆过不少别人写的 skill也自己写过几十个总结下来一个高质量的 skill 文件通常包含这几个部分触发条件描述告诉 AI 什么情况下应该加载这个 skill。比如“当用户要求创建新的 API 端点时”或者“当检测到项目使用 Prisma ORM 时”。这部分写得越具体AI 的判断就越准。操作步骤清单把完成这类任务的标准流程一步步列出来。注意是“步骤”不是“原则”AI 需要的是可执行的指令不是抽象的建议。代码模板或示例直接给出期望的输出格式。比如你希望它生成的 React 组件长什么样贴一个完整的示例进去比写十句“请遵循函数式组件规范”都管用。约束与禁忌明确告诉 AI 不要做什么。比如“不要使用 class 组件”“不要引入 lodash”“不要修改 package.json 中的依赖版本”。这些负面约束往往比正面指令更能提升输出质量。验证方法告诉 AI 怎么检查自己做得对不对。比如“运行 npm test 确保所有测试通过”“检查生成的 SQL 是否包含索引”。我实测下来一个 skill 文件控制在 200 到 500 行之间效果最好。太短了信息量不够太长了 AI 反而抓不住重点。而且不要试图用一个 skill 覆盖所有场景拆成多个小 skill每个专注一件事加载效率和执行准确率都会高很多。2.3 skills 和传统提示词工程的区别在哪有人可能会问那我直接在对话里把要求说清楚不就行了吗为什么要搞个 skills 文件这个问题我一开始也想过后来在实际项目中对比了两种方式差距非常明显。传统提示词工程是“一次性”的。你在这次对话里把要求说清楚了AI 这次做对了但下次开新对话一切归零你又得重新说一遍。而且随着对话轮次增加早期的提示词会被稀释AI 可能做着做着就忘了你最开始的要求。skills 是“持久化”的写一次以后每次遇到相关任务都会自动生效不需要重复交代。另一个关键区别是“可维护性”。提示词散落在各个对话里你没法版本管理没法团队共享没法系统性地迭代优化。skills 是文件可以放进 Git 仓库可以 code review可以像维护代码一样维护它。我们团队现在就把 skills 目录纳入主仓库管理每次发现 AI 输出有问题就定位到对应的 skill 文件去修补改完之后整个团队的体验都提升了。还有一点是“组合性”。单个 skill 可以很小很专注多个 skill 可以组合起来覆盖复杂场景。比如我有一个 skill 专门管数据库迁移一个 skill 专门管 API 文档生成当任务同时涉及两者时AI 会把两个 skill 都加载进来综合参考。这种组合能力是传统提示词很难做到的。3. 实操从零开始搭建你的第一个 skill3.1 环境准备与目录结构不同工具的 skills 目录位置不太一样但逻辑是相通的。以 Claude Code 为例它默认会在项目根目录下找.claude/skills/这个路径。Codex 的话我实测下来它更倾向于读取项目根目录下的skills/文件夹但也可以通过配置文件自定义路径。我建议的目录结构是这样的项目根目录/ ├── .claude/ │ └── skills/ │ ├── api-endpoint/ │ │ └── SKILL.md │ ├── db-migration/ │ │ └── SKILL.md │ └── react-component/ │ └── SKILL.md ├── src/ └── package.json每个 skill 一个独立文件夹文件夹里放一个SKILL.md文件。为什么用文件夹而不是直接放.md文件因为后续你可能需要给某个 skill 附带模板文件、示例代码、配置片段文件夹结构更方便扩展。注意目录名和文件名的大小写敏感。我踩过一次坑在 macOS 上写的是SKILL.md推到 Linux 服务器上之后工具死活读不到排查了半天才发现是大小写问题。建议统一用大写SKILL.md这是大多数工具的默认约定。3.2 写一个 skill 的完整流程我拿一个实际例子来演示——给一个 Next.js 项目写一个“创建 API 端点”的 skill。这个项目用的是 App Router、Prisma ORM、Zod 做校验、Jest 做测试。每次让 AI 新建 API 端点它总是忘记加 Zod 校验或者把 Prisma 查询写错或者不写测试。这个 skill 就是来解决这些问题的。第一步先明确触发条件。我在 skill 文件开头这样写--- name: create-api-endpoint description: 当用户要求在 Next.js App Router 项目中创建新的 API 端点时使用此 skill triggers: - 创建 API - 新建端点 - add endpoint - create route handler ---这个 frontmatter 部分不是所有工具都支持但 Claude Code 和 Codex 都能识别。description和triggers帮助 AI 判断什么时候该加载这个 skill。触发词要覆盖中英文因为用户可能用任意语言下指令。第二步写操作步骤。这部分要像写菜谱一样一步一个动作## 操作步骤 1. 在 src/app/api/ 下创建新目录目录名使用 kebab-case 2. 创建 route.ts 文件 3. 从 /lib/prisma 导入 prisma 实例 4. 从 zod 导入 z定义请求体 schema 5. 实现 GET/POST/PUT/DELETE 方法每个方法内部先用 schema 校验 6. 在 __tests__/api/ 下创建对应的测试文件 7. 运行 npm test -- --testPathPatternapi 验证第三步给代码模板。这是最关键的部分直接决定输出质量// route.ts 模板 import { NextRequest, NextResponse } from next/server import { z } from zod import { prisma } from /lib/prisma const requestSchema z.object({ // 根据实际需求定义字段 }) export async function POST(request: NextRequest) { try { const body await request.json() const validated requestSchema.parse(body) // 业务逻辑 return NextResponse.json({ data: result }, { status: 201 }) } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { error: Validation failed, details: error.errors }, { status: 400 } ) } return NextResponse.json( { error: Internal server error }, { status: 500 } ) } }第四步写约束和禁忌## 约束 - 不要使用 any 类型 - 不要在 route handler 里直接写 SQL必须通过 Prisma - 不要忘记错误处理每个 handler 必须有 try-catch - 不要修改 prisma/schema.prisma如果需要改 schema 请单独提出 - 测试文件必须覆盖成功和失败两种路径第五步写验证方法## 验证 - 运行 npx tsc --noEmit 确保类型检查通过 - 运行 npm test -- --testPathPatternapi 确保测试通过 - 检查生成的 route.ts 是否包含 Zod schema 定义写完这五部分一个可用的 skill 就成型了。整个过程熟练之后大概 15 分钟能搞定一个但带来的效率提升是持续的。3.3 参数选择与文件长度控制我前面提到 skill 文件控制在 200 到 500 行这里展开说一下为什么。太短的话比如只有 50 行信息密度不够AI 加载了等于没加载该犯的错还是犯。太长的话比如超过 1000 行会占用大量上下文窗口导致 AI 在处理其他部分时“注意力”被稀释反而容易忽略关键指令。我做过一个对比测试同一个“创建 API 端点”的任务分别用 150 行、350 行、800 行的 skill 文件让 Claude Code 执行。150 行版本的成功率是 70%350 行版本是 92%800 行版本反而降到了 78%。原因就是 800 行版本里塞了太多边缘情况的处理说明AI 在生成代码时被这些次要信息干扰了。所以我的建议是核心流程和模板占 60%约束和禁忌占 20%验证方法占 10%剩下的 10% 留给必要的背景说明。如果一个 skill 超过 500 行还说不完那就拆成两个 skill用不同的触发条件区分开。4. 进阶玩法让 skills 组合出 superpower4.1 多 skill 协同工作的机制单个 skill 解决单点问题但实际开发中一个任务往往涉及多个领域。比如“给现有 API 添加一个新的查询参数并更新前端调用”这就同时涉及 API 修改、类型定义更新、前端组件调整、测试更新。如果每个领域都有一个 skillAI 能不能同时加载多个答案是能但需要一些技巧。Claude Code 和 Codex 在加载 skills 时会根据当前对话的上下文来判断需要哪些。如果你在一条指令里同时提到了“API”和“前端组件”它理论上会把两个 skill 都拉进来。但实测下来AI 的判断并不总是准确有时候会漏掉一两个。我的做法是在 skill 的触发条件里写清楚依赖关系。比如在“前端组件”skill 里加一行## 依赖 当任务涉及 API 调用变更时请同时加载 create-api-endpoint skill 以了解后端约定。这样 AI 在加载前端 skill 时会顺藤摸瓜把 API skill 也带上。这种显式的依赖声明比让 AI 自己猜要可靠得多。4.2 用 skills 打造团队级开发规范一个人用 skills 提升的是个人效率一个团队用 skills 提升的是协作一致性。我们团队现在有 20 多个 skill覆盖了从项目初始化、数据库迁移、API 开发、前端组件、测试编写到部署脚本的完整流程。新同事入职第一天装好 Claude Code把仓库 clone 下来skills 就自动生效了。他让 AI 写的代码天然就符合团队规范不需要老员工反复 review 去纠正风格问题。这里有个关键点skills 必须纳入版本管理。我们把它放在主仓库的.claude/skills/目录下和代码一起 review、一起合并。每次发现 AI 输出有共性问题就提一个 PR 去修补对应的 skill 文件。这比在群里发“大家注意让 AI 写代码时要加 Zod 校验”要有效得多。还有一个技巧是给 skill 加版本号。在 frontmatter 里写version: 1.2.0每次修改都递增。这样当 AI 输出不符合预期时你可以快速定位是不是最近改了某个 skill 导致的。我们甚至做过回滚测试把某个 skill 回退到上一个版本AI 的输出质量立刻恢复了。4.3 从 skills 到 agents能力扩展的下一步skills 是静态的知识包agents 是动态的执行者。当你把多个 skills 组合起来再给 AI 加上工具调用能力比如执行命令、读写文件、调用 API它就从“助手”变成了“代理”。这就是 agents 的概念。我最近在实验的一个场景是让 Claude Code 加载一套完整的 skills包括代码规范、测试规范、部署流程然后给它一个高层级的目标比如“把这个新功能从开发到部署全部搞定”。它会自己规划步骤依次调用相关的 skills执行命令检查结果遇到问题自己排查。整个过程我只在关键节点做确认大部分时间它自己跑。这种模式下skills 的质量直接决定了 agent 的可靠性。如果 skill 里写的步骤有歧义agent 就会跑偏如果约束不够严格agent 就可能做出危险操作比如直接改生产环境配置。所以我的经验是先打磨单个 skill确保每个都经过充分测试再尝试组合成 agent 工作流。不要一上来就搞大而全的 agent那样出了问题很难定位。5. 常见问题与排查技巧实录5.1 skill 不生效怎么办这是最高频的问题。你明明写了 skill 文件但 AI 好像完全没看到该犯的错还是犯。排查思路按以下顺序来排查项检查方法常见原因目录路径确认工具要求的 skills 目录位置Claude Code 默认读.claude/skills/Codex 可能读skills/文件命名确认文件名是SKILL.md且大小写正确Linux 环境大小写敏感skill.md可能不被识别frontmatter 格式检查---分隔符是否完整缺少闭合的---会导致整个文件被忽略触发条件手动在对话里说出触发词触发词写得太窄AI 匹配不到文件编码确认是 UTF-8 无 BOM带 BOM 的文件在某些工具里解析失败我遇到最多的情况是目录路径不对。不同工具、不同版本对 skills 目录的约定不一样最稳妥的方法是查官方文档或者用工具的调试模式看它到底在哪个路径下找 skills。Claude Code 可以用--debug参数启动它会打印出加载了哪些 skill 文件。5.2 AI 加载了 skill 但输出还是不对这种情况通常不是 skill 没生效而是 skill 内容本身有问题。我总结了几种典型情况第一种是步骤写得太抽象。比如你写“请遵循项目规范”AI 根本不知道你的规范是什么。必须写成“使用 2 空格缩进”“导入语句按字母序排列”“每个函数必须写 JSDoc 注释”这种可执行的具体指令。第二种是模板和约束冲突。比如你的代码模板里用了any类型但约束里写“不要使用 any”AI 就会困惑输出可能随机偏向某一边。写完之后一定要自己通读一遍确保模板和约束一致。第三种是信息过载。前面提过skill 文件太长会导致 AI 抓不住重点。如果你发现 AI 只遵守了 skill 里的一部分规则大概率是文件太长了。试着把次要内容删掉只保留最核心的流程和约束。5.3 多个 skill 之间冲突怎么处理当两个 skill 对同一件事有不同要求时AI 的行为会变得不可预测。比如 skill A 说“API 路由放在src/app/api/”skill B 说“API 路由放在src/pages/api/”AI 可能随机选一个也可能两个都不用。解决方法是建立 skill 的优先级体系。在 frontmatter 里加一个priority字段数字越大优先级越高。当冲突发生时AI 会优先遵守高优先级的 skill。同时在低优先级的 skill 里加一行说明“当与xxxskill 冲突时以xxx为准。”更好的做法是从源头避免冲突。写 skill 之前先规划好职责边界确保每个 skill 只负责一个明确的领域不重叠。我们团队的 skills 目录有一个README.md里面画了一张职责矩阵表谁负责什么一目了然。新增 skill 之前先查表避免和已有的重复。5.4 性能问题skills 太多会不会拖慢响应会但影响没有想象中那么大。我实测过20 个 skill 文件总共约 8000 行Claude Code 在加载时的额外耗时大概在 200 到 500 毫秒之间。这个延迟在交互式编程中基本感知不到。真正影响性能的是“加载了太多不相关的 skill”。如果 AI 每次对话都把 20 个 skill 全部拉进上下文那上下文窗口很快就被占满了留给实际代码的空间就少了。所以触发条件的精准度很关键。我建议定期审查 skill 的触发日志如果工具支持的话看看哪些 skill 被频繁误加载然后收窄它们的触发条件。另一个优化技巧是把大 skill 拆成“核心”和“扩展”两部分。核心部分总是加载扩展部分只在特定条件下加载。比如“API 开发”skill 的核心部分只包含基本的路由创建流程扩展部分包含认证、限流、缓存等高级主题。这样大部分简单任务只需要加载核心部分上下文占用少响应也更快。6. 我踩过的坑和总结出的几条硬经验第一个坑是“过度依赖 skills 而忽略对话上下文”。skills 是静态的但项目是动态的。有时候 AI 加载了 skill但当前对话里有一些 skill 里没写的特殊要求AI 会优先遵守 skill 而忽略对话里的指令。我的应对方法是在 skill 里加一条“当用户在当前对话中有明确指令时以用户指令为准。”这条规则救了我好几次。第二个坑是“skill 写得太完美反而限制 AI 发挥”。我早期写 skill 时恨不得把每个细节都规定死结果 AI 变成了一个只会照本宣科的机器遇到 skill 没覆盖的边缘情况就完全不会变通了。后来我学会了在 skill 里留一些“弹性空间”比如写“优先使用 X 方案如果 X 不适用则根据实际情况选择最合适的方案”。这样既保证了规范性又保留了灵活性。第三个坑是“忘记更新 skill”。项目在演进技术栈在升级但 skill 文件还是半年前写的。结果 AI 按照过时的 skill 生成代码引入了已经废弃的 API。我们现在的规定是每次技术栈升级或规范变更必须同步更新相关的 skill 文件并且把这件事写进 checklist 里。skill 文件和代码一样是需要持续维护的资产不是写完就扔的一次性文档。最后一个经验是关于测试的。每个 skill 写完之后我都会设计一组测试用例来验证它的效果。比如“创建 API 端点”这个 skill我会让 AI 连续创建 5 个不同的端点检查每个输出是否符合预期。如果 5 个里有 2 个以上出问题就说明 skill 需要修改。这种“skill 测试”的习惯让我避免了很多“看起来能用实际上坑很多”的情况。提示不要试图一次性写出完美的 skill。先写一个最小可用版本在实际使用中发现问题再迭代。我现在的 20 多个 skill没有一个是一次性写好的都是经过至少 3 轮修改才稳定下来的。