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. 实操：从零开始搭建你的第一个 skill

3.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 -- --testPathPattern=api` 验证

第三步，给代码模板。这是最关键的部分，直接决定输出质量：

// 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 -- --testPathPattern=api` 确保测试通过 - 检查生成的 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 组合出 superpower

4.1 多 skill 协同工作的机制

单个 skill 解决单点问题，但实际开发中一个任务往往涉及多个领域。比如“给现有 API 添加一个新的查询参数并更新前端调用”，这就同时涉及 API 修改、类型定义更新、前端组件调整、测试更新。如果每个领域都有一个 skill，AI 能不能同时加载多个？

答案是能，但需要一些技巧。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 目录的约定不一样，最稳妥的方法是查官方文档，或者用工具的调试模式看它到底在哪个路径下找 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 轮修改才稳定下来的。