home / skills / git-fg / thecattoolkit / managing-npm

managing-npm skill

safe

This skill manages npm, pnpm, and bun dependencies using strict CLI commands, ensuring safe additions, updates, audits, and lockfile hygiene.

npx playbooks add skill git-fg/thecattoolkit --skill managing-npm

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: managing-npm
description: "Manages npm, pnpm, and bun dependencies following strict protocols. Use when installing, updating, or auditing packages. Do not use for TypeScript configuration or build tooling."
allowed-tools: [Read, Edit, Bash(npm:*), Bash(pnpm:*), Bash(bun:*), Bash(npx:*)]
---

# Dependency Management Protocol

## Core Principle

**NEVER manually edit `package.json`** for dependency changes. Always use package manager commands.

## Dependency Operations

### Adding Dependencies

```bash
# Production dependency
bun add <package>
pnpm add <package>
npm install <package>

# Dev dependency
bun add -d <package>
pnpm add -D <package>
npm install --save-dev <package>
```

### Removing Dependencies

```bash
bun remove <package>
pnpm remove <package>
npm uninstall <package>
```

### Updating Dependencies

```bash
# Check outdated
bun outdated
pnpm outdated
npm outdated

# Update specific package
bun update <package>
pnpm update <package>
npm update <package>

# Update all (interactive)
pnpm update --interactive
npx npm-check-updates -i
```

## Security Audit

```bash
# Run audit
bun audit
pnpm audit
npm audit

# Auto-fix vulnerabilities
pnpm audit --fix
npm audit fix

# Force fix (breaking changes allowed)
npm audit fix --force
```

## Lockfile Hygiene

1. **Commit lockfiles** (`bun.lockb`, `pnpm-lock.yaml`, `package-lock.json`)
2. **Never delete lockfiles** to resolve conflicts - regenerate properly
3. **Use `--frozen-lockfile`** in CI environments

```bash
# CI install (no lockfile changes)
bun install --frozen-lockfile
pnpm install --frozen-lockfile
npm ci
```

## Quality Gates

- [ ] Dependencies added via CLI, not manual edits
- [ ] Lockfile committed with changes
- [ ] No high/critical vulnerabilities in audit
- [ ] Unused dependencies removed

Overview

This skill manages npm, pnpm, and bun dependencies following strict protocols to keep projects reproducible and secure. It enforces command-line operations for adding, removing, updating, and auditing packages and ensures lockfile hygiene and CI-safe installs. Use it to standardize dependency workflows and reduce package-related risks.

How this skill works

The skill validates that dependency changes are performed through package manager commands rather than manual edits to package.json. It runs package operations (add, remove, update), performs security audits and fixes, and enforces lockfile policies including CI frozen installs. It also produces a simple quality gate checklist to confirm best practices are met.

When to use it

Installing a new production or dev dependency
Removing an unused dependency
Checking for and applying package updates
Running security audits and fixing vulnerabilities
Configuring CI installs to prevent lockfile drift

Best practices

Never edit package.json manually; always use bun/pnpm/npm commands
Commit lockfiles (bun.lockb, pnpm-lock.yaml, package-lock.json) with changes
Use --frozen-lockfile (or npm ci) in CI to avoid unexpected updates
Run audits regularly and address high/critical vulnerabilities promptly
Regenerate lockfiles properly instead of deleting them to resolve conflicts

Example use cases

Add a library as a dev dependency using pnpm add -D jest
Remove a deprecated package with npm uninstall <package>
Run pnpm outdated and pnpm update --interactive to upgrade safely
Run npm audit fix and escalate to npm audit fix --force only after review
Configure CI to run pnpm install --frozen-lockfile to ensure reproducible builds

FAQ

Can I manually edit package.json to change versions?

No. Always use the package manager CLI to add, remove, or update dependencies to keep lockfiles and metadata consistent.

What if a lockfile conflict occurs in a merge?

Do not delete the lockfile. Recreate it by running the appropriate install command and resolve the conflict, then commit the regenerated lockfile.