如果你最近在刷前端开发或者 AI 编程相关的内容，大概率会频繁看到“skills”这个词。它在 VS Code 世界里被翻译成“技能”，最早是 Claude Code 这类 AI 编程助手带起来的概念，后来 Codex、Cline 这些工具也都跟进了。很多视频里看起来很神奇：让 AI 在编辑器里一键生成组件、按团队规范 review 代码、自动跑项目脚手架，其实背后靠的就是一套可复用的“技能”。
说直白点，skills 就是“给 AI 编程助手的一份岗位说明书 + 工具箱”。以前你让 AI 干活，是“你问一句，它答一句”，每次都得重新交代上下文；有了 skills 之后，AI 会根据任务描述自动加载对应的说明书，按里面的流程去执行，甚至调用你准备好的脚本。这篇文章就围绕“VS Code 怎么使用 skills”展开，从概念、安装、手写实践到常见坑，一次讲透。
1. Skills是什么，为什么VS Code用户都在聊
1.1 先分清：VS Code 本身不提供 Skills
很多人第一次听到“VS Code 使用 skills”，下意识以为是编辑器更新了某个菜单，其实不是。VS Code 只是一个编辑器外壳，skills 能力来自你安装的 AI 编程扩展，比如 Claude Code for VS Code、Cline、Continue，以及 OpenAI Codex 的命令行工具。
你可以把 VS Code 理解成一个“插座”，AI 扩展就是插上去的电器。skills 是电器里的一个功能按钮，但插座本身不生产功能。所以第一步不是打开 VS Code 设置，而是确定你用的是哪一款支持 skills 的 AI 插件。不同插件对 skills 的目录要求和触发方式有差异，但底层思路是一致的：AI 在对话到来时，会先把项目里的指令文件读进上下文，再决定怎么干活。
1.2 从临时提示词到可复用技能
早些年用 AI 编程，大家习惯把“提示词”写得又臭又长。今天让 AI 生成一个 React 组件，要把组件规范、样式方案、目录位置、命名规则全塞进对话里；明天换个人换个项目，又得重新写一遍。这种模式有两个问题：一是提示词没沉淀，二是一旦角色变了（比如从写代码变成写测试），AI 很容易被历史对话带偏。
skills 解决的正是这两个问题。它把“一类任务的标准操作流程”固化成文件，放在项目目录或用户目录里。AI 遇到匹配的任务时，会自动把这些文件加载进上下文。比如你写一个“生成单元测试”的 skill，里面定义好测试框架、文件命名、断言风格，此后每次让 AI 写测试，它都会自动遵守这套规则。
用生活里的例子来类比：临时提示词是“今天随便做一顿饭”，结果是看冰箱里有什么就炒什么；skills 是“照着菜谱做”，菜谱上写明了食材、调料、下锅顺序和出锅标准。做饭的水平不一定高，但稳定性和可复现性会好很多。
1.3 一个 Skill 的最小结构
虽然各家有细微差别，但一个标准 skill 的最小结构通常是这样的：
SKILL.md：技能说明文件，里面包含元信息（名字、描述、触发条件）和正文指令；scripts/目录：可选，存放辅助脚本，AI 在技能执行时可以调用这些脚本。
SKILL.md开头通常有 YAML frontmatter。以 Claude 系的 skills 为例，长这样：
--- name: python-script-generator description: 当用户要求“创建一个 Python 脚本”“写个脚本模板”时使用。生成带参数解析和日志输出的脚本骨架。 --- # Python 脚本骨架生成 执行步骤： 1. 先询问脚本用途，确认输入参数。 2. 生成 `main()` 函数，使用 `argparse` 解析参数。 3. 添加 `logging` 配置，日志默认输出到控制台。 4. 代码文件放到 `scripts/` 目录，命名与功能相关。这里最容易被新手忽略的是description字段。它不是给人看的，是给 AI 看的。AI 判断“用户当前任务是否匹配这个 skill”，主要靠的就是description里的关键词。写得太抽象，AI 识别不到；写得太具体，只覆盖一条路径，适用性又差。
2. VS Code里引入Skills的几种方式
2.1 先把“能用Skills”的AI助手装好
目前我在日常工作中常用的、且对 skills 支持比较完整的有这么几类：
- Claude Code for VS Code：Anthropic 官方的 VS Code 扩展，和 CLI 版共享 skills 机制。需要在 VS Code 扩展市场搜“Claude Code for VS Code”安装，然后在编辑器里登录账号。它是把 Claude Code 的终端能力嵌进 VS Code 侧边栏，启动后就是一套完整的 agent 对话环境。
- Cline：开源 AI 编程扩展，支持接入 Claude、DeepSeek、Qwen 等多种模型。Cline 提供了自己的规则文件和技能机制，体验上更像“VS Code 原生 AI 助手”。
- Codex CLI：OpenAI 出的命令行 AI 工具，也可以在 VS Code 集成终端里跑。它同样支持 skills，目录默认放在
~/.codex/skills或项目的.codex/skills里。 - Continue：偏对话补全的插件，对 skills 的“自动加载”能力弱一些，但也能通过规则文件约束行为。
如果你不想折腾，我建议从 Cline 开始，因为它对模型没有强绑定，VS Code 里安装扩展后就能用，而且配置界面比纯命令行友好很多。
2.2 项目级和用户级目录怎么放
Skills 可以放在两个层级：
- 用户级（全局）：所有项目都能用。例如
~/.claude/skills/、~/.codex/skills/。适合放通用技能，比如“代码审查”“提交信息生成”“重构辅助”。 - 项目级：只对当前项目生效。一般放在项目根目录的
.claude/skills/或.codex/skills/。适合放团队规范相关的技能，比如“按公司的 React 目录结构生成组件”“对接团队内部的接口文档”。
项目级优先于用户级。如果你在两个层级都定义了同名的 skill，AI 会优先加载项目级的那份。这个设计跟.gitignore的覆盖逻辑很类似：越靠近项目根的配置，优先级越高。
2.3 第三方技能包与市场怎么选
随着 skills 概念走红，社区里出现了不少“技能市场”，把别人写好的技能直接下载到本地。常见的来源有三类：
- 官方市场：Claude 的官方 skill 市场。特点是规范统一、更新及时，但数量不多，方向偏通用。
- GitHub 开源仓库：比如热词里提到的 Superpowers 技能包，就是一堆 SKILL.md 的集合。好处是能直接看到源码，方便改造成自己的；坏处是质量参差不齐，有的技能会写很长的上下文，盲目装太多会挤占上下文窗口。
- 扩展内置市场：Cline 这类扩展自带一个 skills 浏览界面，可以按类目搜索，安装后自动放到本地 skills 目录。
我的建议是：除非是官方或者长期维护的开源项目，否则不装“全家桶”。技能越多，AI 每次判断匹配时要扫描的内容就越多，反而拖慢响应，甚至出现“明明该用技能 A 却调用了技能 B”的乌龙。
2.4 各家AI助手对Skills的支持差异
我整理了一张表，是我自己实测下来比较直观的对比：
| 助手 | 默认技能目录 | 自动加载触达 | 是否支持脚本调用 | 适合场景 |
|---|---|---|---|---|
| Claude Code | ~/.claude/skills、.claude/skills | 强，描述命中即可触发 | 支持，可执行 scripts 下文件 | 深度 agent 类任务 |
| Codex CLI | ~/.codex/skills、.codex/skills | 较强，依赖 description 匹配 | 支持 | 命令行/脚本类任务 |
| Cline | 项目.clinerules+ 自定义技能目录 | 较强，规则文件常驻上下文 | 支持 | VS Code 内日常开发 |
| Continue | 配置文件中的规则 | 较弱，多靠手动引入 | 部分支持 | 补全和轻量对话 |
表格里有一个容易误解的点：Claude Code 的 skills 是“按需加载”，描述匹配到才加载，不会常驻上下文；Cline 的规则文件更像“常驻记忆”，每次对话都会带上一部分。两者适合的应用形态不同，不是简单的谁更强。
3. 手写一个可复用的Skills：从需求到落地
3.1 需求拆解：我要AI干什么
这一节我拿一个很常见的需求来做演示：团队里经常要新建 Python 命令行工具，每次都要搭一遍argparse+logging+ 主函数入口。新人可能写出来样式五花八门，老手又觉得重复劳动很烦。
于是目标很明确：写一个 skill，让 AI 看到“创建一个 Python 脚本”时，自动生成符合团队规范的脚本骨架。注意，这不是“写一段代码”，而是“按既定步骤生成代码”。所以 skill 的内容里必须包含步骤和约束。
3.2 编写SKILL.md的frontmatter
新建目录.claude/skills/python-tool/，在里面创建SKILL.md。开头的 frontmatter 是关键：
--- name: python-tool description: 创建 Python 命令行工具脚本时使用。触发词包括“创建脚本”“新建 python 工具”“生成命令行程序”。输出带参数解析、日志、主函数入口的代码骨架。 ---描述里我特意写了几个不同的触发说法。这不是凑字数，而是因为 AI 是靠语义匹配，不是靠关键词查表。用户说“帮我写一个小工具”也可能匹配到，只要description里有“工具”“python”等语义点。
3.3 编写Skill正文与辅助脚本
正文部分要写清楚执行流程。我会写得很“死板”，因为 AI 喜欢明确的步骤：
# Python 命令行工具骨架生成 ## 执行步骤 1. 向用户确认脚本用途和需要接收的参数，参数默认由命令行传入。 2. 生成文件到项目根目录下 `scripts/` 文件夹，文件名使用 snake_case。 3. 文件结构固定为： - `main()` 函数作为唯一入口； - `argparse.ArgumentParser` 解析参数； - `logging` 输出日志，日志级别可从参数 `--verbose` 控制。 4. 生成后向用户说明文件路径和运行示例，不要自动执行脚本。 ## 约束 - 不创建虚拟环境，不安装第三方依赖。 - 不生成测试文件，除非用户明确要求。 - 不修改 `scripts/` 目录之外的其他文件。这些约束非常重要。没有约束的 skill 会让 AI 发挥过度，比如顺手帮你建了虚拟环境、装了依赖，结果环境一塌糊涂。写约束就像给实习生交代“哪些事绝对不能碰”，它会极大减少 AI 的“自作主张”。
如果你想让它更强大，可以在同目录下放一个scripts/子目录，里面写一个parse_args.py模板之类的辅助文件。AI 在生成代码时，会去读取这些辅助文件作为参考。
3.4 调试与触发的完整流程
写完 skill 后，怎么确认它能被触发？我的调试习惯是分三步：
- 用明确描述触发：在 AI 对话里输入“帮我创建一个 Python 脚本，参数是输入输出路径”。如果 AI 生成的代码遵循了 skill 里的命名约束，说明它已经加载了这份文件。
- 用模糊描述触发：输入“写个小工具”，看它是否还按 skill 来。如果没触发，不是 skill 的问题，而是
description里的语义点不够，需要补充相关词语。 - 检查加载日志：Claude Code 在对话详情里能看到 skill 的加载记录；Cline 则在输出面板里打印提示。如果看不到，说明 skill 目录没放对，或者文件名写错了。
我踩过一个很蠢的坑：把SKILL.md的文件名写成了skill.md。Linux 环境大小写敏感，AI 一直没扫到。这类目录和文件名问题，比逻辑问题隐蔽得多，排查时优先检查命名和路径。
4. 前端开发常用Skills方向与Superpowers实战
4.1 适合前端团队沉淀的三类技能
如果你只看别人炫技，可能觉得 skills 很玄。落到前端开发上，我目前推荐从这三个方向开始沉淀：
组件生成团队如果有一套自己的组件库，写组件时差的就是“按现有设计系统的风格生成代码”。把这个需求固化成 skill：描述里写上组件库名称、CSS 方案、目录位置、Props 命名规范。此后 AI 生成组件不再是你一句句喂规则，而是自动遵守。
组件测试这个和组件生成是一对。测试 skill 里定义好测试框架（Vitest 还是 Jest）、mock 风格、断言写法、覆盖范围。很多前端项目测覆盖率极低，不是大家不会写，而是要查半天现有测试长什么样。skill 把“参考模板”写死，生成测试时会稳定很多。
变更检查与提交信息这类 skill 更像“代码审查助手”。它指导 AI 先看git diff，再结合项目现有约定给出变更建议和规范的 commit message。对于多人协作的项目效果立竿见影，因为 commit message 的名字风格终于能统一了。
4.2 使用开源技能包（Superpowers）的正确姿势
搜索热词里频繁出现 Superpowers，这是一套社区开源的项目，把大量 skill 按场景分类打包，比如“研究规划”“代码调试”“文档编写”等。很多人把它当成“AI 技能全家桶”直接下载，结果一个项目塞了几十个 skill，AI 每次都要做大量匹配，体验直线下降。
正确姿势是：只挑和当前工作流强相关的技能，放进用户级目录，用了一段时间后再删掉不常用的。我在项目中只保留了“调试会话”“变更影响分析”“需求澄清”这三个，其他全部禁掉。保留太多技能，就像工具箱里什么扳手都有，但你要的是找扳手的速度，不是扳手的数量。
另外，开源技能包的内容最好通读一遍。有些技能是作者根据自己项目局写的，里面的目录结构、命名规范不一定适配你的场景。抄一半才是最尴尬的。
4.3 让Skills跟项目规范绑定：从团队到人
一个个人的经验：skills 真正发挥价值，是在团队规范化之后。我之前在一家公司，代码规范文档写了几十页，但 AI 生成的代码还是我行我素。后来把规范的核心条目拆进.claude/skills/，比如“组件目录必须使用 index.ts 导出”“样式文件统一用 CSS Modules”。AI 生成的代码立马“懂事”了。
但这里要注意权限问题：项目级 skills 是跟随仓库的，团队成员同步代码时，也会同步这些目录。如果有人不想用，可以删掉本地那份，不影响其他人。所以它是软约束，不是硬防线。要想硬约束，还是得靠 CI 检查，skills 负责“尽量生成对的”，CI 负责“不放过错的”。
5. VS Code中运行Skills的常见问题与排查手记
5.1 远程开发时“未能下载VS Code服务器（Failed to fetch）”
用 VS Code 的 Remote-SSH 连到远程服务器时，经常报“无法与 10.10.8.149 建立连接: 未能下载 VS Code 服务器”。很多人的第一反应是 SSH 配置坏了，但实际 90% 的情况是 SSH 能连上，只是远程主机上的~/.vscode-server目录有问题，或者远程主机网络访问更新服务的出口受限。
排查顺序：
- 先确认 SSH 本身能连通，在终端里手动
ssh user@10.10.8.149跑一下，排除网络层问题； - 查看远程主机上
~/.vscode-server/bin/目录，里面应该是几个以 commit id 命名的文件夹，如果空说明服务器根本没部署成功； - 打开 VS Code 命令面板，执行“Remote-SSH: Show Log”，看下载服务器的具体报错；
- 如果确认是远程主机下载不了更新源，可以在本地把对应的 vscode-server 包下载好，再手动 scp 到远程并解压到对应 commit id 目录。
我自己的习惯是：把~/.vscode-server/bin/做成一个手动管理目录，升级版本前先看 commit id，避免每次自动更新都卡半天。
5.2 SCP复制服务器卡住怎么办
有时候 VS Code 会自动执行“正在使用 scp 将 VS Code 服务器复制到主机”，然后卡在 90% 不动。这种情况多数不是 scp 进程本身的问题，而是目标主机磁盘空间不足，或者远端连接被中断。
处理思路是这样的：先在本地终端手动scp同一个文件，观察是否也卡。如果手动复制没问题，就查远端磁盘df -h；如果手动复制也慢，大概率是网络带宽或 MTU 问题。对大文件可以改用压缩传输：
scp -C vscode-server-linux-x64.tar.gz user@192.168.245.128:~/压缩传输在局域网里未必快，但跨网段时经常能解决卡死问题。还有一点：连接远程开发服务器时，尽量保持 VS Code 默认的“自动恢复”，如果中间断过一次，重新连时它会在原来的基础上续传，而不是重新来一遍。
5.3 Skill写了但AI不调用
这是最让人抓狂的：明明把 SKILL.md 放在正确目录，AI 就是不按技能走。我从实际测试里总结出四个原因，按出现频率排序：
- 描述不精准：
description写成了功能说明书，而不是触发词集合。AI 没识别出“这个任务属于那个技能”。 - 上下文太长被截断：项目里塞了大量规则文件、文档、其他 skills，导致 AI 扫描技能目录时漏掉了你的。这种情况要清理目录，少装不必要的技能。
- 目录位置不对：比如用户级和项目级搞反，或者文件名大小写写错。Linux 环境下
SKILL.md和skill.md是两个文件。 - 模型不支持工具调用：有时候你切换到了一些第三方兼容模型，这些模型并不完全支持 tool use，自然就无法加载 skills。
第四点值得展开。很多人会用一些网关工具把 Claude Code 接到 DeepSeek、Qwen、GLM 等模型上。接口兼容只代表“能跑通对话”，不代表“完整支持 tool calling”。而 skills 的加载本身依赖工具调用能力，一旦模型在工具调用上不稳定，就会出现“偶尔触发、经常不触发”的现象。遇到这种问题，先换回官方模型测试，先确认是不是兼容层的问题，再决定要不要换模型。
5.4 解释器与终端版本不一致
这个虽然和 skills 没有直接关系，但我在用 AI 编程助手时经常被它“坑”到：AI 在 VS Code 里选了某个 Python 解释器，但终端里激活的却是另一个 conda 环境，导致脚本运行时报错“模块找不到”。实际上不是代码问题，而是环境不一致。
修复办法很简单：
- 在 VS Code 里按
Ctrl+Shift+P，执行“Python: Select Interpreter”，手动选和终端一致的环境； - 如果在
settings.json里配置了python.defaultInterpreterPath，把它设置成绝对路径； - 终端里执行
which python或where python，确认当前 shell 实际使用的解释器路径。
这类问题跟 skills 的关系在于：AI 生成的脚本可能会调用依赖环境变量，如果环境不一致，再好的 skill 也白搭。我在写 Python 类的 skills 时，规范里会明确“先确认当前解释器再运行”，这个约束写进 SKILL.md 能省很多事。
5.5 编译成功却烧录不进开发板
如果你是做嵌入式开发的，还有一个经典场景：VS Code 里配置 C/C++ 编译器，编译通过，但烧录不进 STM32 开发板。热词里正好也有“vs code里编译成功，却怎么也烧录不进开发板”。
这类问题排查方向集中在三处：调试器驱动、OpenOCD 配置、串口占用。
- 先在设备管理器里确认 ST-Link 或串口设备被系统识别；
- 再检查 OpenOCD 配置文件里的芯片型号是否和实际一致，比如 STM32F4 和 STM32F1 的
-c set CPUTAPID不一样； - 最后确认 IDE 的烧录前工具没有和终端里的串口监视器冲突。
如果让 AI 来帮忙排查，建议把编译日志和 OpenOCD 日志一起贴给它，再套一个“嵌入式烧录排查”的 skill，它可以针对日志里的关键词给出更具体的配置建议。这比直接问“为什么烧录不了”有效得多。
6. 我踩过的坑与给你的建议
在 skills 这条路上走了一段时间，我最大的感受是：skills 最大的门槛不是“写文件”，而是“克制”。
刚开始我也是看到什么技能都想装，结果项目目录里塞了几十个 skill。AI 的上下文窗口是有限的，技能太多不但没有提升效率，反而让对话响应变慢，还会出现技能之间互相冲突的情况。比如某个调试技能要求用console.log，另一个代码规范技能要求用debugger，两个都命中时，AI 会变得犹豫。
我的建议是：初期只保留一个你最想解决的痛点场景，把它做成 skill，反复打磨。比如你一个月要写 20 次业务表单，就先做一个“生成业务表单组件”的 skill，把校验规则、提交逻辑、样式方案都写进去。用 1 周时间调整 description 的触发语义，扩展步骤细节，等稳定了，再加第二个技能。
还有一个很容易被忽略的点：skills 是要维护的。依赖升级了、团队规范改了、目录结构变了，你都得回来改 SKILL.md。所以不要在 skills 里写太具体的“当前实现细节”，而是写“目标、约束、执行步骤”。具体的实现交给 AI 去读取当前代码库，不然半年后技能就成废纸。
最后分享一个小技巧：写 skill 的时候，把“验收标准”也写进去。比如让 AI 生成完组件之后，自己检查一遍是否有 import 遗漏、是否有未使用的变量、是否导出了默认组件。我试过加了这条之后，AI 生成代码的质量有明显提升，因为它在输出前多了一道“自查”动作。这个思路在写提示词的时候也适用，但放到 skill 里会更稳定，因为技能是可复用的，你只写一次，AI 会按这个标准执行一整年。