说个有意思的事我在好几个技术群里看人聊VS Code 使用 Skills聊到最后总是绕回同一个问题——Skills 到底是个啥它装在哪为什么我下了一堆项目在编辑器里却找不到任何入口说实话这个问题我第一次接触时也困惑了很久。VS Code 本身并没有一个叫 Skills 面板 的东西你装了半天skills 合集打开编辑器发现一切照旧于是怀疑自己是不是下错了。这篇文章就是来把这条链路彻底捋清楚的Skills 在 VS Code 生态里到底是什么角色、选哪个 AI 助手搭配它、现成的 Skills 怎么装进来、远程开发时那几个高频报错怎么排查以及最后怎么写一个属于你自己的 Skills。内容偏向实操适合刚接触 AI 编程助手、被agent skills这个概念绕晕的开发者也适合已经在用 Claude Code 或 Codex、但感觉没发挥出全部能力的人。1. Skills 到底解决了什么问题从一问一答到按流程干活1.1 一个最直观的对比普通提示词 vs Skills先说结论Skills 本质上是一份带结构化格式的指令包它把某个领域里一件事情的完整流程、操作标准、验收方式都打包好让 AI 助手按这个流程执行。普通提示词和它的区别用一句话说就是普通提示词是帮我写一个 Python 脚本读取 Excel 并生成报表。Skills 则变成了这是一个数据报表生成任务。请按以下流程执行第一步读取 Excel 文件并校验所有列名是否与配置一致第二步处理缺失值和重复行第三步按业务口径计算指标第四步用 matplotlib 生成图表并导出 PDF以上步骤完成后必须运行项目里的 pytest 测试用例并把本次改动记录到 CHANGELOG.md最后用不超过 200 字总结可能影响到的其他模块。看出来区别了吧普通提示词给 AI 的是一个目标AI 自己决定怎么做。Skills 在目标之上叠加了流程、标准、验证方式、输出格式。也就是说Skills 是给 AI 的一份操作手册、一套 SOP。有了它AI 不再是即问即答的聊天窗口而是像一个按图纸施工的执行者每次干活的方式可预期、可复用、可管理。1.2 Skills 在 VS Code 里的运行方式这里必须先把概念厘清VS Code 本身没有内置 Skills 功能你也不能在编辑器设置里找到一个叫 Skills 的开关。Skills 是被 VS Code 里运行的AI 编程助手Agent读取和执行的。现在主流的几个入口是Claude Code 的 VS Code 扩展、Codex 扩展、Kimi Code 扩展以及部分开源终端型 agent。它们的共性是都支持通过读取本地目录中的 SKILL.md 文件来识别一个技能包。换句话说Skills 是 Agent 的扩展机制而不是编辑器的扩展机制。这也是大多数新手卡住的原因——你在 VS Code 菜单里翻来翻去找 Skills其实方向从一开始就错了。当你在对话框里让 AI 根据论文润色技能处理这一段 时Agent 会先在配置好的 skills 目录里扫描所有 SKILL.md通过里面的描述判断哪个技能匹配当前任务然后加载对应的指令和脚本去执行。整个调用链是用户的自然语言 - Agent 扫描 skills 目录 - 匹配 SKILL.md 描述 - 执行其中的步骤和脚本 - 返回结果。理解这条链路后后面所有安装、排错、自研动作就都有据可依了。1.3 和扩展、插件、命令面板的区别VS Code 扩展是给编辑器加能力的比如代码高亮、主题、格式化工具、语言服务。你会感觉到编辑器本身变了。Skills 则是给 AI 换职业素养的它改变的是 AI 的行为逻辑。装了一个前端组件生成的 Skills 之后编辑器界面没有任何变化但 AI 生成代码时会主动遵守你的组件规范、提交格式和测试要求。它不改变工具改变的是工具使用者的工作方式。还有个最容易混淆的概念是命令面板里的快捷键和任务Tasks那是 VS Code 自己执行命令的机制。Skills 不直接绑定快捷键它靠 Agent 自主判断何时启用。早期我总想用一个快捷键呼出一个技能后来想明白了Skills 的正确用法不是手动触发而是让 Agent 根据上下文自动决定是否使用。你需要做的是把技能描述写得足够清晰让它在该用的场合被想起来。2. 选型思路Claude Code、Codex、Kimi Code 到底该装哪个2.1 三个主流 Agent 的对比既然 Skills 是依附于 Agent 存在的那第一步就得选一个在 VS Code 里跑得顺的 Agent。我三个都用过一段时间简单说说各自的脾气和 Skills 生态。维度Claude CodeCodexKimi Code官方 Skills 支持很成熟有专门的 skills 目录约定支持 skills目录结构与 Claude 类似支持文档也在持续完善适合场景复杂多文件重构、长链路任务、工程化交付轻量代码生成、前端页面、快速补全中文场景理解好、上下文长、和文档问答结合紧密扩展性强社区 skills 生态最丰富中等中等偏上上手成本需要一点 CLI 和配置文件基础最低装完就能用和 Codex 差不多我没有把模型能力放进表格因为模型迭代太快今天的最强明天可能就被超了。更重要的是匹配度你日常干的是什么类型的活决定哪个 Agent 对你最有价值。如果你做的是大型项目的架构调整、跨模块重构、系统性排查我推荐 Claude Code 作为主力。它的 Skills 机制出现得最早社区里沉淀的技能包也是最多的比如热词里那个 superpowers 合集就是围绕 Claude Code 的 skills 体系发展起来的。Codex 在 VS Code 里的体验最零负担适合打开就写点小功能、调调前端的场景。Kimi Code 的长处是对中文指令的解析更自然很多想法你直接用大白话就能交代清楚在做笔记整理、文档生成、论文润色这类文字密集型任务时表现不错。2.2 第三方模型接入cc switch 这类工具做了什么热词里有使用 cc switch 接入 deepseek v4, qwen, glm 等模型这样的表述这也是很多人感兴趣的玩法。cc switch 是一个命令行工具作用是用一条指令切换 Claude Code 后端连接的模型接口。你原本跑在 Claude Code 上面的 Skills在切换后依然可以使用因为 Skills 的执行机制在 Agent 这一层底层的模型换了流程和脚本照样跑。这个思路的价值在于你不需要为了换模型而换 Agent。比如你想省点 API 费用或者某个任务特别适合某个国产模型的强项你只要把 endpoint 和 model 换掉就行Skills 目录不需要任何改动。但坦白说切换之后不能保证 100% 兼容。不同模型对工具调用的遵循度差异很大有些模型会在执行到一半的时候把步骤简化尤其是你写了复杂条件判断的地方。我的建议是把 cc switch 当作一个试模型的入口跑通了你再用若遇到意外行为先回退默认模型而不是急着改技能包本身的逻辑。2.3 我的选择建议如果你现在完全没经验我的建议是别一上来就追求全家桶。先在 VS Code 扩展市场装一个你最顺手的 Agent用它跑一个现成的技能包把Skills 目录 - SKILL.md - 脚本执行这条链路跑通了再去折腾其他工具。一次只引入一个变量出问题的时候你才知道该检查哪里。还要注意一个常被忽略的点Agent 本身的版本会影响 Skills 目录的默认位置。比如 Claude Code 早期版本找skills/目录新版则要求放到.claude/skills/Codex 的目录结构也经历过调整。如果你按照网上教程装完发现 Agent 完全没反应第一件事是检查你的 Agent 版本对应的目录约定而不是怀疑技能包本身坏了。3. 把现成的 Skills 装进 VS Code市场、手动、本地三管齐下3.1 从官方市场安装以 superpowers 为例Superpowers 是目前 GitHub 上社区热度很高的一个 Skills 合集仓库名是 superpowers/superpowers里面包含了大量可以直接用的技能覆盖规划、编码、调试、写作等多个方向。它的安装方式很典型看懂它你就看懂了八成 skills 的安装逻辑。以 Claude Code 为例最通用的是手动克隆方式cd ~/.claude git clone https://github.com/superpowers/superpowers.git skills或者只把技能包放进当前项目目录让技能只对当前项目生效cd /path/to/your-project mkdir -p .claude/skills cp -r ~/.claude/skills/* .claude/skills/这里要特别提醒把仓库克隆下来之后要确认一下目录层级。很多技能仓库最外层是 README 和一堆技能文件夹你要确保skills/目录下面直接就是一个个技能文件夹每个文件夹里有一个 SKILL.md而不是整个仓库被多套了一层目录。我见过太多人把仓库整个拉下来、忘了处理嵌套层级Agent 扫描的时候压根找不到技能描述。装完之后重启 Agent 会话在对话框里描述一下你要做的事如果描述和某个技能的 description 匹配上了它就会自动启用。3.2 手动安装目录结构和避坑先看一个典型的技能目录长什么样skills/ └── pdf-report/ ├── SKILL.md └── scripts/ └── generate.py核心文件就是SKILL.md。它的开头有一段 YAML 格式的 frontmatter里面最重要的字段是name和description。Agent 学习新技能时主要靠读description来判断什么时候该调用这个技能。这段描述写得越精确技能被正确调用的概率越高。我踩过的几个坑写在这里供参考有些技能包依赖 Node.js 或 Python 环境。你把技能文件夹放进来了但里面的脚本要跑起来还需要对应的运行时。装完技能不装依赖是最常见的假安装。技能目录不要直接放在中文或带空格的路径下。大部分脚本没有做路径转义一旦路径里有空格子进程调用时经常报错。技能之间不要互相覆盖同名文件。两个技能包如果都提供utils.py后安装的会覆盖先安装的而且 Agent 不会提醒你。另外手动安装时不要贪多。一次装 50 个技能Agent 每次做决策都要多扫描 50 份描述既影响响应速度也可能因为描述互相干扰导致误触发。我个人的习惯是一个项目里只保留不超过 10 个与当前工作强相关的技能。3.3 值得优先装的几类 Skills写论文、前端开发、代码审查从搜索热词里能看到大家最关心的是这么几类写论文、前端开发、代码审查。我说说自己的实际体验。论文写作 / 润色类。热词里的 workbuddy skills 就属于这一类。这类技能通常集成了文献整理、段落润色、引用格式校验等功能。用的时候你不需要写复杂的提示词直接把草稿丢给 Agent说用论文润色技能处理一下它会自动按学术写作规范调整措辞、检查逻辑连接、给出修改说明。对于非英语母语的同学来说这类技能的价值不是帮你代写而是帮你把已经写出来的内容改得更加地道。前端开发类。这是我自己用得最多的一类。好的前端技能会在 prompt 里内置组件库用法、Tailwind 配置约定、接口联调规范。举个例子你让它生成一个带登录态的待办页面普通 AI 会给你一个玩具 demo但挂载了项目规范技能的 AI 会先扫描你的现有代码识别出路由配置方式、UI 库版本、API 封装方式然后再动手。这个体验差距是巨大的。代码审查类。这类技能适合放在 CI 前的本地检查环节。技能会定义一份审查清单要求 Agent 在跑完审查后输出变更影响范围、潜在性能问题、安全风险、命名规范建议。你可以把团队内部总结的常见 bug 模式写进去让 AI 每次审查都按同一套标准来。4. 排错笔记远程开发、下载失败、环境不一致的完整排查链路4.1 场景一无法与远程主机建立连接服务器下载 failed to fetch先看一个特别常见的报错几乎每天都有新手遇到无法与10.10.8.149建立连接:未能下载vs code 服务器(failed to fetch).这个问题的本质是VS Code 通过 Remote-SSH 远程开发时需要在远端主机上安装一个和本地版本完全一致的 vscode-server 服务端。当它尝试从官方下载地址拉取服务端压缩包时由于网络不通、代理配置错误或地址被阻断下载失败于是整个连接过程卡住。排查链路我建议按这个顺序走先确认 SSH 本身能通。在终端里执行ssh user10.10.8.149如果 SSH 正常但 VS Code 连不上那问题基本就是 vscode-server 下载环节。检查本地和远端的代理设置。VS Code Remote-SSH 会读取你本地的代理环境变量如果代理配置有问题会导致远端 wget 或 curl 请求失败。可以在终端里env | grep -i proxy看一下。检查远端主机的 DNS。可以ssh userhost curl -I 下载地址测试一下能否正常响应。这一步的目的只是确认连通性。手动下载并放置 vscode-server。这是最可靠的办法。先在本地 VS Code 的安装目录里找到product.json读取里面的commit字段这就是当前版本对应的 commit id。然后手动下载对应版本的服务端压缩包用scp传到远端后解压到~/.vscode-server/bin/commit-id/目录最后给 server 可执行权限重新连接即可。这个流程比较繁琐但它是绕过网络下载问题最稳妥的方法经验之谈不要反复点重试每次重试都会重新触发下载反而浪费时间。4.2 场景二SSH 连接时 scp 复制 VS Code 服务器卡住另一个出现频率很高的卡点热词里原话是设置 ssh 主机 192.168.245.128: 正在使用 scp 将 vs code 服务器复制到主机这个现象是SSH 隧道已经建立进入到了传输 vscode-server 包的阶段但 scp 传输过程特别慢或者直接卡住。原因是服务器压缩包通常有几十兆而很多内网主机带宽有限加上 scp 本身没有断点续传一旦中断就从头再来。我的处理思路是建立一条手动传送通道# 在本地终端先给远端创建目录 ssh user192.168.245.128 mkdir -p ~/.vscode-server/bin # 直接 scp 上传压缩包注意先解压出目标目录名 scp vscode-server-linux-x64.tar.gz user192.168.245.128:~/.vscode-server/bin/ # 登录远端解压到对应 commit-id 目录 ssh user192.168.245.128 cd ~/.vscode-server/bin tar -xzf vscode-server-linux-x64.tar.gz传完之后检查目录结构是否是~/.vscode-server/bin/commit-id/如果 commit id 对不上启动时又会触发重新下载。除了传输卡住还有一类隐蔽问题远端主机是精简系统缺少tar、wget这类基础命令。VS Code 的服务端安装脚本依赖它们缺失时也会出现卡住。可以在远端执行which tar which wget确认一下缺什么补什么。提示如果远端主机是公司内网机器并且你无法修改系统级网络配置最简单的方法永远是手动下载 scp 上传这也符合多数公司的远程开发实践。4.3 场景三解释器与终端版本不一致这个坑和 Skills 的关联更深。不少 Skills 内部是靠 Python 脚本来实现实际功能的。如果你的 VS Code 里选择的 Python 解释器和你当前终端激活的环境不是同一个Skills 脚本可能被安装在了 A 环境运行时却用的是 B 环境结果就是脚本明明有但它依赖的库 import 失败。排查步骤也不复杂在 VS Code 终端里执行which python看当前 shell 用的是哪个解释器。打开命令面板执行Python: Select Interpreter看 VS Code 绑定的是哪个解释器。对比两条路径经常会出现终端用 pyenv 的 python3.11而 VS Code 解释器选了 conda 的 python3.10。统一方法在.vscode/settings.json里显式固定解释器路径比如{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python }如果你在跑一个 Skills 脚本最保险的方式是在脚本内部显式调用虚拟环境的解释器而不是依赖python这个系统命令。比如 Python 脚本开头直接写成/path/to/.venv/bin/python $或是在 SKILL.md 里写清楚执行前先加载 .venv 环境。这个坑非常隐蔽因为 Skills 本身没报错你只会觉得脚本有时候能跑有时候不能跑。其实不是随机故障就是环境选错导致的。5. 开发自己的 Skills从需求到落地的完整路径5.1 Skills 的骨架SKILL.md 和脚本/指令安装别人的 Skills 只是第一步真正能让你工作效率翻倍的是把自己日常重复的流程沉淀成一个 Skills。其实也就是把你平时怎么交代活整理成一份 Agent 能读懂的手册。每个 Skill 的骨架只有两部分SKILL.md写给 Agent 看的操作手册附加脚本/模板/配置实际干活时要调用的工具一个最小可用的SKILL.md长这样--- name: paper-polish description: 对用户提供的论文摘要或段落进行学术润色调整句式结构、提升用词准确性并输出修改前后的对照。 --- ## 工作流程 1. 识别用户输入的文本属于摘要、引言、方法、结论中的哪一部分。 2. 保持学术表达规范避免口语化。 3. 对每一段输出三部分内容 - 润色后文本 - 修改点清单 - 修改理由简述 ## 注意事项 - 不改变原有结论、数据和引用。 - 遇到专业术语期间不得替换为通用词汇。 - 如果用户没有明确说明目标期刊风格默认采用简洁学术风。这个文件的关键点在于description。前面说过Agent 靠 description 判断什么时候调用技能所以描述里要写明做什么、输入是什么、输出是什么尽量包含触发词比如润色、修改、学术、论文。5.2 实例写一个论文润色助手 Skills我拿自己写的一个论文润色技能来演示。除了SKILL.md我还放了一个辅助脚本用来处理用户提交的文本并生成对照表。# scripts/polish_text.py import re import sys def split_sentences(text): # 简单按句号拆句实际项目里可以用 nltk 或 spacy return re.split(r(?[。\.!?])\s*, text) def main(): input_text sys.stdin.read() sentences split_sentences(input_text) print(f共识别出 {len(sentences)} 个句子准备逐句润色。) if __name__ __main__: main()然后 Skill 的目录是这样的paper-polish/ ├── SKILL.md ├── scripts/ │ └── polish_text.py └── templates/ └── output_report.md使用场景你在 VS Code 里让 Agent 用论文润色技能处理一下这段摘要。Agent 读到 SKILL.md 后会按里面的流程执行必要时会调用scripts/polish_text.py做文本预处理最后按templates/output_report.md的格式输出润色结果。我的建议是初次开发技能时不要一上来就写复杂逻辑。先写一个只包含 3-5 个固定步骤的 SKILL.md不挂任何脚本跑通了再逐步加脚本和判断逻辑。技能和代码一样迭代比一次成型可靠。5.3 调试与验证怎么确认 Skills 生效了写完一个 Skills 后最大的疑问是它到底起没起作用最简单的方法是直接问它你现在能看到哪些技能 或者在对话框里描述一个明显只属于该技能的任务。比如测试论文润色技能你就发一句表述混乱的句子看 Agent 是否按 SKILL.md 里定义的输出格式返回。更严谨的验证流程确认文件路径正确技能文件夹位于 Agent 读取的 skills 根目录下SKILL.md 放在技能文件夹根目录不能放在子目录里。修改后重启 Agent 会话。大部分 Agent 只在会话启动时加载一次技能目录改文件不重启是不生效的。用调试模式启动 Agent观察日志里是否出现了你技能的 name 字段。很多 Agent 支持--debug或类似参数输出里能看到技能匹配的记录。检查脚本权限。脚本文件如果没有可执行权限Agent 调用时会报权限错误chmod x一下就好。按照这个顺序排查绝大多数技能没生效的问题都能定位。最后分享一点个人实践体会。Skills 这个东西真正难的不是安装也不是手写格式而是把你想让 AI 稳定执行的流程想明白。你如果连自己平时是怎么工作的都说不清楚那就很难写出一份让 AI 照做的技能说明。所以我的建议很朴素每次你发现自己需要跟 AI 反复交代同一件事时就把它记录下来攒到三次以上就值得写成一个 Skills。刚开始可以只给自己用放在个人目录下等稳定了再挪到项目目录里固化下来再往后可以整理成一个团队共享的技能包。这个过程比单纯下载别人的技能包有价值得多——因为你从用技能的人慢慢变成了造技能的人这才是 AI 编程时代最值得积累的能力。