SKILL.md
$27
Step-by-Step Installation
Run the bundled install script from the workspace root:
bash scripts/install.shCommon Options
Option
Description
--workspace <path>
Path to directory containing package.json (auto-detected if omitted)
--playwright
Also install Playwright Chromium browser for E2E testing
What the Script Does
- Copies
package.json,package-lock.json, and.npmrc(if present) to a local ext4 directory
- Runs
npm ci(ornpm installif no lockfile) on the local filesystem
- Symlinks
node_modulesback into the workspace
- Verifies known native binaries (esbuild, rollup, lightningcss, vite) if present
- Optionally installs Playwright browsers and system dependencies (uses
sudowhen available)
If verification fails, run the script again — crashes can be intermittent during initial setup.
Post-Install Verification
After the script completes, verify your toolchain works. For example:
npm test # Run project tests
npm run build # Build the project
npm run dev # Start dev serverImportant Notes
- The local install directory (e.g.,
/home/agent/project-deps) is container-local and is NOT synced back to the host
- The
node_modulessymlink appears as a broken link on the host — this is harmless sincenode_modulesis typically gitignored
- Running
npm ciornpm installon the host naturally replaces the symlink with a real directory
- After any
package.jsonorpackage-lock.jsonchange, re-run the install script
- Do NOT run
npm ciornpm installdirectly in the mounted workspace — native binaries will crash
Troubleshooting
Problem
Solution
SIGILL or SIGSEGV when running dev server
Re-run the install script; ensure you're not running npm install directly in the workspace
node_modules not found after install
Check that the symlink exists: ls -la node_modules
Permission errors during install
Ensure the local deps directory is writable by the current user
Verification fails intermittently
Run the script again — native binary crashes can be non-deterministic on first load
Vite Compatibility
If your project uses Vite, you may need to allow the symlinked path in server.fs.allow. Add the symlink target's parent directory (e.g., /home/agent/project-deps/) to your Vite config so that Vite can serve files through the symlink.