1. 从“skills”这个标题说起：它到底指什么
第一次看到“skills”这个标题，很多人会以为是某个招聘网站上的技能标签，或者是一份简历里的能力清单。但结合热搜词里反复出现的 Claude Code、Codex、agents、plugin 这些词，就能判断出这里说的 skills 不是泛指“技能”，而是特指 AI 编程助手生态里的Agent Skills——一种把可复用的操作流程、领域知识、工具调用方式打包成模块，让 AI 代理在特定任务上表现更稳定的机制。
简单说，skills 就是给 AI 代理准备的“操作手册 + 工具箱”。你告诉它遇到某类任务时该按什么步骤走、该调用哪些工具、该注意哪些边界条件，它就能从“什么都能聊两句但什么都不精”变成“在这个具体场景里靠谱得像个老手”。这解决了大模型在实际工程中最大的痛点：通用能力很强，但落到具体项目、具体框架、具体规范上，经常答非所问、步骤跳步、参数写错。
这篇文章适合几类人看：一是已经在用 Claude Code 或 Codex 做日常开发，想进一步提升效率的工程师；二是正在搭建内部 AI 代理平台，需要设计 skills 体系的技术负责人；三是对 agent 生态感兴趣，想搞清楚 skills、plugin、agents 之间关系的技术爱好者。我会从设计思路、核心细节、实操过程、常见问题四个维度展开，尽量把每个“为什么”讲透，让你看完能直接上手复现。
2. 内容整体设计与思路拆解
2.1 为什么是 skills，而不是 prompt 或 plugin
很多人第一反应是：我直接写一段 system prompt 不就行了，为什么要搞 skills 这么一层？这个问题我在实际项目里被问过不下十次。答案在于复用粒度和触发时机。
Prompt 是每次对话都要重新注入的，写长了占上下文，写短了覆盖不全，而且它和具体任务绑定太松——你没法让 AI 在“写 React 组件”和“排查 Gradle 构建失败”这两个场景下自动切换到不同的 prompt。Plugin 则是更底层的扩展，通常涉及进程、网络、文件系统权限，开发和维护成本高，适合做通用能力（比如读文件、跑命令），但不适合承载“我们团队 React 组件必须用 function component + hooks，样式用 CSS Modules，测试用 Vitest”这种业务规范。
Skills 正好卡在中间：它比 prompt 结构化，比 plugin 轻量。一个 skill 通常包含元信息（名称、描述、触发条件）、指令正文（步骤、约束、示例）、可选资源（脚本、模板、参考文档）。AI 代理在运行时根据当前任务匹配 skill 描述，命中后把指令正文加载进上下文，任务结束就释放。这样既保证了专业性，又不会长期占用上下文窗口。
2.2 三种主流形态：Claude Code Skills、Codex Skills、通用 Agent Skills
从热搜词看，大家关注的主要是三类。Claude Code 的 skills 体系比较成熟，官方市场里有大量现成 skill 可以直接装，也支持本地自定义。Codex 这边的 skills 更偏向于和代码仓库结合，强调在具体项目里沉淀可复用的操作流程。通用 Agent Skills 则是一个更抽象的概念，LangChain Deep Agents 这类框架也在推类似的机制，核心思想都是“把领域知识从模型权重里解耦出来，变成可版本管理的资产”。
我个人的选型建议是：如果你主力用 Claude Code，优先走官方 skill 市场 + 本地覆盖的方式，上手最快；如果你团队用 Codex 做代码审查和重构，建议把 skills 和仓库的 CONTRIBUTING.md 放在一起维护，让规范和 skill 同步更新；如果你在自研 agent 平台，参考 Claude Agent Skills 的第一性原理设计——描述匹配、按需加载、资源隔离——这三条是绕不开的。
2.3 一个 skill 的目录结构长什么样
以 Claude Code 的 skill 为例，典型结构是这样的：
my-skill/ SKILL.md # 必需，元信息 + 指令正文 scripts/ # 可选，辅助脚本 setup.sh references/ # 可选，参考文档 api-spec.md assets/ # 可选，模板、配置片段 template.tsxSKILL.md 的头部是 YAML frontmatter，至少包含 name 和 description。description 非常关键，它决定了这个 skill 什么时候被触发。写得太宽泛，比如“帮助写代码”，那几乎每个任务都会命中，反而干扰；写得太窄，又可能永远匹配不上。我的经验是 description 里要包含动作 + 对象 + 场景三要素，比如“当用户需要在 React 项目里新增一个表单组件，且项目使用 React Hook Form 做校验时，按本 skill 的步骤生成代码”。
3. 核心细节解析与实操要点
3.1 SKILL.md 的写法：把“老手直觉”翻译成步骤
写 skill 最难的地方不是技术，而是把你脑子里那些“不用说也知道”的直觉显式化。比如一个资深前端在新建组件时会自动做这几件事：确认目录结构、检查是否已有类似组件、选样式方案、写类型定义、补测试、更新导出索引。这些对你来说是肌肉记忆，但对 AI 来说必须一条条写出来。
我通常按这个模板来组织指令正文：
- 前置检查：动手前先确认哪些条件。比如“先读 package.json，确认 react-hook-form 版本是否 >= 7”。
- 执行步骤：编号列出，每步说明输入、输出、使用的工具。比如“用 Read 工具读取 src/components 目录，列出已有组件名”。
- 约束与禁忌：明确不能做什么。比如“不要新建 index.ts 以外的导出文件”“不要用 any 类型”。
- 示例：给一个最小可运行示例，让 AI 有参照。
- 验证方式：怎么确认做对了。比如“运行 pnpm test src/components/NewForm.test.tsx，全部通过才算完成”。
注意：步骤不要写得太抽象。“合理组织代码”这种话等于没说，“在 src/components/ 下新建 PascalCase 命名的目录，目录内放 index.tsx 和 index.test.tsx”才是可执行的。
3.2 description 的匹配逻辑与调优
不同平台的匹配机制略有差异，但大体上都是把用户当前请求和 skill 的 description 做语义相似度比较，超过阈值就加载。Claude Code 还会考虑 skill 的优先级和互斥关系。实测下来，description 里堆关键词效果并不好，反而是一句自然语言描述匹配得更准。
我踩过的一个坑是：早期我把 description 写成“React 组件开发”，结果连“帮我看看这个 React 报错”也会触发，加载了一堆用不上的步骤，浪费上下文。后来改成“在已有 React 项目中新增一个使用 React Hook Form 的表单组件”，误触发率明显下降。另一个技巧是给 skill 加when_to_use字段（如果平台支持），用更口语化的例子补充说明，比如“当用户说‘加个登录表单’‘新建一个注册页’时使用”。
3.3 资源文件的组织：脚本、模板、参考文档怎么放
scripts 目录适合放那些确定性高、不需要 AI 推理的操作。比如初始化目录结构、生成样板代码、跑 lint 修复。把这些写成 shell 或 node 脚本，skill 正文里直接让 AI 调用，比让 AI 一步步敲命令更稳。
references 目录放的是“查阅型”内容，比如内部 API 规范、设计系统 token 列表、常见错误码对照表。这些内容通常很长，不适合全量塞进上下文，而是让 AI 在需要时用 Read 工具按需读取。assets 目录放模板文件，比如组件模板、测试模板、配置文件模板，AI 可以直接复制修改。
提示：资源文件命名要见名知意，避免
file1.md、temp.tsx这种。AI 在匹配资源时也会参考文件名，好的命名能提升加载准确率。
3.4 版本管理与团队协作
Skills 是资产，资产就要版本管理。我建议把团队共用的 skills 放在独立仓库，通过 submodule 或包管理工具引入到各个项目。每次修改 skill 都要走 PR 流程，因为一个错误的步骤可能影响所有使用该 skill 的成员。Claude Code 官方市场的 skill 可以 fork 到内部仓库再改，不要直接依赖线上版本，否则上游更新可能引入不兼容变更。
另外，skill 的 description 和正文要同步更新。我见过有人改了步骤但忘了改 description，结果触发条件还是旧的，新步骤永远加载不到。建议在 CI 里加一个检查：如果 SKILL.md 的正文有变更，description 也必须变更，否则告警。
4. 实操过程与核心环节实现
4.1 环境准备：Claude Code 与 Codex 的安装配置
先讲 Claude Code 的安装。Windows 用户建议用 WSL2，原生 Windows 下路径和权限问题比较多。安装方式按官方文档走即可，装完后用claude --version确认。国内网络环境下，如果遇到登录或市场加载问题，优先检查系统代理设置是否影响了 CLI 工具，必要时在终端里单独配置。VS Code 用户装 Claude Code 扩展后，可以在设置里指定 CLI 路径，避免扩展找不到命令。
Codex 的安装类似，但 Codex 更依赖项目本地的配置文件。装完后在项目根目录建.codex/目录，skills 放在.codex/skills/下。Codex 登录后如果提示“无法加载组织设置”，通常是配置文件里的 org 字段和实际账号不匹配，检查~/.codex/config.json即可。
注意：安装过程中如果遇到
qt.qpa.plugin: could not find the qt platform plugin "windows"这类报错，说明某个 GUI 依赖缺失，和 skills 本身无关，装对应的运行库即可。不要在这个问题上浪费太多时间。
4.2 从零写一个“新增 React 表单组件”skill
假设我们要写一个 skill，让 AI 在指定项目里新增表单组件。第一步建目录：
mkdir -p .claude/skills/new-form-component/{scripts,references,assets}第二步写 SKILL.md：
--- name: new-form-component description: 当用户需要在 React 项目里新增一个使用 React Hook Form 做校验的表单组件时使用 --- ## 前置检查 1. 读取 package.json，确认 react-hook-form 版本 >= 7.0.0 2. 读取 src/components 目录，确认没有同名组件 ## 执行步骤 1. 在 src/components/ 下新建 PascalCase 目录，名称为组件名 2. 复制 assets/FormTemplate.tsx 到该目录，重命名为 index.tsx 3. 替换模板中的 __COMPONENT_NAME__ 为实际组件名 4. 复制 assets/FormTestTemplate.tsx 为 index.test.tsx，同样替换占位符 5. 在 src/components/index.ts 中追加导出 ## 约束 - 不要使用 any 类型 - 样式统一用 CSS Modules，文件名 index.module.css - 测试用 Vitest + Testing Library ## 验证 运行 pnpm test src/components/<组件名>，全部通过第三步准备模板文件。FormTemplate.tsx 里用__COMPONENT_NAME__占位，AI 替换后即可使用。模板要尽量完整，包含 imports、类型定义、组件主体、导出，减少 AI 自由发挥的空间。
4.3 测试 skill 是否生效
写完 skill 后，在 Claude Code 里输入“帮我加一个登录表单组件”，观察它是否加载了 new-form-component。如果没加载，检查 description 是否匹配、skill 目录是否在正确位置、SKILL.md 的 frontmatter 格式是否正确。如果加载了但步骤没执行，检查正文里的工具调用是否被平台支持，比如某些平台不支持直接跑 shell 脚本，需要改成让 AI 用 Bash 工具执行。
我一般会准备一组测试用例：正向用例（明确匹配）、负向用例（不该匹配的）、边界用例（模糊描述）。每次改完 skill 都跑一遍，确保触发行为符合预期。这个习惯帮我避免了好几次“改了 A 场景结果 B 场景挂了”的事故。
4.4 参数计算与选择：上下文预算怎么分配
Skills 会占用上下文窗口，所以要有预算意识。一个 skill 的正文建议控制在 500 到 1500 字，超过 2000 字就要考虑拆分或把细节移到 references 里按需加载。假设模型上下文是 200K token，系统提示和对话历史占 50K，那 skills 总占用最好不超过 30K，留足空间给代码和工具输出。
如果同时命中多个 skill，平台通常会按优先级排序加载。我的做法是给核心 skill 设高优先级，辅助 skill 设低优先级，并在 description 里写清楚互斥关系，比如“本 skill 与 legacy-form-skill 互斥，优先使用本 skill”。
5. 常见问题与排查技巧实录
5.1 skill 不触发或误触发
这是最高频的问题。排查顺序如下：先看 description 是否包含用户请求里的核心词；再看 skill 目录层级是否正确，Claude Code 要求放在.claude/skills/下，Codex 要求放在.codex/skills/下；然后看 frontmatter 是否有语法错误，YAML 对缩进敏感，一个 tab 就能让整个文件解析失败。
误触发的话，把 description 写得更具体，加上限定条件。比如“在 React 项目里”比“在项目里”好，“使用 React Hook Form”比“使用表单库”好。还可以在正文开头加一句“如果项目未使用 React Hook Form，请忽略本 skill”，给 AI 一个退出条件。
5.2 加载了 skill 但步骤执行不完整
常见原因是步骤太抽象，AI 自由发挥时跳步。解决办法是把每步的输入输出写死，并加上验证点。比如“读取 package.json 后，输出 react-hook-form 的版本号，如果低于 7.0.0 则停止并告知用户”。另一个原因是上下文被截断，skill 正文太长导致后半部分没加载。这时候要精简正文，把非核心内容移到 references。
5.3 脚本执行权限与路径问题
scripts 目录里的脚本在 Windows 下可能因为没有执行权限而失败。建议在 skill 正文里让 AI 用bash scripts/setup.sh显式调用，而不是直接./scripts/setup.sh。路径统一用相对于项目根目录的写法，避免绝对路径导致换机器就挂。
5.4 团队协作中的 skill 冲突
两个人写了功能重叠的 skill，同时命中时行为不可预测。解决办法是建立 skill 注册表，每个 skill 登记名称、负责人、适用范围、优先级。新 skill 上线前检查是否与已有 skill 重叠，重叠的话合并或明确互斥。我们团队用了一个简单的 Markdown 表格维护这个注册表，放在仓库根目录，PR 时强制更新。
| 问题现象 | 可能原因 | 排查方法 | 解决方式 |
|---|---|---|---|
| skill 不触发 | description 不匹配 | 对比用户请求和 description 关键词 | 改写 description，增加场景限定 |
| skill 误触发 | description 太宽泛 | 用负向用例测试 | 加限定条件或互斥声明 |
| 步骤跳步 | 正文太抽象 | 检查每步是否有明确输入输出 | 细化步骤，加验证点 |
| 脚本失败 | 权限或路径问题 | 手动执行脚本看报错 | 用 bash 显式调用，统一相对路径 |
| 上下文截断 | 正文过长 | 看加载日志 | 精简正文，细节移到 references |
| 多 skill 冲突 | 功能重叠 | 检查注册表 | 合并或设优先级 |
提示：每次平台大版本更新后，重新跑一遍 skill 测试用例。平台可能调整匹配算法或工具接口，旧 skill 不一定兼容。
6. 进阶玩法：把 skills 和 agents、plugin 串起来
6.1 skills 与 agents 的分工
Agent 负责决策“做什么”，skill 负责指导“怎么做”。一个 agent 可以挂载多个 skill，根据任务动态加载。比如一个“前端开发 agent”可以挂 new-form-component、new-page、fix-lint 三个 skill，用户说“加个表单”就加载第一个，说“修一下 lint”就加载第三个。这样 agent 的职责清晰，skill 的复用性也高。
LangChain Deep Agents 这类框架里，agent 和 skill 的绑定关系通常在配置里声明。我建议按领域划分 agent，按任务划分 skill，避免一个 agent 挂几十个 skill 导致匹配混乱。
6.2 skills 与 plugin 的边界
Plugin 提供底层能力，比如文件读写、网络请求、数据库连接；skill 提供上层流程，比如“新增组件时先读目录再写文件再跑测试”。两者配合的方式是：skill 正文里调用 plugin 提供的工具。比如 skill 说“用 Read 工具读取 package.json”，Read 就是 plugin 提供的能力。
判断一个功能该做成 plugin 还是 skill，看它是否需要跨任务复用。文件读写、命令执行这种每个任务都可能用到的，做成 plugin；业务规范、操作流程这种特定任务才用的，做成 skill。
6.3 用 skills 做代码审查与规范落地
除了生成代码，skills 还能用于审查。写一个 code-review skill，正文里列出团队的审查清单：命名规范、类型完整性、测试覆盖、性能隐患、安全边界。AI 在 review 时加载这个 skill，就会按清单逐条检查，而不是泛泛地说“代码看起来不错”。
这个玩法在我们团队效果很好。以前 code review 靠人肉记规范，新人经常漏项；现在 AI 先跑一遍 skill，把明显问题标出来，人只需要看 AI 拿不准的部分。效率提升明显，规范落地也更彻底。
6.4 持续迭代：从使用日志里找改进点
Skills 不是写完就完了。我建议定期看使用日志，统计每个 skill 的触发次数、任务成功率、用户反馈。触发少但任务重要的 skill，可能是 description 没写好；触发多但成功率低的 skill，可能是步骤有问题。根据数据迭代，比拍脑袋改有效得多。
另外，把用户经常手动纠正 AI 的地方记下来，这些就是 skill 该补充的约束。比如用户反复说“不要用 default export”，那就在 skill 约束里加上这一条。日积月累，skill 会越来越贴合团队的实际习惯。
我个人在实际操作中的体会是，skills 的价值不在于写得多，而在于写得准。一个描述精准、步骤清晰的 skill，比十个泛泛而谈的 skill 有用得多。刚开始可以从一两个高频任务入手，跑通流程后再逐步扩展。踩过几次坑之后你会发现，最难的不是技术实现，而是把团队里那些“只可意会”的经验变成可执行的文字。这件事值得花时间做，因为一旦沉淀下来，就是团队长期受益的资产。
