Dependencies Skill
Core Philosophy
"Upgrade deliberately; keep lockfiles in sync."
Update dependencies in a controlled way: check compatibility, resolve conflicts, run tests, and commit lockfile changes.
Protocol
1. Understand Ecosystem
| Ecosystem |
Manifest |
Lockfile |
Update commands |
| Node |
package.json |
package-lock.json / yarn.lock / pnpm-lock.yaml |
npm update, npm install <pkg>@latest, yarn upgrade, pnpm update |
| Python |
requirements.txt / pyproject.toml |
requirements.lock / poetry.lock |
pip install -U <pkg>, poetry update, uv lock |
| Go |
go.mod |
go.sum |
go get -u ./... or go get module@version |
| Rust |
Cargo.toml |
Cargo.lock |
cargo update or edit version then cargo build |
| Ruby |
Gemfile |
Gemfile.lock |
bundle update <gem> |
Respect project choice: e.g. npm vs yarn vs pnpm, pip vs poetry vs uv.
2. Upgrade Workflow
- Scope: All deps, or only named packages (and their dependents if needed).
- Update: Use the ecosystem’s update command; avoid editing lockfile by hand.
- Resolve: If there are version conflicts, relax constraints or pick a compatible version; document why.
- Install/build: Run install and build so lockfile and manifests are in sync.
- Test: Run test suite; fix any breakage from API or behavior changes.
- Commit: Commit manifest + lockfile together (and any fix commits).
3. Conflict Resolution
- Node:
npm install or yarn install often suggests fixes; use overrides/resolutions only when necessary and document.
- Python: Resolve version ranges in
requirements.txt or pyproject.toml; regenerate lockfile.
- Go:
go get or fix go.mod; run go mod tidy.
- Rust: Adjust version in
Cargo.toml; cargo update or cargo build.
4. Security / Outdated
- Use ecosystem tools when the user cares about vulnerabilities or outdated deps:
npm audit, yarn audit, pip audit, cargo audit, go list -m -u all, etc.
- Suggest upgrades or patches; don’t auto-fix without user context (e.g. breaking changes).
5. Major Version Upgrades
Major version upgrades often include breaking changes. Follow this strategy:
- Read the changelog - Review all breaking changes, deprecations, and migration guides.
- Check compatibility - Verify that other deps and the app are compatible with the new major.
- Update incrementally - Upgrade one major dep at a time, not all at once.
- Run the full test suite after each upgrade; fix breakage before moving on.
- Document breaking changes - Note what changed and why in the commit message or plan.
6. Supply Chain Security
- Audit regularly: Run
npm audit, pip audit, cargo audit, bundler-audit in CI.
- Pin versions in lockfiles; use exact versions for critical dependencies.
- Review new deps before adding: check maintenance status, download stats, and known vulnerabilities.
- Use lockfiles - Always commit lockfiles; never delete them to "fix" issues.
- Verify checksums - Lockfiles with integrity hashes (npm, yarn) protect against tampered packages.
- Invoke security-reviewer for deep supply chain audit when adding new dependencies to security-sensitive areas.
7. Downgrade Strategy
Sometimes you need to downgrade:
- Regression found - The new version introduces a bug. Pin to the last working version and document.
- Compatibility conflict - Two deps require incompatible versions. Pin the conflicting dep lower and document.
- Always document why a downgrade was necessary (in commit message or lockfile comment).
8. Cross-Skill Integration
| Situation |
Skill to invoke |
| Security vulnerability in dependency |
security-reviewer skill |
| Dependency upgrade breaks tests |
testing skill / debugging skill |
| Dependency upgrade breaks build/CI |
ci-cd skill |
| Major version upgrade with API changes |
code-reviewer skill |
Checklist
1---2name: dependencies3description: Upgrade and manage dependencies: resolve conflicts, update lockfiles, and check compatibility. Use when the user asks to upgrade deps, update packages, fix dependency conflict, or update lockfile.4---56# Dependencies Skill78## Core Philosophy910**"Upgrade deliberately; keep lockfiles in sync."**1112Update dependencies in a controlled way: check compatibility, resolve conflicts, run tests, and commit lockfile changes.1314---1516## Protocol1718### 1. Understand Ecosystem1920| Ecosystem | Manifest | Lockfile | Update commands |21| ---------- | ------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |22| **Node** | `package.json` | `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` | `npm update`, `npm install <pkg>@latest`, `yarn upgrade`, `pnpm update` |23| **Python** | `requirements.txt` / `pyproject.toml` | `requirements.lock` / `poetry.lock` | `pip install -U <pkg>`, `poetry update`, `uv lock` |24| **Go** | `go.mod` | `go.sum` | `go get -u ./...` or `go get module@version` |25| **Rust** | `Cargo.toml` | `Cargo.lock` | `cargo update` or edit version then `cargo build` |26| **Ruby** | `Gemfile` | `Gemfile.lock` | `bundle update <gem>` |2728Respect project choice: e.g. npm vs yarn vs pnpm, pip vs poetry vs uv.2930### 2. Upgrade Workflow31321. **Scope**: All deps, or only named packages (and their dependents if needed).332. **Update**: Use the ecosystem’s update command; avoid editing lockfile by hand.343. **Resolve**: If there are version conflicts, relax constraints or pick a compatible version; document why.354. **Install/build**: Run install and build so lockfile and manifests are in sync.365. **Test**: Run test suite; fix any breakage from API or behavior changes.376. **Commit**: Commit manifest + lockfile together (and any fix commits).3839### 3. Conflict Resolution4041- **Node**: `npm install` or `yarn install` often suggests fixes; use `overrides`/`resolutions` only when necessary and document.42- **Python**: Resolve version ranges in `requirements.txt` or `pyproject.toml`; regenerate lockfile.43- **Go**: `go get` or fix `go.mod`; run `go mod tidy`.44- **Rust**: Adjust version in `Cargo.toml`; `cargo update` or `cargo build`.4546### 4. Security / Outdated4748- Use ecosystem tools when the user cares about vulnerabilities or outdated deps: `npm audit`, `yarn audit`, `pip audit`, `cargo audit`, `go list -m -u all`, etc.49- Suggest upgrades or patches; don’t auto-fix without user context (e.g. breaking changes).5051### 5. Major Version Upgrades5253Major version upgrades often include breaking changes. Follow this strategy:54551. **Read the changelog** - Review all breaking changes, deprecations, and migration guides.562. **Check compatibility** - Verify that other deps and the app are compatible with the new major.573. **Update incrementally** - Upgrade one major dep at a time, not all at once.584. **Run the full test suite** after each upgrade; fix breakage before moving on.595. **Document breaking changes** - Note what changed and why in the commit message or plan.6061### 6. Supply Chain Security6263- **Audit regularly**: Run `npm audit`, `pip audit`, `cargo audit`, `bundler-audit` in CI.64- **Pin versions** in lockfiles; use exact versions for critical dependencies.65- **Review new deps** before adding: check maintenance status, download stats, and known vulnerabilities.66- **Use lockfiles** - Always commit lockfiles; never delete them to "fix" issues.67- **Verify checksums** - Lockfiles with integrity hashes (npm, yarn) protect against tampered packages.68- **Invoke security-reviewer** for deep supply chain audit when adding new dependencies to security-sensitive areas.6970### 7. Downgrade Strategy7172Sometimes you need to downgrade:7374- **Regression found** - The new version introduces a bug. Pin to the last working version and document.75- **Compatibility conflict** - Two deps require incompatible versions. Pin the conflicting dep lower and document.76- **Always document** why a downgrade was necessary (in commit message or lockfile comment).7778### 8. Cross-Skill Integration7980| Situation | Skill to invoke |81|-----------|----------------|82| Security vulnerability in dependency | **security-reviewer** skill |83| Dependency upgrade breaks tests | **testing** skill / **debugging** skill |84| Dependency upgrade breaks build/CI | **ci-cd** skill |85| Major version upgrade with API changes | **code-reviewer** skill |8687---8889## Checklist9091- [ ] Manifest and lockfile both updated and committed.92- [ ] Install/build succeeds; tests pass after upgrade.93- [ ] Conflicts resolved with a clear choice (and comment if non-obvious).94- [ ] Major upgrades or breaking changes called out for the user.95- [ ] Supply chain audit run (npm audit, pip audit, etc.) with no critical vulnerabilities.96- [ ] New dependencies reviewed for maintenance status and security.97- [ ] Downgrades documented with rationale.
micaelmalta