Skip to content
dependency-upgrade · claude-skills · Flowy
Secure dependency upgrades with supply chain protection, cooldowns, and staged rollout. Use when upgrading deps, configuring security policies, or preventing supply chain attacks.
One skill from claude-skills .
$ npx -y skills add secondsky/claude-skills --skill dependency-upgrade --agent claude-codeInstalls just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itself Claude auto-loads it when your prompt matches the work. You can call it Invoke it directly when you want it. Slash command /dependency-upgrade👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Secure dependency upgrades with supply chain protection, cooldowns, and staged rollout. Use when upgrading deps, configuring security policies, or preventing supply chain attacks. 📦 Ships with claude-skills
</> SKILL.md
dependency-upgrade.SKILL.md
---
name : dependency-upgrade
description : "Secure dependency upgrades with supply chain protection, cooldowns, and staged rollout. Use when upgrading deps, configuring security policies, or preventing supply chain attacks."
license : MIT
---
# Dependency Upgrade
Manage dependency upgrades with supply chain security, compatibility analysis, staged rollout, and comprehensive testing across all major package managers.
## When to Use This Skill
- Upgrading major framework or library versions
- Configuring supply chain attack prevention (cooldown, script blocking, lockfile hardening)
- Setting up secure package manager configuration
- Resolving dependency conflicts or peer dependency issues
- Planning incremental upgrade paths with testing
- Automating dependency updates with Renovate, Dependabot, or Snyk
- Auditing dependencies for vulnerabilities
- Setting up CI/CD dependency security workflows
## Two Modes of Operation
**Interactive** — Walk through setup questions to generate tailored config. Use for fresh setup.
**Default** — Apply recommended defaults immediately: 7-day cooldown, block all scripts, frozen-lockfile, lockfile-lint, Dependabot with cooldown. Customization optional.
## Interactive Setup Flow
Flowy AI Flows that just work. Hand-picked Claude Code plugins that fire the right skill as you prompt.
When the user wants tailored configuration, walk through these decisions. Skip this section entirely if using default mode.
### Tier 1: Required Decisions
Always ask these 3 questions before generating any config:
**1. Package Manager**
"Which package manager does this project use?"
| Answer | Generates |
|--------|-----------|
| npm | `.npmrc` |
| Bun | `bunfig.toml` |
| pnpm | `pnpm-workspace.yaml` |
| Yarn | `.yarnrc.yml` |
| Deno | `deno.json` config |
**2. Cooldown Period**
"How many days should newly published packages age before install? This prevents supply chain attacks where malicious packages are discovered and unpublished within days."
| Option | Days | Use Case |
|--------|------|----------|
| Aggressive | 3 | Catches most typosquatting |
| Recommended | 7 | Good balance for most projects |
| Conservative | 14 | Critical/production systems |
| Paranoid | 21 | Matches Snyk's built-in default |
| Custom | N | User specifies |
**3. Post-Install Script Policy**
"How should lifecycle scripts (postinstall, preinstall) be handled? These are the #1 attack vector for supply chain attacks."
| Option | Behavior |
|--------|----------|
| Block all (recommended) | `--ignore-scripts` + allow-git=none |
| Allowlist | Block by default, allow specific trusted packages |
| Review only | Warn but don't block |
### Tier 2: Security Tooling (Offer as Batch)
"Which of these security features would you like to configure? Select any that apply."
**4. CI/CD Automation Tool**
| Answer | Generates |
|--------|-----------|
| Dependabot | `.github/dependabot.yml` with cooldown |
| Renovate | `renovate.json` with minimumReleaseAge |
| Snyk | No config needed (21-day cooldown built-in) |
| None | Skip |
**5. Automerge Policy**
| Option | Behavior |
|--------|----------|
| None | All updates require manual review |
| Minor+Patch only | Auto-merge safe updates, review majors |
| All with approval | Auto-merge after team approval |
**6. Update Schedule**
| Option | Config Value |
|--------|-------------|
| Daily | `"daily"` |
| Weekly (default) | `"weekly"` |
| Biweekly | `"biweekly"` |
| Monthly | `"monthly"` |
**7. Install-Time Security Tooling**
"Which security tools should protect dependency installation?"
| Option | Free? | What It Does |
|--------|-------|-------------|
| socket npm wrapper | Yes (beta) | Wraps npm/npx, blocks malicious packages before install. Run `socket wrapper on` to enable system-wide. |
| npq | Yes | Pre-install auditor (CVE, typosquat, age, provenance checks) |
| Socket Firewall (sfw) | No | Real-time deep analysis, blocks malicious packages |
| socket npm + npq | Yes | Both free tools combined |
| None | — | Skip |
Load `references/socket-cli-guide.md` for full Socket CLI setup including authentication and free vs authenticated features.
**8. Lockfile Validation**
| Option | Behavior |
|--------|----------|
| Yes (recommended) | Adds `lockfile-lint` + CI script |
| No | Skip |
### Tier 3: Advanced Options (Only If User Opts In)
"Would you like to configure any advanced options?"
**9. Dev Containers** — Generate hardened `.devcontainer/devcontainer.json` (Yes/No)
**10. Secrets Manager** — 1Password CLI / Infisical / None
**11. pnpm Trust Policy** — Enable `trustPolicy: no-downgrade` (pnpm 10.21+ only, Yes/No)
**12. Cooldown Exclusions** — Package names that bypass cooldown (e.g., `@types/react`, `typescript`, `esbuild`)
## Security-First Upgrade Principles
1. **Cooldown before installing** — Wait 7 days for new package versions to be vetted by the community
2. **Block post-install scripts** — Prevent arbitrary code execution during `npm install`
3. **Freeze lockfiles in CI** — Use deterministic installs (`npm ci`, `--frozen-lockfile`)
4. **Validate lockfile integrity** — Use `lockfile-lint` to detect injection
5. **Audit before trusting** — Use `npq` or Socket CLI to check packages before installing
6. **Upgrade incrementally** — One major version at a time with testing between each
7. **Never blindly upgrade** — Avoid `npm update` or `npm-check-updates -u` without review
8. **Scan before and after** — Use `socket scan` to detect supply chain issues beyond CVEs
## Cooldown Period: Prevent Supply Chain Attacks
Newly published packages may contain malicious code discovered within hours. Configure a cooldown period to delay installation.
### Quick Setup
**npm** (`.npmrc`):
```ini
min-release-age=7
```
**Bun** (`bunfig.toml`):
```toml
[install]
minimumReleaseAge = 604800 # 7 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
```
**pnpm** (`pnpm-workspace.yaml`):
```yaml
minimumReleaseAge: 10080 # 7 days in minutes
minimumReleaseAgeExclude:
- '@types/react'
- typescript
```
**Yarn** (`.yarnrc.yml`):
```yaml
npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
- "@types/react"
- "typescript"
```
Load `references/cooldown-config-guide.md` for detailed per-PM configuration, CI tool integration, and exclusion patterns.
Use `templates/<pm>-security.tmpl` for copy-paste ready config files.
## Disable Post-Install Scripts
Post-install scripts are the most common supply chain attack vector (Shai-Hulud, Nx, event-stream incidents).
### Quick Setup
**npm**:
```bash
npm config set ignore-scripts true
npm config set allow-git none
```
**Bun**: Disabled by default. Allow specific packages in `package.json`:
```json
{ "trustedDependencies": ["esbuild", "sharp"] }
```
**pnpm (10.0+)**: Disabled by default. Allow specific packages in `pnpm-workspace.yaml`:
```yaml
allowBuilds:
esbuild: true
strictDepBuilds: true # Hard error on unreviewed scripts
```
Load `references/package-manager-security.md` for full per-PM hardening including pnpm `trustPolicy`, `blockExoticSubdeps`, and `@lavamoat/allow-scripts`.
## Deterministic & Frozen Installs
Always use frozen install commands in CI to ensure reproducible builds:
| Package Manager | Command | What It Does |
|----------------|---------|-------------|
| npm | `npm ci` | Deletes node_modules, installs exact lockfile versions |
| Bun | `bun install --frozen-lockfile` | Fails if lockfile is out of sync |
| pnpm | `pnpm install --frozen-lockfile` | Fails if lockfile is out of sync |
| Yarn | `yarn install --immutable --immutable-cache` | Validates lockfile and cache |
| Deno | `deno install --frozen` | Frozen installation |
Commit all lockfiles to version control: `package-lock.json`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `deno.lock`.
## Lockfile Validation
Install and configure `lockfile-lint` to detect lockfile injection attacks:
```bash
npm install --save-dev lockfile-lint
```
```json
{
"scripts": {
"lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
"preinstall": "npm run lint:lockfile"
}
}
```
Note: `lockfile-lint` does not currently support Bun's `bun.lock` / `bun.lockb` formats.
## Pre-Install Security Auditing
### npq — Pre-Install Auditor
```bash
npm install -g npq
npq install <package> # Audit before installing
npq install <package> --dry-run # Audit without installing
# Shell alias for seamless use
alias npm='npq-hero'
# Use with other PMs
NPQ_PKG_MGR=pnpm npq install <package>
NPQ_PKG_MGR=bun npq install <package>
```
### Socket Firewall (sfw) — Real-Time Blocker
```bash
npm install -g sfw
sfw npm install <package> # Blocks malicious packages
sfw pnpm add <package>
sfw yarn add <package>
```
Load `references/supply-chain-security.md` for full comparison of npq vs sfw and what each validates.
## Socket CLI Integration
Socket CLI provides proactive supply chain security beyond basic vulnerability scanning — covering malware detection, typosquatting, protestware, install script risks, and license compliance.
### Proactive Upgrade Workflow
```
1. PRE-UPGRADE: socket scan create --report → establish baseline
2. EVALUATE: socket package score npm <pkg>@<ver> → assess target package safety
3. SAFE INSTALL: socket npm install <pkg> → block malicious packages
4. POST-UPGRADE: socket scan create --report → verify no new alerts
5. DIFF: socket scan diff <before> <after> → see exactly what changed
6. FIX: socket fix --minimum-release-age 7d → auto-fix any new CVEs
7. OPTIMIZE: socket optimize → apply security overrides
```
### Quick Reference
```bash
# Install
npm install -g socket
# Authenticate (required for scans, fixes, package scores)
socket login
# Check a package before upgrading
socket package score npm <package>
# Scan your whole project
socket scan create --report
# Auto-fix CVEs (complements Dependabot/Renovate)
socket fix --minimum-release-age 7d
# Gate CI on security policy
socket ci
# Safe npm wrapper (free, no auth needed)
socket wrapper on
```
Load `references/socket-cli-guide.md` for comprehensive command reference, CI workflow templates, alert categories, and free vs authenticated feature matrix.
## Dependency Analysis
```bash
# Audit for vulnerabilities
bun audit # Bun
npm audit # npm
yarn audit # Yarn
# Socket: deep security assessment (CVEs + supply chain + license)
socket package score npm <package>
socket scan create --report
# Check for outdated packages
bun outdated
npm outdated
# Interactive upgrade (safe — review each)
bunx npm-check-updates --interactive
# Analyze dependency tree
npm ls <package-name>
yarn why <package-name>
```
## Staged Upgrade Strategy
Upgrade one dependency at a time with testing between each:
```bash
# 1. Create feature branch
git checkout -b upgrade/<package>-<version>
# 2. (Optional) Baseline scan — capture current state
socket scan create --report
# 3. Evaluate target package before upgrading
socket package score npm <package>@<version>
# 4. Upgrade single package
bun add <package>@<version>
# 5. Test immediately
bun test && bunx tsc --noEmit && bun run build
# 6. (Optional) Post-upgrade scan — verify no new alerts
socket scan create --report
# 7. Commit and continue
git add -A && git commit -m "chore: upgrade <package> to <version>"
```
Load `references/staged-upgrades.md` for codemod automation, custom migration scripts, and peer dependency handling.
Load `references/compatibility-matrix.md` for version compatibility tables (React 18/19, Next.js 13-15, TypeScript, Tailwind 3/4).
## Automated Updates with Cooldown
Configure CI/CD tools to respect cooldown periods:
### Dependabot (`.github/dependabot.yml`)
```yaml
version : 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
```
### Renovate (`renovate.json`)
```json
{
"extends": ["config:base"],
"minimumReleaseAge": "7 days",
"packageRules": [
{
"matchUpdateTypes": ["minor", "patch"],
"automerge": true
},
{
"matchUpdateTypes": ["major"],
"automerge": false,
"minimumReleaseAge": "14 days"
}
]
}
```
### Snyk
Snyk includes a built-in 21-day cooldown for upgrade PRs. No configuration needed.
### Socket Fix (complements Dependabot/Renovate)
Socket Fix automatically resolves CVEs with intelligent upgrade planning. Runs alongside other automation tools — it focuses on CVE remediation specifically:
```bash
# Fix all fixable CVEs with cooldown alignment
socket fix --minimum-release-age 7d
# Conservative: no major version bumps
socket fix --minimum-release-age 7d --no-major-updates
# Target specific CVEs
socket fix --id GHSA-hhq3-ff78-jv3g --minimum-release-age 7d
# Preview without applying
socket fix --no-apply-fixes --minimum-release-age 7d
```
For CI autopilot mode (auto-creates and auto-merges fix PRs), use `templates/socket-fix-ci.tmpl`.
Load `references/socket-cli-guide.md` for full `socket fix` options including `--autopilot`, `--range-style`, and `--pr-limit`.
Use `templates/dependabot-security.tmpl` or `templates/renovate-security.tmpl` for complete config files.
## Publishing Security
For package maintainers:
```bash
# Enable 2FA
npm profile enable-2fa auth-and-writes
# Publish with provenance (cryptographic build proof)
npm publish --provenance
# Trusted publishing via OIDC (eliminates long-lived tokens)
# Configure on npmjs.com, then:
# In GitHub Actions: permissions: id-token: write
```
Load `references/supply-chain-security.md` for full publishing security guide including OIDC setup and dependency tree reduction.
## Dev Environment Hardening
Isolate dependency execution from the host system:
- **Dev containers** — limit blast radius of malicious packages
- **Secrets management** — use 1Password CLI or Infisical instead of plaintext `.env` files
- **Dependency tree reduction** — replace common packages with native JS
Use `templates/devcontainer-security.tmpl` for a hardened dev container config.
Load `references/secrets-and-containers.md` for dev container setup, secrets management, and dependency reduction patterns.
## Testing Strategy
Run tests at every level after each upgrade:
```bash
# 1. Static analysis (fastest)
bunx tsc --noEmit && bun run lint
# 2. Unit tests
bun test
# 3. Build check
bun run build
# 4. Integration / E2E (after major upgrades)
bun run test:e2e
```
Load `references/testing-strategy.md` for full testing pyramid, CI integration, and bundle analysis.
## Rollback Plan
```bash
#!/bin/bash
git stash
git checkout -b upgrade/<package>
bun add <package>@latest
if bun test && bun run build; then
git add package.json bun.lock
git commit -m "chore: upgrade <package>"
else
echo "Upgrade failed, rolling back"
git checkout main
git branch -D upgrade/<package>
bun install
fi
```
## Upgrade Checklist
```markdown
Pre-Upgrade:
- [ ] Review current dependency versions
- [ ] Read changelogs for breaking changes
- [ ] Create feature branch
- [ ] Tag current state (git tag pre-upgrade)
- [ ] Run full test suite (baseline)
- [ ] Verify cooldown period is configured
Security Pre-Checks:
- [ ] Post-install scripts are disabled
- [ ] Lockfile validation is active
- [ ] Install auditing tools configured (if applicable)
- [ ] CI uses frozen-lockfile install
- [ ] Run `socket scan create --report` for baseline (if Socket available)
During Upgrade:
- [ ] Upgrade one dependency at a time
- [ ] Check target package: `socket package score npm <pkg>` (if Socket available)
- [ ] Respect cooldown period (don't force latest)
- [ ] Update peer dependencies
- [ ] Fix TypeScript errors
- [ ] Run test suite after each upgrade
- [ ] Check bundle size impact
Post-Upgrade:
- [ ] Post-upgrade scan: `socket scan diff` to verify no new alerts (if Socket available)
- [ ] Consider `socket fix --minimum-release-age 7d` for any new CVEs
- [ ] Full regression testing
- [ ] Performance testing
- [ ] Update documentation
- [ ] Deploy to staging
- [ ] Monitor for errors
- [ ] Deploy to production
```
## Common Pitfalls
- Upgrading all dependencies at once (use incremental upgrades)
- Blindly running `npm update` or `npm-check-updates -u` without review
- Not testing after each individual upgrade
- Ignoring peer dependency warnings
- Forgetting to update or commit the lock file
- Not reading breaking change notes in changelogs
- Skipping major versions instead of stepping through them
- Not having a rollback plan
- Trusting npmjs.org displayed source code (can differ from actual tarball)
- Leaving post-install scripts enabled (most common attack vector)
- Not configuring a cooldown period for new package versions
## When to Load References
Load these reference files when the user needs detailed information beyond the quick-reference in SKILL.md:
| Load This File | When |
|---------------|------|
| `references/cooldown-config-guide.md` | Configuring cooldown for a specific PM, CI tool integration, or exclusion patterns |
| `references/package-manager-security.md` | Full per-PM hardening guide including pnpm trust policy, blockExoticSubdeps, cross-PM cheat sheet |
| `references/supply-chain-security.md` | Understanding attack vectors, incident history, npq vs sfw vs Socket CLI comparison, publisher security (2FA, provenance, OIDC) |
| `references/secrets-and-containers.md` | Setting up dev containers, secrets management with 1Password/Infisical |
| `references/socket-cli-guide.md` | Using Socket CLI for scans, fixes, package scoring, CI integration, wrapper mode, alert categories |
| `references/compatibility-matrix.md` | Checking version compatibility for React, Next.js, TypeScript, Tailwind upgrades |
| `references/staged-upgrades.md` | Codemod automation, custom migration scripts, peer dependency handling, workspace upgrades |
| `references/testing-strategy.md` | Full testing pyramid, CI integration, bundle analysis, performance testing |
## Template Files
Ready-to-use config files in `templates/`:
| Template | Purpose |
|----------|---------|
| `npmrc-security.tmpl` | Secure `.npmrc` with scripts disabled + cooldown |
| `bunfig-security.tmpl` | Secure `bunfig.toml` with cooldown + exclusions |
| `pnpm-workspace-security.tmpl` | Secure `pnpm-workspace.yaml` with cooldown, allowBuilds, trustPolicy |
| `yarnrc-security.tmpl` | Secure `.yarnrc.yml` with age gate + preapproved packages |
| `dependabot-security.tmpl` | Dependabot config with 7-day cooldown |
| `renovate-security.tmpl` | Renovate config with minimumReleaseAge + automerge rules |
| `devcontainer-security.tmpl` | Hardened dev container with security options |
| `socket-fix-ci.tmpl` | GitHub Actions: Socket Fix autopilot with cooldown-aligned CVE remediation |
| `socket-scan-ci.tmpl` | GitHub Actions: Socket CI security gate for every push/PR |
© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic
