Vibeyard：npm 依赖添加指南 Skill
为 Vibeyard 这类 Electron 三目标构建项目提供添加 npm 依赖的标准流程，避免 CSS、原生模块或渲染端打包被静默破坏。
项目自身的依赖添加规范（Electron 三构建目标的打包规则），服务于该项目贡献者，不是通用技能。
这个 Skill 能做什么，适合哪些场景？
add-npm-dependency 是 Vibeyard 仓库中一个针对本项目定制的 Agent Skill，位于 .claude/skills/add-npm-dependency/SKILL.md。它规定了在该 Electron 项目中安装、添加或升级 npm 依赖时必须遵守的规则：始终安装最新版并保留 ^ 版本范围、只使用 npm、同时提交 package. 和 package-lock.。Skill 的核心逻辑是先判断依赖被哪个构建目标消费（renderer / main / preload），因为 renderer 由 esbuild 打包成单个 IIFE，不支持 Node 内置模块和原生模块，也没有 CSS loader，需要手动复制样式文件。它还覆盖了原生模块的 postinstall 重建、asar 解包、类型声明安装以及构建、测试和打包验证等步骤。注意：这是项目专属 Skill，只在 Vibeyard 代码库内部有效，不是通用的依赖管理工具。
该 Skill 本身是指令文档，指导 AI 代理执行以下操作：用 npm install <pkg>@latest 安装最新版本并保留 ^ 范围；根据依赖用途判断归入 renderer（纯 JS/TS、esbuild 打包）还是 main/preload（可含原生模块、tsc 编译为 CommonJS）；对带样式的库（如 gridstack、@xterm/*）在 scripts/copy-assets.js 中添加 CSS 复制步骤并在 index.html 中加 link 标签；原生模块需触发 electron-builder install-app-deps 重建、必要时加入 asarUnpack；缺类型时安装 @types/<pkg>；最后运行 npm run build 和 npm test 验证，并确认依赖在 dependencies 而非 devDependencies。
- 在 Vibeyard 项目中开发的贡献者，需要添加一个纯 JS/TS 的 UI 库（类似 marked 或 dompurify）时，按流程确认它可被 esbuild 打包进 renderer。
- 贡献者需要安装带样式表的渲染端库时，按照 gridstack 的既有先例手动添加 CSS 复制步骤和 link 标签。
- 贡献者添加 better-sqlite3、node-pty 这类原生模块时，确保只用于 main/preload、通过 postinstall 重建并处理 asar 解包。
- 贡献者升级现有依赖时，遵守'永远装最新版、不手动改 package. 版本'的仓库约定。
- AI 编码代理在 Vibeyard 仓库中被要求'安装某个包'时，自动触发该 Skill，按正确目标与步骤执行，避免静默破坏构建。
这个 Skill 有哪些优点和局限？
- 高度贴合 Vibeyard 实际构建结构，针对 esbuild 无 CSS loader、原生模块 ABI 重建等真实易错点给出明确规则。
- 强制执行仓库约定：最新版 + ^ 范围、npm only、同时提交 lockfile，减少人为失误。
- 包含必做的验证步骤（npm run build + npm test），并以 Do/Don't 清单收尾，易于代理遵循。
- 提供仓库内既有先例（gridstack、better-sqlite3、@types 包）作为参照，降低判断成本。
- 完全绑定 Vibeyard 项目的构建结构（三个构建目标、copy-assets.js、.nvmrc 等），对其他项目不通用。
- 强制'永远安装最新版'的策略可能与需要版本锁定的团队规范冲突。
- 要求原生模块在 macOS、Linux、Windows 三平台编译通过，跨平台风险需使用者自行关注。
- Skill 效果依赖所连接代理正确触发和执行，源材料中未提供独立测试或成功率证据。
如何安装这个 Skill？
该 Skill 属于 Vibeyard 仓库的 .claude/skills/ 目录（该仓库捆绑了 2 个 Skill，此为其一）。安装方式：克隆仓库 git clone https://github.com/elirantutia/vibeyard.git，Skill 文件已随仓库位于 .claude/skills/add-npm-dependency/SKILL.md。若要在自己的项目中复用，需将该 Skill 文件夹复制到自己项目的 .claude/skills/ 目录下，但注意其规则针对 Vibeyard 的构建结构定制，需相应修改。Vibeyard 应用本身的安装：macOS 下载 .dmg，Linux 下载 .deb 或 .AppImage，Windows 下载 .exe，或 npm i -g vibeyard；源码构建需 Node v24+。
如何使用这个 Skill？
在 Vibeyard 项目中让 Claude Code 处理任何涉及添加、安装或升级 npm 包的任务时，该 Skill 会自动触发（其 description 声明 MUST 用于此类任务），例如输入："安装 dompurify"、"给项目添加 gridstack 依赖"或"升级 better-sqlite3"。代理随后会按 Skill 的六步流程执行：判断构建目标、处理 CSS/原生模块注意事项、安装类型、运行构建和测试验证。若在其他客户端使用，将 SKILL.md 内容作为上下文提供给代理即可。