Vibeyard: Add npm Dependency Skill
A project-specific playbook for adding npm dependencies to an Electron app with three build targets, preventing silent breakage of CSS, native modules, and the renderer bundle.
The project's own dependency-addition conventions (Electron three-build-target packaging rules), for its contributors, not a general-purpose skill.
What does this skill do, and when should you use it?
add-npm-dependency is a project-specific Agent Skill in the Vibeyard repository, located at .claude/skills/add-npm-dependency/SKILL.md. It defines the mandatory rules for installing, adding, or upgrading npm dependencies in this Electron project: always install the latest version with a caret range, use npm only, and commit both package. and package-lock.. Its core logic is deciding which build target consumes a package (renderer / main / preload), because the renderer is bundled by esbuild into a single IIFE that forbids Node built-ins and native modules and has no CSS loader, requiring manual stylesheet copying. It also covers native-module postinstall rebuilds, asar unpacking, type installation, and build/test/packaging verification. Note: this is a repository-specific skill that only applies inside the Vibeyard codebase, not a general dependency-management tool.
The skill is an instruction document that guides an AI agent to: install packages with npm install <pkg>@latest while keeping the caret range; classify each dependency by target — renderer (pure JS/TS, esbuild-bundled) vs main/preload (Node/native modules allowed, tsc to CommonJS); for styled libraries (gridstack, @xterm/*), add a CSS copy step in scripts/copy-assets.js and a link tag in index.html; for native modules, rely on the postinstall electron-builder install-app-deps rebuild and add asarUnpack entries when needed; install @types/<pkg> when types are missing; and finally run npm run build and npm test, ensuring runtime deps live in dependencies rather than devDependencies.
What are this skill's strengths and limitations?
- Closely tailored to Vibeyard's real build structure, addressing concrete failure points like esbuild's missing CSS loader and native-module ABI rebuilds.
- Enforces repo conventions: latest version with caret range, npm only, lockfile always committed — reducing human error.
- Includes required verification steps (npm run build + npm test) and a Do/Don't checklist that agents can follow mechanically.
- Points to in-repo precedents (gridstack, better-sqlite3, @types packages) that lower judgment cost.
- Tightly bound to Vibeyard's build structure (three targets, copy-assets.js, .nvmrc) — not reusable in other projects as-is.
- The mandatory always-latest-version policy may conflict with teams that pin exact versions.
- Native modules must compile on macOS, Linux, and Windows; cross-platform risk is explicitly left to the user to watch.
- Effectiveness depends on the connected agent triggering and following the skill; no independent tests or success metrics are provided in the source.
How do you install this skill?
The skill lives in Vibeyard's .claude/skills/ directory (the repo bundles 2 skills; this is one of them). To get it: git clone https://github.com/elirantutia/vibeyard.git — the file is already at .claude/skills/add-npm-dependency/SKILL.md. To reuse it elsewhere, copy the skill folder into your own project's .claude/skills/ directory, but be aware its rules are tailored to Vibeyard's build structure and would need editing. Installing the Vibeyard app itself: download the .dmg (macOS), .deb/.AppImage (Linux), or .exe (Windows) from GitHub Releases, or run npm i -g vibeyard; building from source requires Node v24+.
How do you use this skill?
Inside the Vibeyard project, the skill triggers automatically whenever you ask Claude Code to add, install, or upgrade an npm package (its description marks such tasks as MUST-use), e.g. "install dompurify", "add gridstack as a dependency", or "upgrade better-sqlite3". The agent then follows the skill's six steps: pick the build target, handle CSS/native-module gotchas, add types, and verify with build and test runs. With other clients, supply the SKILL.md content as context to the agent.