企业官网建设流程全解析

最近折腾 AI agent 的时间，比我实际写代码的时间还长。不是模型不够聪明，而是每次让它处理具体业务时，总在同样的项目规范上反复出错。一开始我把规则写进 system prompt，几千字塞进去，效果反而更差——上下文一长，模型抓不住重点，该遵守的规范照样忘。后来换了思路，把“知识包”做成 skills 挂到 agent 上，整套配置放在 VSCode 里管理，跑通之后效果提升非常明显。

这篇文章就是完整的实操记录，从概念到落地再到排坑，一条线讲完。适合已经在 VSCode 里用 AI agent 写代码、但对 skills 机制还比较模糊的人，也适合刚听说 skills、想搞清楚它和普通 prompt 到底差在哪的人。

1. Skills 到底是什么，它和 MCP、插件有什么区别

1.1 一次完整的 skill 调用过程

先聊概念，不然配置完你也不知道自己在配什么。一个 skill 本质上是一个目录，里面至少有一个名为 SKILL.md 的 Markdown 文档。这个文档开头有一段 YAML 格式的元信息，包含技能的 name 和 description，正文则是具体的操作流程、规则、模板或参考资料。

agent 在每次对话开始前，会扫描所有可用 skills 的 description，判断当前任务与哪个 skill 匹配。匹配成功的 skill 会被读入上下文，后续整个任务都按照你定义的流程走。整个过程有点像你给新来的实习生一份《项目交接手册》：你不用把手册内容背给他听，只需要告诉他“遇到这类问题去翻手册第几章”。

关键点在于：skills 是按需加载的。没有匹配任务时，它只是磁盘上的一堆文件，不占上下文；一旦匹配，才把完整内容喂给模型。这跟把规则塞进 system prompt 有本质区别。

1.2 skills、MCP 和插件的边界

我在配置过程中发现，很多人把 skills 和 MCP Server、VSCode 插件混为一谈，这三者其实是三个层级的工具。

MCP Server 解决的是“agent 获取动态数据、执行外部操作”的问题。它提供工具接口，比如读取数据库、调用内部 API、搜索代码库。MCP 面向的是实时状态，强调交互能力。

VSCode 插件则是编辑器层面的扩展，比如语法高亮、代码补全、LSP 集成。插件运行在编辑器进程里，agent 本身不直接依赖它。

Skills 解决的则是“agent 如何按既定流程处理某类任务”的问题。它更像静态知识库，内容由你提前编写。举个例子：MCP 负责“查当前分支有没有未提交的改动”，skill 负责“提交代码前按什么顺序跑检查、写 commit message 用什么格式”。

三者的协同关系是：skill 定义规范和流程，MCP 提供执行动作所需的数据接口，VSCode 提供编辑和调试环境。配置时不需要互相替代，而是各管一段。

1.3 适合用 skills 承接的场景

结合我这段时间的实测，下面几类场景用 skills 收益最大：

不适合用 skills 的场景我也列一下：需要实时查询的操作、高度依赖用户当前输入且每次差异很大的任务、超长且很少复用的分析工作。这些用 MCP 或普通对话更合适。

2. 环境准备：VSCode 侧要满足的三个前置条件

2.1 把终端和 shell 环境统一

看着是废话，但这是我踩得最深的坑。配置 skills 涉及创建目录、写文件、在终端里执行 agent 命令，不同 shell 环境下路径规则不一样，很容易出问题。

我的建议是：无论 macOS 还是 Windows，都在 VSCode 里固定一个默认终端。macOS 用 zsh，Windows 用 PowerShell 7（不要用 Windows PowerShell 5.1，编码问题会让你怀疑人生）。设置方式：Ctrl+Shift+P打开命令面板，搜索“Terminal: Select Default Profile”，选定之后重启终端。

为什么要强调这个？因为 agent 在执行 skill 里的脚本时，会调用当前终端的 shell。如果 shell 不一致，脚本里写的命令可能完全无法解析。比如 Windows 下用 cmd 和 PowerShell 对$HOME环境变量的处理就不一样，skill 里引用路径时很容易踩。

2.2 Node.js 版本与 Git 配置

主流的 agent 宿主工具基于 Node.js 开发，所以 Node.js 环境是硬前提。我建议安装并使用 LTS 版本，目前我在用的版本是 Node.js 20.x。版本太旧的话，依赖包安装或 agent 运行时会报错，但报错信息往往不直观，排查起来很浪费时间。

Git 同样必须提前装好并完成基础配置，因为很多 agent 工具在首次运行时需要读取 Git 配置，或者把 skill 放在 Git 仓库里管理。执行下面两条命令检查：

node -v git --version

如果还没配置 Git 用户信息，顺手补上：

git config --global user.name "your name" git config --global user.email "you@example.com"

这里有个很容易忽略的细节：如果公司的代码仓库走的是 SSH 方式，务必提前把 SSH key 配置好。agent 在某些场景下会自动调用git命令，如果认证没配好，流程会在中途卡住，而且报错信息极其隐蔽。

2.3 确认 Agent 宿主程序版本

Skills 机制本身是跟着 agent 宿主工具走的。我现在常用的有两个：Claude Code 和 Codex。两者对 skills 的支持路径略有差异，但目录结构和 SKILL.md 格式基本一致。

在配置之前，先确认你安装的 agent 工具版本足够新。老版本可能不支持 skills 机制或支持不完整。以我用的工具为例，更新命令如下：

# 如果通过 npm 安装 npm update -g @anthropic-ai/claude-code npm update -g @openai/codex

更新完验证一下版本号。如果工具自身版本太老，后面怎么配都不会生效，这也是很多教程没提的“前置的前置”。

3. 核心配置步骤：从目录到 SKILL.md 全流程

3.1 全局目录与项目目录的分工

Skills 存放在两个层级：全局目录和项目目录。全局目录对当前用户所有项目生效，适合放通用于所有项目的技能，比如 Git 提交规范、通用代码审查清单。项目目录只对当前项目生效，适合放项目特有规范，比如这个项目的数据流约定、部署流程。

以我实际用的目录结构为例：

# 全局目录 ~/.claude/skills/ ├── git-commit-conventions/ │ └── SKILL.md └── code-review-checklist/ └── SKILL.md # 项目目录（Claude Code） .vscode/ai/skills/ ├── project-data-model/ │ └── SKILL.md └── frontend-lint/ ├── SKILL.md └── lint-check.mjs

注意：不同 agent 工具对“项目目录”的识别规则不同。有的认项目根目录下的.claude/，有的认.codex/。如果你同时用多个工具，建议在项目根目录下统一为每个工具建各自的 skills 目录，不要混用。VSCode 的.vscode/ai/skills/是我个人习惯的集中管理方式，配合 settings.json 做映射，后面细讲。

3.2 SKILL.md 的标准格式与元信息

一个规范的最小 SKILL.md 长这样：

--- name: frontend-lint description: 项目前端代码规范与提交前检查清单。当用户提到“检查代码”“提交前确认”“eslint 报错”“风格问题”时使用。 --- # 前端代码检查流程 1. 先运行 ESLint 检查，命令是 `npm run lint:eslint` 2. 再运行 TypeScript 类型检查，命令是 `npm run typecheck` 3. 如果检查失败，按错误类型分类处理： - 自动修复类：运行 `npm run lint:fix` - 手动修复类：列出文件路径和错误行号 4. 全部通过后，输出检查结果汇总

frontmatter 里 name 和 description 是最关键的两个字段。name 是技能的唯一标识，description 则决定了 agent 什么时候调用这个 skill。写 description 时要尽量包含明确的触发词和行为描述，不要写“处理代码问题”这种空话。我经过多轮测试，有效的描述格式是：场景 + 触发词 + 预期动作。

还有一点容易被忽略：SKILL.md 的文件名必须保持大写的SKILL.md，不能改成小写或自定义名称。这是 agent 扫描时的约定，改了就识别不到。

3.3 支持脚本与资源的引用规则

SKILL.md 可以引用同目录下的脚本和资源文件。代理读取时，以该 skill 目录为根目录解析相对路径。

例如，我让 agent 执行一个自定义的代码检查脚本，在 SKILL.md 里这样写：

在项目根目录执行以下命令读取检查脚本输出： ```bash node ./.vscode/ai/skills/frontend-lint/lint-check.mjs

脚本中如果引用了配置文件，也尽量使用绝对路径或基于项目根目录的相对路径，不要用~或者环境变量。因为 agent 执行脚本的当前工作目录不一定是 skill 目录，用相对路径容易找错文件。最稳妥的做法是在脚本开头加一行工作目录切换。

资源文件同理。如果 skill 里需要参考某份设计稿、接口文档，可以放在 skill 目录下的references/子目录中，然后在 SKILL.md 正文里说明具体路径。不要把整份文档粘进 SKILL.md，保持 SKILL.md 精简，让 agent 需要时去读完整资源。

3.4 在 VSCode 中验证加载结果

配置完不能只看文件在不在，还要确认 agent 确实加载了。我常用的验证方式是在 agent 对话里直接问它：

“你目前有哪些可用 skills？分别适合什么场景？”

正常的 agent 会列出所有已加载的 skills 及其 description。如果列不出来或明显缺失，说明目录或格式有问题。还可以用一个更直接的测试：故意触发某个 skill 的场景描述，观察 agent 是否按 SKILL.md 里的流程操作。比如我的 frontend-lint skill 触发词是“检查代码”，我就输入“帮我检查一下代码”，看它会不会先跑 eslint 再跑 typecheck。

这一步不能省。很多配置看起来啥都齐了，实际上 agent 根本没读到文件，等到真正需要时才发现在裸奔。

4. 手写一个前端开发 skill：完整案例

4.1 定义触发场景与描述

光讲格式太抽象，我拿自己项目里实际在用的“前端开发 skill”当例子拆解一遍。这个 skill 要解决的核心问题：让 agent 在改前端代码时，能够遵守项目里约定俗成的命名、样式规范，同时减少低级重复错误。

我当时写的 frontmatter 是这样的（为了让触发更准确，迭代过好几个版本）：

--- name: frontend-dev description: 项目前端开发辅助规范。当用户要求“新增组件”“修改页面”“重构前端代码”“实现 UI 交互”时使用。包括目录结构约定、组件命名规则、样式变量使用、状态管理规范。 ---

这里有个经验：description 写得越具体，匹配越准，但也会导致一些相关任务匹配不上。建议先用宽泛的描述跑几天，统计哪些任务没被正确触发，再逐步收紧。不要一上来就写死在很小的范围。

4.2 编写可执行的检查清单

SKILL.md 正文部分，我按照“开发前 → 开发中 → 开发后”三个阶段组织，让 agent 在任意节点介入都能快速定位当前阶段：

# 前端开发规范 ## 开发前 - 确认目标组件属于哪个模块，对应目录为 src/modules/<module>/components - 检查是否已有相似组件，优先复用 - 确认样式是否使用全局 design-tokens，禁止硬编码颜色值 ## 开发中 - 组件命名使用 PascalCase，文件名与组件名一致 - 样式类名使用 BEM 风格，块名与组件名对应 - 状态管理走 store，禁止组件间跨层 props 透传超过两层 ## 开发后 - 运行 npm run typecheck 确认无类型错误 - 运行 npm run lint:eslint 确认无规范错误 - 新增组件需要在 docs/component-list.md 中登记

这些规则不是凭空写的，而是之前 agent 在改代码时反复踩过的坑。整理成 skill 之后，至少不用每次都在对话里重复交代。而且 agent 输出代码的风格明显稳定了，组件命名的随意性大大降低。

4.3 实测中的调整与后续迭代

配置完不是终点，迭代才是常态。我跑了两周后发现了两个问题。

第一，description 里的“状态管理走 store”被 agent 理解成所有组件间通信都必须走 store，导致一些纯展示组件为了传一个 props 值就引入大量模板代码。修改办法是在 SKILL.md 里补充例外说明：“组件内部状态用 ref/reactive，父子组件简单传值直接用 props，跨层级共享状态才走 store”。

第二，检查清单里的命令太长。agent 在真实项目里执行npm run typecheck时，如果依赖没装全，经常卡住。后来我在清单里补了异常分支：“如果 typecheck 报模块缺失错误，先运行 npm install，再重试”。

这种迭代完全在文本层面完成，改 SKILL.md 即可，不用动任何代码。这也是 skills 机制让我觉得舒服的地方——沉淀经验的门槛极低。

5. 配置踩坑实录：我实际遇到的四个问题

5.1 路径分隔符导致技能加载失败

这是我在 Windows 上遇到的第一个坑。我把 macOS 上能正常运行的 skill 目录整个拷贝到 Windows 项目下，结果 agent 完全没有识别到任何技能。排查了一圈才发现，SKILL.md 内部引用的资源路径用的是 macOS 风格的分隔符assets/images/logo.png，Windows 下按这个路径找不到文件，整个 skill 加载失败。

处理办法：在所有 skill 的文档和脚本中，统一使用项目根目录相对路径，并通过 Node.js 的path模块或path.resolve()处理跨平台分隔符。不要在 SKILL.md 里硬编码/或\。Windows 下运行 Nuxt/Vite 等前端工程时，也建议在项目根目录的.npmrc里确认文件路径格式一致。

5.2 frontmatter 不规范导致技能被静默忽略

比起路径问题，这个坑更隐蔽——因为系统不会报错，只是 skill 不生效。我一度以为 agent 本身不支持 skills，差点重装工具。

检查发现：SKILL.md 的 frontmatter 被我写成了 JSON 风格：

{ "name": "my-skill", "description": "my skill" }

而 agent 要求的是 YAML 风格，且字段必须严格对应用法。另外，frontmatter 的首尾要各留一条空行，文件开头不能有 BOM 头。Windows 记事本保存文件时偶尔会加上 BOM，这也会导致解析失败。

后面我统一用手头编辑器保存文件，并在写完 SKILL.md 之后做一个最小验证：在对话里输入技能描述里的触发词，看有没有反应。没有反应时优先查 frontmatter 格式，不要瞎试其他方向。

5.3 缓存吞掉修改

修改 SKILL.md 内容后，发现 agent 还是沿用旧的规则。一开始以为是路径问题，反复查看配置，最后定位到是缓存。

agent 宿主工具在启动时把 skills 列表读进内存，之后虽然会扫描文件变更，但某些版本对文件修改的感知不及时，特别是只改了正文、没改文件更新时间的情况。我的处理办法：每次改完 skill 内容，重启 VSCode 终端里运行的 agent 进程。注意不是刷新页面，而是终止 agent 会话重新启动。

如果还是不行，检查系统 tmp 目录下是否存在该 agent 的缓存文件夹。不同工具缓存位置不同，大概集中在用户目录的隐藏文件夹里。确认后清空缓存，重启 VSCode。

5.4 同名技能的覆盖顺序

当一个技能在全局目录和项目目录存在同名情况时，不同宿主工具的覆盖策略不一样。我在某个项目里自定义了一个code-review技能，想覆盖全局的同名技能，结果发现 agent 依然调用全局版本。

查阅文档后才知道，这个工具在遇到同名技能时，会同时加载但优先使用项目目录下的版本。另一个工具则是直接全局优先。规则差异很大，靠记忆不可靠，最稳妥做法是避免同名。

我现在的命名习惯是给项目特有技能加前缀，比如projectname-lint、projectname-deploy，从源头避免冲突。如果你确实需要同名的“扩展”效果，可以在 description 里注明适合场景，让 agent 根据描述判断用哪个。

6. 我现在的 skills 扩展思路：结构图与图片生成

6.1 结构图类 skills 的写法

很多人在热词里搜“结构图 skills”，因为要让 agent 画架构图、流程图时，输出总是乱糟糟的。我之前也遇到同样问题：让 agent 画一个系统架构图，它直接输出一段 Mermaid 代码，渲染出来层级混乱，配色也不符合团队规范。

后来我把结构图规范写成一个 skill：

--- name: architecture-diagram description: 绘制系统架构图、流程图、时序图。当用户要求“画架构图”“画流程图”“画时序图”时使用。包括图的方向、层级分组、关键节点命名规范。 ---

正文里明确规定了使用的图表工具和语法约束，并附上典型示例。比如要求所有架构图采用自上而下的布局、关键模块使用指定颜色、外部系统必须放在虚线框内。这样 agent 输出的图，基本能保持一个统一风格。

实测效果很好，唯一要注意的是：SKILL.md 里示例代码块过多时，会让 agent 误以为每次都要完整复现，反而忽视当前需求。建议示例只保留一到两个，其余用链接引用到 skill 目录的 references 子目录。

6.2 图片生成类 skills 的控制边界

热词里还有“图片生成 skills”，这个就更有意思了。严格说，图片生成不属于 agent 本身的能力，但我们可以通过 skill 定义一个严格的输出框架，让 agent 调用外部绘图接口或编码工具时，产出的结果贴近你的预期。

我的做法是：在 skill 里定义图片生成的完整参数模板，包括画布尺寸、色彩模式、风格关键词、输出格式，并明确告诉 agent 必须先生成配置 JSON，经用户确认后再调用绘图脚本。这相当于给 agent 加了一层流程控制，避免它跳过配置阶段直接乱生成。

需要注意的边界是：不要把复杂的执行业务逻辑写进 SKILL.md。SKILL.md 应该是“如何思考”的指南，不是“如何执行”的代码。真正要执行的动作，放到单独的脚本文件中，skill 里只用相对路径引用它。

最后分享一个我的个人习惯：SKILL.md 的文件本身用<skill-name>.md这种短名，但目录名保持语义化，比如code-review-checklist/。这样在项目列表里扫一眼就知道哪个技能管什么，查找和维护都方便。Skills 这个东西，配置起来不复杂，真正花心思的是怎么把自己日常的经验整理成结构化的内容。等积累了几个核心技能之后，你会发现 agent 的输出质量提升，远比换一个更大的模型来得实在。