企业官网建设流程全解析

最近不少人私信问我，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 user@your-server-ip

配好之后，VSCode 的 Remote - SSH 插件就能直接连上远程开发环境。如果你用的是 WSL，想在本机 Windows 的 VSCode 里操作 Linux 子系统里的项目，也需要确认wsl命令可用，并安装 WSL 扩展。

还有一件事经常被忽略：远程服务器的时间要准。agent 在做代码签名、连接部分服务时会校验时间，之前有次我在服务器上怎么都登不上某个开发代理服务，最后发现是服务器时区漂了，同步时间之后瞬间恢复。建议日常就配好 NTP 自动同步，避免这种低级问题。

3. 配置 agent 本体：从 Claude Code、Codex 到私有模型

3.1 安装并初始化 Claude Code

Claude 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/codex

Codex 同样会读取项目里的规则文件，不过它对配置文件名的默认支持有差异，具体要看版本更新。我自己的处理方式是用一个统一的目录，把规则文件集中放，然后在 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 常见问题与排查速查表

把自己攒下的几个典型问题整理成一个速查表，方便你对照排查：

这表格里的问题，你遇到的大概率会集中在“规则没生效”和“改了不该改的东西”这两类上。根因基本都是规则文件的位置、编码或优先级问题，按表里的解法走一遍，绝大多数能救回来。

根据我个人经验，VSCode 里配置 AI agent skills，最核心的动作其实是“规则文件的持续演化”，而不是某一次装好就一劳永逸。建议你第一版只写 30% 的必要规则，跑几个真实任务后把反馈沉淀回去，让规则跟着项目的实际需求慢慢长起来。比如 agent 经常问“这个常量为什么不在配置文件里”，你就该把常量定义的位置写进规则；agent 总是不写测试，你就把测试要求加粗。调了一两周之后，你会明显感觉到同样的模型，在你这儿说话做事明显靠谱很多，这种差距就是 skills 体系带来的。