VS Code中Skills实战：从概念、配置到常见问题排查

如果你最近在刷前端开发或者 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 CodeAnthropic 官方的 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 CLIOpenAI 出的命令行 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 目录结构生成组件”“对接团队内部的接口文档”。项目级优先于用户级。如果你在两个层级都定义了同名的 skillAI 会优先加载项目级的那份。这个设计跟.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 命令行工具每次都要搭一遍argparselogging 主函数入口。新人可能写出来样式五花八门老手又觉得重复劳动很烦。于是目标很明确写一个 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 技能全家桶”直接下载结果一个项目塞了几十个 skillAI 每次都要做大量匹配体验直线下降。正确姿势是只挑和当前工作流强相关的技能放进用户级目录用了一段时间后再删掉不常用的。我在项目中只保留了“调试会话”“变更影响分析”“需求澄清”这三个其他全部禁掉。保留太多技能就像工具箱里什么扳手都有但你要的是找扳手的速度不是扳手的数量。另外开源技能包的内容最好通读一遍。有些技能是作者根据自己项目局写的里面的目录结构、命名规范不一定适配你的场景。抄一半才是最尴尬的。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 user10.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 user192.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 里按CtrlShiftP执行“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 会按这个标准执行一整年。