最近折腾 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项目代码规范ESLint 规则、目录结构约定、命名风格纯知识型按任务触发不占常驻上下文提交前检查流程跑单测、查类型、检查敏感信息流程固定可沉淀成 checklist工具链用法内部 CLI 命令、构建脚本参数文档经常变更新 skill 即可不用改 prompt领域业务知识支付流程、权限模型、状态机定义新成员/agent 都能快速上手代码生成模板新页面、新接口、新组件的脚手架把范式固化成模板输出稳定不适合用 skills 的场景我也列一下需要实时查询的操作、高度依赖用户当前输入且每次差异很大的任务、超长且很少复用的分析工作。这些用 MCP 或普通对话更合适。2. 环境准备VSCode 侧要满足的三个前置条件2.1 把终端和 shell 环境统一看着是废话但这是我踩得最深的坑。配置 skills 涉及创建目录、写文件、在终端里执行 agent 命令不同 shell 环境下路径规则不一样很容易出问题。我的建议是无论 macOS 还是 Windows都在 VSCode 里固定一个默认终端。macOS 用 zshWindows 用 PowerShell 7不要用 Windows PowerShell 5.1编码问题会让你怀疑人生。设置方式CtrlShiftP打开命令面板搜索“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 youexample.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.pngWindows 下按这个路径找不到文件整个 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 的输出质量提升远比换一个更大的模型来得实在。