最近不少人私信问我VSCode 里配置 AI agent skills 到底怎么搞。这个东西说难真不难但网上一搜全是零散的片段有的只讲插件安装有的只讲配置文件很少有把整条链路串起来的。我把自己从零到一配下来的完整过程整理了一遍踩过的坑和验证过好用的方案都写在下面照着走基本可以少折腾半天时间。这篇内容适合这几类人看VSCode 用得比较多、想把手头项目真正交给 AI agent 干活儿的开发者已经装了 Claude Code 或 Codex 但感觉回复质量一般、想通过 skills 机制提升准确度的人还有刚接触 agent 编程、对“规则文件到底怎么写”没什么概念的新手。我会从环境准备开始一路讲到 skills 目录设计、上下文规则编写、远程开发场景以及实际跑通一个任务的完整流程。1. AI agent skills 到底是个啥1.1 不要把 skills 和插件、扩展混为一谈很多人在这一步就卡住了因为他们以为“skills”指的是 VSCode 插件市场里某个能一键安装的东西。实际上AI agent skills 是一套给 agent 定义能力和行为边界的规则集合通常以目录和 Markdown 文件的形式存在于项目里。你告诉 agent“你擅长什么”“你按什么步骤干活儿”“哪些事不许做”这些规则集合在一起就是 skills。打个比方插件是给编辑器装上的工具比如格式化代码、高亮语法而 skills 是给 agent 装上的“岗位职责”。同一个 agent配上不同 skills它可以是一个 Python 后端工程师也可以是只做前端重构的专职助手甚至是一个帮你写提交规范的机器人。在具体实现上目前主流方案里比较有代表性的是 Claude 生态的项目内规则机制项目根目录放一个CLAUDE.md作为长期记忆文件而skills目录则存放一个一个独立的能力包。这些能力包可以包含详细的操作说明、脚本、模板agent 会在需要时自动读取并调用。VSCode 里配置 AI agent skills本质就是把这些规则、能力包和编辑器里的 agent 插件串起来。1.2 为什么要在 VSCode 里配置 skills有人会问我直接在终端里跑 agent 不就行了为什么非要和 VSCode 绑在一起我的实际体验是这三点内聚上下文VSCode 天然知道你打开的是哪个项目、当前激活的是哪个文件、工作区里有哪些目录。agent 插件可以读取这些信息不用你手动把大段代码复制粘贴给 agent。视觉反馈与即时操作agent 对代码文件的修改可以直接在编辑器里 diff你可以逐行确认改了什么而不是在终端里看一大堆文字输出。多 Agent 协同更自然如果同时装了 Claude Code 和 Codex 这种不同后端VSCode 可以当作统一入口各自保存会话记录和规则文件互不干扰。而且VSCode 有丰富的远程开发支持。配置好 WSL 或 SSH 之后skills 文件放在服务器项目里本地编辑器依然可以无缝调试、查看修改。这一点对经常在服务器上做开发的人来说非常重要后面我会专门讲。2. 动手前先把底子打好基础环境准备2.1 代码编辑器与必要运行时既然标题就是“VSCode 配置”那 VSCode 本身自然是第一项。建议直接到官网下载稳定版不要用绿色精简版或来路不明的镜像包否则后面装插件、跑扩展容易出各种奇怪问题。安装过程一路下一步就行唯一提醒的是记得勾选“添加到 PATH”这一项方便后续在终端里直接敲code命令启动。然后是 Node.js这个很关键。目前多数 agent 类插件包括 Claude Code、Codex 的 CLI 封装都是基于 Node.js 跑的所以本地最好装一个较新的 LTS 版本。装完后在终端执行node -v和npm -v能看到版本号就说明环境没问题。如果你项目里还涉及 Python那顺便把 Python 和 pip 也配好。我遇到过不少同学只装了插件没装对应运行时agent 一执行脚本就报错还以为是自己 skills 写得不对。这个不能怪 agent基础运行环境还是得自己保证。另外 Git 建议一起装好并且把用户信息配置了git config --global user.name 你的名字 git config --global user.email 你的邮箱agent 在生成代码后有不少场景会帮你创建分支、提交代码如果 Git 用户信息缺失它会卡在一堆 git 报错上影响使用体验。2.2 配置好 Git 和 SSH 能省一半事这里重点说下 SSH。如果你只在本机写代码SSH 可以暂时不管但如果你要把 agent skills 用在远程服务器上SSH 密钥的配置就很重要了。最简单的做法是生成密钥对然后把公钥放到服务器上ssh-keygen -t ed25519 -C 你的邮箱 ssh-copy-id useryour-server-ip配好之后VSCode 的 Remote - SSH 插件就能直接连上远程开发环境。如果你用的是 WSL想在本机 Windows 的 VSCode 里操作 Linux 子系统里的项目也需要确认wsl命令可用并安装 WSL 扩展。还有一件事经常被忽略远程服务器的时间要准。agent 在做代码签名、连接部分服务时会校验时间之前有次我在服务器上怎么都登不上某个开发代理服务最后发现是服务器时区漂了同步时间之后瞬间恢复。建议日常就配好 NTP 自动同步避免这种低级问题。3. 配置 agent 本体从 Claude Code、Codex 到私有模型3.1 安装并初始化 Claude CodeClaude Code 是目前配置 skills 最顺滑的 agent 之一它对CLAUDE.md和skills目录有原生支持。安装方式很简单在终端执行npm install -g anthropic-ai/claude-code装完输入claude就能进入交互式对话界面。第一次启动会让你登录账号如果网络环境能访问官方服务直接走浏览器授权就行如果是团队账号或者走企业代理按官方文档配置好环境变量即可这里不展开。初始化完成之后建议在项目根目录首次启动claude它会自动生成一个初始化的CLAUDE.md文件这个文件就是后续你定义长期规则的主阵地。里面已经有默认的模板和提示建议读完再改不要一上来就清空。3.2 接入其他模型很多人由于账号或使用习惯的原因不一定用 Claude 官方服务而是想接 DeepSeek、Codex 或其他模型。这些怎么做呢先说 Codex。Codex 是 OpenAI 出的命令行编程工具同样也是 Node.js 生态安装方式类似npm install -g openai/codexCodex 同样会读取项目里的规则文件不过它对配置文件名的默认支持有差异具体要看版本更新。我自己的处理方式是用一个统一的目录把规则文件集中放然后在 agent 配置里显式给到路径这样即使以后换 agent规则内容也可以复用。再说接 DeepSeek 这种私有模型网关。核心思路是给支持自定义模型接入的 agent 客户端配一个兼容接口的 base URL再把模型名指过去。比如某些 CLI 工具支持这种配置claude config set --global apiBaseUrl https://your-proxy.example.com claude config set --global model deepseek-chat这类操作的具体参数不同版本会变化建议装完先看官方说明核心明白一件事就行skills 规则和模型后端是解耦的规则写在项目里模型只负责理解和生成内容。换模型不会丢失你的规则体系。3.3 编辑器集成与快捷键CLI 能跑通之后就要把 agent 接回 VSCode。在扩展市场搜索并安装 Claude Code 的官方扩展或者装 Codex 扩展看你主要用哪个。装完之后左侧会出现专门的面板你可以直接在里面输入指令同时它会自动感知当前打开的文件内容。我建议把这些快捷键记下来不同扩展略有差异以官方按键映射为准快速唤起对话输入框把选中的代码送进对话并让 agent 分析让 agent 直接处理终端里最近一次报错实际用下来发现选中代码再让 agent 分析比新开对话粘贴大段代码要准得多因为编辑器上下文已经把它要处理的对象范围缩小了。这也是 VSCode 相比纯终端体验提升最明显的地方。4. skills 目录设计与规则编写4.1 skills 目录结构怎么设计这才是整个配置流程的重头戏。一个典型的结构长这样your-project/ ├── .vscode/ ├── src/ ├── CLAUDE.md └── skills/ ├── frontend-refactor/ │ ├── SKILL.md │ ├── checklist.md │ └── templates/ ├── backend-api/ │ ├── SKILL.md │ └── examples/ └── commit-standard/ └── SKILL.md每个子目录就是一个独立 skill目录名建议用 kebab-case不要用中文或带空格的名称。每个 skill 目录里的SKILL.md是这个能力的说明文件agent 会在需要时读取它。里面应该写清楚这个 skill 的触发条件、适用场景、执行步骤、约束规则。为什么要把规则拆成一个个独立目录而不是全塞进CLAUDE.md里我自己的体会是CLAUDE.md是常驻上下文token 消耗要控制写得越多 agent 每次请求花的钱越多、响应也越慢。而 skills 是按需加载的agent 判断要用哪个才去读对应的文件规则再多也不至于拖累日常应答。4.2 SKILL.md 文件编写规范SKILL.md 的内容不要写废话。我用下来最顺手的是这种结构--- name: frontend-refactor description: 在 Vue/React 项目中执行安全的前端重构包括组件拆分、命名优化、样式收敛。 when_to_use: 用户提到“重构”“清理组件”“优化前端结构”等指令时触发。 progress_chain: false --- ## 核心原则 1. 不改变组件对外接口除非用户明确要求。 2. 每次重构前先输出影响范围清单确认后再动手。 3. CSS 变量统一收敛到主题文件不硬编码颜色。 ## 执行步骤 1. 扫描 src/components 下目标组件及其引用。 2. 分析组件 props、事件、对外暴露的 slot。 3. 重构并同步更新引用处。 4. 跑一遍 lint 和类型检查。 5. 输出变更摘要。注意开头的 YAML frontmatter虽然不一定每个 agent 都强依赖但写上可以有更明确的触发判断。when_to_use特别有用它帮 agent 判断什么时候该用这个 skill减少误触或漏用。我还建议在 skill 里放一个checklist.md把质量检查项写清楚。agent 在完成重构后会主动对照检查清单逐项确认比如“是否有被删除的导出”这些细小的兜底能显著减少低质量代码产出。4.3 CLAUDE.md 长期记忆文件怎么组织CLAUDE.md 不承担具体某个技能的执行细节它负责的是项目全局的长期记忆。我一般在里面放四块内容项目背景这个项目解决什么问题技术栈是什么目录结构如何。代码规范命名风格、缩进、组件组织方式、是否允许使用 any 等。工作流偏好提交信息格式、分支命名规范、测试文件的放置路径、代理服务器配置等。明确禁止的行为比如不要动 schema 文件、不要自动修改锁文件、不要未经确认就重命名公共 API 等。举个例子一段典型的 CLAUDE.md 内容# 项目客户管理后台 ## 技术栈 - 前端Vue 3 TypeScript Vite - 后端Node.js Express - 数据库PostgreSQL ## 代码规范 - 组件文件名使用 PascalCase - 样式使用 CSS Modules禁止全局裸类名 - 所有新增接口必须写 JSDoc ## 工作流 - 提交信息使用 conventional commits 格式 - 新增功能必须附带单元测试测试文件与源码同目录下 __tests__ 中 ## 禁止行为 - 未经确认不得修改 prisma/schema.prisma - 不得在 package.json 中隐藏依赖的 oninstall 脚本 - 不得删除 tests 目录下的历史用例这类文件写得好不好直接决定 agent 在你项目里的表现。我自己迭代了一个多月每次 agent 出现不符合预期的行为我就把对应的情况补充或修改到 CLAUDE.md 里规则会越调越贴身。4.4 让 skills 支持远程开发WSL/SSH如果你项目在远程服务器或 WSL 里skills 的配置思路是“项目内规则跟着项目走”。远程开发时VSCode 会把工作区挂载到远程环境所以只需要在远程项目目录中创建CLAUDE.md和skills目录远程终端里启动 agent它就能自动识别这些规则。本地的 VSCode 只是显示和交互层不需要重复拷贝这些文件。有一个点特别提醒当你本机用 VSCode 连接远程时如果本地工作区没有打开命令面板中启动 agent 扩展可能会默认在本地目录找规则文件导致“明明配了 skills 怎么不生效”的错觉。解决办法是先通过 VSCode 的“打开远程窗口”进入项目再启动 agent 扩展面板或终端。5. 实际跑通一个例子用 agent skills 完成一个模块开发5.1 定义任务和技能理论说了不少用例子走一遍更直观。我最近在一个内部工具项目里加了一个“导出报表”的功能就用 agent skills 来完成。我在skills/backend-api/SKILL.md里写了--- name: backend-api description: 用于 Node.js 后端的接口开发与调试包括路由注册、参数校验、错误处理。 --- ## 执行步骤 1. 查看路由文件确认是否已有相似接口。 2. 按项目分层新增 controller参数校验、service业务逻辑、model数据访问。 3. 错误统一返回 { code, message } 结构。 4. 新增接口必须在 README 的 API 文档中登记。然后在 VSCode 里打开 agent 面板直接说“新增一个导出报表接口条件按 createTime 和 status 过滤文件用 CSV 格式。”agent 读取了skills/backend-api/SKILL.md里的步骤先扫了一遍现有路由发现了之前已有一个列表查询接口就在它的基础上扩展而不是另起炉灶。这个行为正是when_to_use和checklist共同作用的结果。5.2 验证与迭代agent 生成完代码后我没有直接点接受所有修改而是逐个打开 diff 检查。要特别留意的点包括有没有引入新的依赖但没有说明理由参数校验是否覆盖了边界值比如空串、超长字符串错误码是否复用而不是发明新格式有没有处理文件流关闭的逻辑避免连接泄漏我把检查出来有问题的部分直接选中发给 agent让它重新调整。它根据我的反馈修改后我把这条对话的经验写回了SKILL.md的checklist.md里相当于给 skill 打了补丁。反复两三轮之后这个导出接口就稳定了。整个过程我没有手写一行后端代码但逻辑正确性是通过和 agent 的交互以及我对 diff 的检查来保证的。这个流程走顺之后效率比自己写快不少。5.3 常见问题与排查速查表把自己攒下的几个典型问题整理成一个速查表方便你对照排查现象常见原因解决办法agent 没有按预期使用 skillSKILL.md 里的when_to_use不明确或 CLAUDE.md 里写了冲突规则检查触发关键词确认规则文件编码为 UTF-8必要时在对话中明确引用 skill 名agent 忽略 CLAUDE.md 里的禁止行为规则放到了系统级配置里项目级规则优先级不够把禁止项写进项目根目录 CLAUDE.md并在每次对话确认系统提示中是否包含该文件skills 目录不生效agent 不读取目录名或文件名拼写错误确认目录名为skills/SKILL.md并且 content 里没有 emoji 或奇数字符装了扩展但终端启动不了 agentNode.js 版本太旧升级 Node.js 到官网要求的 LTS 版本重开终端再试远程服务器上 skills 不生效在本地启动了 agent 而不是远程终端确保通过 VSCode Remote 打开远程窗口在远程路径下启动 agentagent 修改了大量无关文件规则里缺少“最小变更”约束在 CLAUDE.md 中增加“不得格式化未涉及的文件只做必要修改”模型总是没理解项目背景CLAUDE.md 太薄或内容过时每次功能迭代后同步更新 CLAUDE.md 中架构说明这表格里的问题你遇到的大概率会集中在“规则没生效”和“改了不该改的东西”这两类上。根因基本都是规则文件的位置、编码或优先级问题按表里的解法走一遍绝大多数能救回来。根据我个人经验VSCode 里配置 AI agent skills最核心的动作其实是“规则文件的持续演化”而不是某一次装好就一劳永逸。建议你第一版只写 30% 的必要规则跑几个真实任务后把反馈沉淀回去让规则跟着项目的实际需求慢慢长起来。比如 agent 经常问“这个常量为什么不在配置文件里”你就该把常量定义的位置写进规则agent 总是不写测试你就把测试要求加粗。调了一两周之后你会明显感觉到同样的模型在你这儿说话做事明显靠谱很多这种差距就是 skills 体系带来的。