1. 从“skills”这个热词说起：它到底是什么

最近半年，不管是在技术群还是各种开发者社区，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表，能看到claude code、codex、agents、plugin这些词跟skills绑在一起反复出现。很多人第一次看到“skills”会以为是某种新编程语言或者框架，其实不是。它更像是一套给 AI 编程助手用的能力扩展包，你可以把它理解成给一个刚入职的实习生配的“岗位操作手册”——手册里写清楚了遇到什么任务该用什么工具、按什么流程走、输出什么格式。

我最早接触这个概念是在折腾claude code的时候。当时我让它帮我改一个前端项目的构建配置，它给出的方案总是差那么点意思，要么漏掉某个环境变量，要么把vite的配置改得面目全非。后来有人丢给我一个skills包，里面定义了一套针对前端构建的规则和工具调用逻辑，再跑同样的任务，输出质量直接上了一个台阶。从那以后我就意识到，skills这个东西不是锦上添花，而是决定 AI 助手能不能真正干活的关键。

那skills具体解决什么问题？简单说，它解决的是通用 AI 模型在特定领域“不够专业”的问题。一个通用模型可能知道webpack和vite的区别，但它不知道你们团队内部约定的构建产物目录结构、不知道你们用的 CI 流程、不知道你们对tree-shaking的特殊要求。skills就是把这些领域知识、操作流程、工具调用规则打包成一个可复用的模块，让 AI 助手在特定场景下表现得像一个有经验的从业者，而不是一个只会背文档的搜索引擎。

适合谁来了解这个东西？如果你是前端开发、全栈工程师、或者任何在日常工作中使用claude code、codex、cursor这类 AI 编程工具的人，skills能直接提升你的工作效率。如果你是对agents开发感兴趣的工程师，skills的设计思路也值得研究，因为它本质上是一种轻量级的 agent 能力编排方案。哪怕你只是刚装好claude code还在摸索阶段，了解skills也能帮你少走很多弯路。

2. 核心思路拆解：skills 为什么这样设计

2.1 从“提示词工程”到“能力封装”的演进

早期大家用 AI 编程助手，靠的是在对话里写一大段提示词，比如“你是一个资深前端工程师，请按照以下规范帮我改代码……”。这种方式的问题很明显：每次都要重复写，容易漏掉细节，而且不同人写的提示词质量参差不齐。skills的出现，本质上是把这种一次性的提示词工程升级成了可复用、可版本管理的能力封装。

我打个比方。提示词工程就像你每次做饭前临时写一张菜谱，写完就扔；而skills就像你把菜谱整理成一本标准化的烹饪手册，下次直接翻到对应章节就行。手册还可以不断修订、补充新菜式，甚至分享给其他人用。这个演进方向是必然的，因为 AI 助手要真正融入工作流，就不能依赖每个人每次即兴发挥。

从技术实现上看，一个skills包通常包含几个核心部分：触发条件（什么情况下激活这个 skill）、工具定义（可以调用哪些外部工具或 API）、执行流程（按什么步骤完成任务）、输出规范（结果应该长什么样）。这四部分组合起来，就形成了一个闭环的能力单元。

2.2 skills 与 agents、plugin 的关系

热搜词里agents、plugin、skills经常一起出现，很多人搞不清楚它们的区别。我用一个实际场景来解释。假设你要做一个“自动修复前端构建错误”的功能：

• plugin是底层的能力提供者，比如一个能读取构建日志的插件、一个能修改配置文件的插件。
• skills是中间层的编排逻辑，它定义了“先读日志、再定位错误、然后修改配置、最后验证”这个流程。
• agents是上层的自主决策者，它决定什么时候调用哪个skill，以及多个skill之间怎么协作。

所以skills是连接plugin和agents的桥梁。没有skills，agents就像一个有大脑但没有手脚的人；没有agents，skills就像一套工具但没有使用工具的人。理解这个层次关系，对后续自己开发skills非常重要。

2.3 为什么是现在：AI 编程工具爆发的必然结果

claude code、codex、cursor这些工具的普及，让大量开发者开始日常使用 AI 助手写代码。但通用模型的能力边界很快暴露出来：它能写一个排序算法，但搞不定你们公司内部那个用了五年的老构建系统；它能解释React的生命周期，但不知道你们团队对组件命名有特殊约定。skills就是在这个背景下火起来的，它让 AI 助手从“什么都会一点”变成“在特定领域真正能干活”。

我观察到一个趋势：越来越多的团队开始把内部的最佳实践、代码规范、部署流程写成skills包，新入职的工程师装上这些skills，AI 助手就能按照团队标准来辅助工作。这比写文档有效得多，因为文档没人看，但 AI 助手每天都在用。

3. 核心细节解析与实操要点

3.1 一个典型 skills 包的结构长什么样

我拿一个实际的前端开发skills包来拆解。这个包是我自己整理的，用于辅助React项目的日常开发。它的目录结构大致如下：

frontend-dev-skills/ ├── manifest.json ├── skills/ │ ├── component-generator/ │ │ ├── skill.md │ │ ├── templates/ │ │ └── validators/ │ ├── build-fixer/ │ │ ├── skill.md │ │ └── scripts/ │ └── code-reviewer/ │ ├── skill.md │ └── rules/ └── shared/ ├── utils/ └── configs/

manifest.json是整个包的入口文件，定义了包的名称、版本、依赖关系以及包含哪些skill。每个skill目录下的skill.md是这个能力的核心描述文件，里面用自然语言加结构化配置的方式，写清楚了触发条件、执行步骤和输出要求。templates目录放代码模板，validators放校验规则，scripts放可执行的辅助脚本。

注意：不同工具对skills包的结构要求不完全一样。claude code和codex在加载skills时的目录约定有差异，建议先查对应工具的官方文档，别直接照搬。

3.2 skill.md 的编写要点

skill.md是整个skills包最核心的文件。我踩过的坑是：一开始把它写成了纯自然语言的说明文档，结果 AI 助手理解起来很吃力，执行时经常跑偏。后来我总结出一个原则——结构化描述加自然语言补充。

一个高质量的skill.md通常包含以下部分：

• 元信息：skill 名称、版本、作者、适用场景。
• 触发条件：用明确的模式描述什么时候激活这个 skill，比如“当用户提到‘构建失败’或‘build error’时”。
• 前置检查：执行前需要确认哪些条件，比如“确认项目根目录存在package.json”。
• 执行步骤：分步骤描述操作流程，每一步都要说明输入、操作、输出。
• 工具调用：明确列出可以调用的工具及其参数格式。
• 输出规范：定义结果的格式，比如“返回一个 JSON 对象，包含errorType、location、suggestion三个字段”。
• 异常处理：遇到常见错误时怎么处理，比如“如果日志文件不存在，提示用户检查构建命令”。

我实测下来，把执行步骤写得越具体，AI 助手的表现越稳定。比如不要写“检查代码质量”，而要写“运行eslint并解析输出，提取error和warning数量，如果error大于 0 则返回失败”。

3.3 工具调用的参数设计

skills里经常需要调用外部工具，比如执行 shell 命令、读写文件、调用 API。参数设计的好坏直接影响 skill 的可靠性。我的一般原则是：

• 参数名要自解释：用targetFile而不是f，用maxRetries而不是n。
• 提供默认值：对于可选参数，给出合理的默认值，减少调用方的负担。
• 参数校验要前置：在 skill 描述里写清楚参数的类型、范围、必填与否，让 AI 助手在调用前就能发现错误。
• 敏感操作要加确认：比如删除文件、修改生产配置，必须在 skill 里定义确认步骤。

举个例子，一个“自动修复构建错误”的 skill，它的工具调用参数可能是这样的：

{ "tool": "executeCommand", "parameters": { "command": "npm run build", "workingDirectory": "{{projectRoot}}", "timeout": 120000, "captureOutput": true } }

这里的{{projectRoot}}是变量占位符，实际执行时会替换成真实路径。这种设计让 skill 可以在不同项目里复用，而不需要硬编码路径。

4. 实操过程与核心环节实现

4.1 环境准备：安装 claude code 与配置 skills

先说一下claude code的安装。在windows上，我推荐用官方安装包，直接下载后按向导走就行。安装完成后，你需要配置skills的加载路径。默认情况下，claude code会从用户目录下的.claude/skills文件夹读取skills包。你可以把整理好的skills包直接放进去，或者在配置文件里指定自定义路径。

在ubuntu上配置claude code稍微麻烦一点，因为涉及到权限和路径问题。我的做法是：

# 创建 skills 目录 mkdir -p ~/.claude/skills # 把 skills 包复制进去 cp -r /path/to/your-skills/* ~/.claude/skills/ # 确认权限 chmod -R 755 ~/.claude/skills

配置完成后，重启claude code，它应该能自动识别到新的skills。你可以在对话里输入“列出可用的 skills”来验证。

提示：如果你在vscode里使用claude code插件，skills的加载路径可能跟独立客户端不一样。我遇到过插件读不到skills的情况，后来发现需要在插件的设置里手动指定skills目录。

4.2 编写第一个 skill：以“组件生成器”为例

我来演示一个完整的skill编写过程。目标是：当用户说“帮我生成一个 React 组件”时，AI 助手能按照团队规范生成组件文件。

第一步，创建目录结构：

mkdir -p ~/.claude/skills/component-generator/templates touch ~/.claude/skills/component-generator/skill.md

第二步，编写skill.md：

# Component Generator ## 元信息 - 名称: component-generator - 版本: 1.0.0 - 适用场景: 生成 React 函数式组件 ## 触发条件 当用户请求生成新的 React 组件时激活。 ## 前置检查 - 确认项目使用 React 16.8 以上版本 - 确认存在 src/components 目录 ## 执行步骤 1. 从用户输入中提取组件名称，转换为 PascalCase 格式 2. 检查 src/components 下是否已存在同名文件，若存在则提示用户 3. 读取 templates/component.tsx 模板 4. 替换模板中的占位符：{{ComponentName}}、{{ComponentNameLower}} 5. 将生成的文件写入 src/components/{{ComponentName}}/index.tsx 6. 如果项目使用 TypeScript，同时生成 index.ts 类型导出文件 ## 输出规范 返回生成的文件路径列表，以及每个文件的简要说明。 ## 异常处理 - 如果组件名称不符合 PascalCase 规范，自动转换并提示用户 - 如果目录不存在，询问用户是否创建

第三步，准备模板文件templates/component.tsx：

import React from 'react'; interface {{ComponentName}}Props { className?: string; } export const {{ComponentName}}: React.FC<{{ComponentName}}Props> = ({ className }) => { return ( <div className={className}> {{ComponentName}} Component </div> ); };

第四步，测试。重启claude code，输入“帮我生成一个 UserProfile 组件”，观察输出是否符合预期。如果不符合，调整skill.md里的步骤描述，直到稳定为止。

4.3 调试技巧：如何定位 skill 执行失败的原因

skills执行失败是家常便饭，我总结了一套排查流程：

1. 检查触发条件：skill 有没有被正确激活？可以在对话里问 AI 助手“你现在激活了哪些 skill”。
2. 检查前置条件：skill 里定义的前置检查是否通过？比如目录是否存在、依赖是否安装。
3. 检查工具调用：如果 skill 需要调用外部工具，确认工具是否可用、参数是否正确。
4. 检查输出解析：有时候 skill 执行成功了，但输出格式不符合预期，导致后续步骤失败。
5. 查看日志：claude code和codex都有日志输出，可以在设置里打开详细日志，定位具体哪一步出错。

我遇到过一个典型问题：skill 里定义了一个 shell 命令，但在windows上执行失败，因为命令用了linux风格的路径分隔符。后来我在 skill 里加了平台判断逻辑，根据操作系统选择不同的命令格式。

5. 常见问题与排查技巧实录

5.1 skills 加载失败怎么办

这是最常见的问题。表现是：你把skills包放到了指定目录，但 AI 助手就是识别不到。排查思路如下：

我个人的经验是，路径问题占了八成。尤其是在windows上，路径里的反斜杠和空格经常导致解析失败。建议统一用正斜杠，路径里不要有中文和空格。

5.2 skill 执行结果不稳定怎么调

同一个 skill，有时候执行得很好，有时候完全跑偏。这种不稳定性通常来自几个方面：

• 描述模糊：skill.md 里的步骤描述不够具体，AI 助手每次理解都不一样。解决办法是把步骤拆得更细，用明确的动词和参数。
• 上下文干扰：对话历史太长，AI 助手被之前的对话带偏了。可以在 skill 里加一句“忽略之前的对话历史，严格按照本 skill 的步骤执行”。
• 工具返回结果不确定：比如调用了一个 API，返回格式偶尔变化。可以在 skill 里加结果校验和重试逻辑。
• 模型随机性：这是最根本的原因。可以通过降低温度参数、增加示例、明确输出格式来缓解。

我实测下来，给 skill 加示例是最有效的稳定手段。在skill.md里放一两个输入输出的例子，AI 助手模仿示例的准确率会高很多。

5.3 多个 skills 冲突怎么处理

当你装了很多skills，可能会出现冲突：两个 skill 都声称能处理同一类任务，AI 助手不知道该用哪个。我的处理原则是：

• 优先级排序：在manifest.json里给每个 skill 定义优先级，数字越小优先级越高。
• 触发条件互斥：尽量让不同 skill 的触发条件不重叠，比如一个处理“新建组件”，一个处理“修改组件”。
• 显式指定：在对话里直接说“用 component-generator 这个 skill”，避免歧义。
• 合并 skill：如果两个 skill 功能高度重叠，考虑合并成一个，用参数区分不同场景。

注意：不要装太多 skill。我一开始装了二十多个，结果 AI 助手经常选错。后来精简到八个常用的，反而效率更高。

5.4 如何评估一个 skill 好不好用

我一般从四个维度评估：

• 触发准确率：该激活的时候激活了吗？不该激活的时候有没有误触发？
• 执行成功率：按照 skill 的步骤走，能顺利完成任务的概率是多少？
• 输出质量：生成的结果是否符合预期？需不需要人工大量修改？
• 可维护性：skill.md 是否容易理解和修改？加新功能方不方便？

我建议每个 skill 上线前都跑一轮测试，准备十个典型任务，看成功几个。低于七个的，回去改 skill.md。

6. 进阶玩法：把 skills 用出花来

6.1 组合多个 skill 完成复杂任务

单个 skill 能做的事有限，但多个 skill 组合起来，能完成相当复杂的任务。比如“自动修复构建错误并提交 PR”这个流程，可以拆成三个 skill：

1. build-error-analyzer：分析构建日志，定位错误。
2. code-fixer：根据错误类型，修改对应代码。
3. pr-creator：创建分支、提交代码、发起 PR。

在agents层面，定义一个工作流，按顺序调用这三个 skill。这样每个 skill 保持简单和专注，组合起来又能完成复杂任务。这种设计思路跟微服务架构很像，每个服务只做一件事，但通过编排能完成复杂业务。

6.2 让 skill 具备学习能力

skills本身是静态的，但你可以设计一些机制让它“学习”。我的做法是在 skill 执行后收集反馈，把成功的案例和失败的案例分别记录下来，定期分析失败原因，然后更新skill.md。这本质上是一个人工反馈循环，虽然不如自动学习那么酷，但实际效果很好。

具体操作上，我会在 skill 里加一个“记录执行结果”的步骤，把每次执行的输入、输出、是否成功写到一个日志文件里。每周花半小时看看日志，找出高频失败模式，针对性优化。

6.3 团队协作中的 skills 管理

如果你在团队里推广skills，管理就成了问题。我的建议是：

• 统一仓库：把所有skills放在一个 Git 仓库里，统一版本管理。
• 命名规范：用团队名-功能名的格式，比如frontend-component-generator。
• 文档齐全：每个 skill 都要有 README，说明用途、用法、维护人。
• 定期评审：每月评审一次，清理不再使用的 skill，更新过时的 skill。
• 权限控制：涉及敏感操作的 skill，限制只有特定人员能修改。

我们团队现在有三十多个skills，覆盖前端、后端、运维、测试各个领域。新入职的工程师第一天就装上这些skills，AI 助手直接按照团队标准辅助工作，上手速度比以前快了一倍不止。

6.4 从 skills 到 agents：下一步怎么走

当你积累了一定数量的skills，自然会想更进一步：让 AI 助手自主决定什么时候用什么 skill。这就是agents的范畴。我目前的做法是定义一个“调度 agent”，它的职责是分析用户请求，然后从可用 skill 列表里选择最合适的组合。

这个调度 agent 的核心逻辑是：意图识别加 skill 匹配。用户说“帮我修一下构建”，调度 agent 识别出意图是“修复构建错误”，然后匹配到build-error-analyzer和code-fixer两个 skill，按顺序执行。如果执行失败，调度 agent 还可以尝试其他 skill 组合。

这个方向还在早期，但我已经看到一些团队在做类似的事情。langchain deep agents这类框架也在探索这个方向。如果你对agents开发感兴趣，从skills入手是个很好的起点，因为skills的边界清晰、易于测试，适合作为构建复杂 agent 系统的第一步。

7. 我踩过的坑和总结的经验

说几个我实际踩过的坑，希望能帮你省点时间。

第一个坑是贪多。我一开始看到skills觉得什么都能做，一口气写了二十多个，结果 AI 助手经常选错，反而降低了效率。后来精简到八个核心 skill，每个都打磨得很稳定，整体效率反而提升了。所以我的建议是：先做三个最常用的，用顺了再扩展。

第二个坑是描述太抽象。我早期写的skill.md喜欢用“优化代码质量”这种模糊表述，结果 AI 助手每次理解都不一样。后来改成“运行 eslint，如果 error 数量大于 0，逐条修复”，执行就稳定多了。skill 描述要像给新人写操作手册，具体到每一步做什么、用什么工具、输出什么格式。

第三个坑是忽略平台差异。我在mac上写好的 skill，拿到windows上跑就出问题，因为路径分隔符和命令不一样。后来我在 skill 里加了平台判断，或者干脆用跨平台的工具和写法。如果你团队里有人用windows有人用mac，这一点一定要提前考虑。

第四个坑是不做版本管理。我早期直接改skill.md，改坏了想回滚都回不去。后来把所有skills放进 Git 仓库，每次修改都提交，出问题随时回滚。这个习惯强烈建议你从一开始就养成。

最后一个经验是：skills 的价值在于持续迭代。不要指望一次写出完美的 skill，而是在使用中不断发现问题、优化描述、补充示例。我现在的核心 skill 都迭代了十几版，每一版都比上一版更稳定、更高效。这个过程本身就是对团队工作流程的一次梳理和优化，收获远不止 AI 助手变好用这么简单。