Safely plan and execute dependency maintenance for JavaScript/TypeScript (npm, pnpm) and GitHub Actions, including npm lockfiles, pnpm workspaces, catalogs, overrides, SHA-pinned action versions, release-age policies, audits, CI validation, Dependabot boundaries, PRs, and GitHub tracking issues. Use whenever the user asks to update, bump, refresh, audit, clean, modernize, or review dependencies or GitHub Actions, reduce vulnerabilities, clean overrides, or prepare dependency PRs/issues.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Safely plan and execute dependency maintenance for JavaScript/TypeScript (npm, pnpm) and GitHub Actions, including npm lockfiles, pnpm workspaces, catalogs, overrides, SHA-pinned action versions, release-age policies, audits, CI validation, Dependabot boundaries, PRs, and GitHub tracking issues. Use whenever the user asks to update, bump, refresh, audit, clean, modernize, or review dependencies or GitHub Actions, reduce vulnerabilities, clean overrides, or prepare dependency PRs/issues.
metadata
{"short-description":"Safe npm/pnpm and GitHub Actions dependency maintenance"}
Dependency Maintenance
Use this workflow to maximize safe dependency progress without changing the repository's package-manager contract or
hiding remaining risk.
Preflight
Read repo instructions first: AGENTS.md, CLAUDE.md, package-specific instructions, and CONTRIBUTING.md.
Detect the package-manager contract from lockfiles, packageManager, CI, deploy config, and package-manager guard
scripts:
npm repo: use npm, preserve package-lock.json, and validate with npm ci.
pnpm repo: use pnpm, preserve pnpm-lock.yaml, pnpm-workspace.yaml, catalogs, and overrides.
Do not introduce a different lockfile, workspace file, package-manager metadata, or install command.
Check branch and worktree state with git status --short --branch. If unrelated changes are present, use an isolated
worktree or avoid touching those files.
Read .nvmrc, , , , deploy config, , and the GitHub Actions pins in
and .
.node-version
engines
.npmrc
dependabot.yml
.github/workflows/*.yml
.github/actions/**/action.yml
Capture the baseline: outdated report, audit report, lockfile state, and relevant validation commands.
Policy
Treat release-age and cooldown rules as hard gates. Compute exact cutoff timestamps before selecting versions.
In pnpm repos, minimumReleaseAge is a maturity window in minutes. Treat the configured minimumReleaseAgeExclude
list as read-only: respect the existing entries, but never add or widen it to push a fresher version through — the
maturity window is a hard gate, not a hurdle to bypass.
Treat npm/pnpm dependency updates as owned by this skill. Do not re-enable Dependabot npm/pnpm package-ecosystem jobs
unless the user explicitly asks.
GitHub Actions are in scope for manual/agent sweeps and for policy enforcement, but Dependabot keeps opening the
routine github-actions PRs: its cooldown in dependabot.yml (7 days) matches the action maturity window, so leave
that job enabled and let the two coexist. Docker and other non-JavaScript ecosystems also stay under Dependabot.
Pin GitHub Actions to a full 40-character commit SHA, never a tag or branch ref (@v4, @main). A movable ref lets
the upstream repo change what runs in CI without review. Append the human-readable version as an end-of-line comment
(uses: actions/checkout@<sha> # v7.0.0) and update that comment on every bump so the SHA stays auditable.
Gate GitHub Actions on release age: only adopt a SHA whose release (tag) is older than 7 days. Actions use a longer
7-day window than the JS/npm/pnpm gate because an action runs with repository scope in CI, so a fresh release is
higher-risk supply-chain surface. Treat the window as a hard gate, not a suggestion.
Pin exact versions (mandatory). Every npm/pnpm dependencies/devDependencies specifier must be an exact pin, never
a ^ caret or ~ tilde range. Floating ranges silently pull unreviewed releases and widen the supply-chain attack
surface, so a single exact version is the only safe and reproducible default. When a bump touches a manifest, also
tighten any pre-existing ^/~ range on that package to an exact pin. The exception is peerDependencies: those
declare the version range a consumer must satisfy (the package never installs them itself), so pinning them exact
invents false incompatibilities — leave intentional peer ranges as ranges.
Preserve reference style otherwise: keep catalog: references, workspace: references, and repo-specific package
placement unchanged. Pin the concrete version at the catalog definition so consumers stay on catalog:.
Default PR scope is eligible patch and minor updates. Major upgrades, risky transitive fixes, and broad migrations get
tracking issues unless the user explicitly approves doing them now.
Prefer official migration guides, changelogs, package registry metadata, and advisory pages for decisions that affect
risk.
Inventory
Build an inventory from direct dependencies, dev dependencies, peer dependencies, optional dependencies, catalogs,
overrides, lockfiles, and audit output.
When registry-age gates matter, use the bundled helper as a reproducible first pass:
node <skill-dir>/scripts/eligible-updates --manager auto --days 3
Replace <skill-dir> with the directory containing this SKILL.md. Adjust --days or --minutes to match the repo
policy.
Triage
Classify every candidate before changing files:
Safe now: patch/minor, older than cutoff, peer-compatible, and locally validatable.
Blocked non-major: too fresh, peer-conflicting, runtime-breaking, upstream-pinned, or requiring nontrivial code/config
migration.
Major migration: semver-major or framework/toolchain migration that needs a dedicated issue.
Audit-only blocked: no patched version, incompatible transitive major, bundled dependency, or upstream package must
move first.
Removable: unused dependency that should be deleted instead of bumped.
Group tightly coupled packages together when separate bumps are likely to create peer, type, or runtime friction.
Apply
Update catalogs before workspace manifests when dependencies are shared through catalog:.
In npm repos, update package.json and regenerate package-lock.json with npm. Prefer lockfile-only install when
appropriate, then validate with clean install.
In pnpm repos, regenerate pnpm-lock.yaml with normal pnpm install flow. Do not bypass minimumReleaseAge.
Preserve package-manager script safety settings such as engine-strict, ignore-scripts, LavaMoat allow-scripts, and
only-allow.
Keep code/config changes minimal and only when required by the dependency update.
If a supposedly safe update breaks validation, revert just that candidate and document why it moved to blocked work.
Overrides
Treat overrides as temporary exceptions:
Remove stale overrides after direct bumps when they no longer affect resolution or audit posture.
Keep or add only targeted overrides that are compatible with the dependent package and materially improve security or
toolchain behavior.
Avoid broad overrides for transitive major jumps unless upstream compatibility is proven.
Document every kept override with package path, advisory or compatibility reason, current resolution, target
resolution, and remaining risk.
Refresh overrides after the direct bumps land, so you only keep exceptions that are still required. Let natural
resolution catch up first, then keep overrides only for advisories that remain. The flow is the same regardless of
package manager, but the exact commands differ, so use the ones in the matching reference file:
Remove the existing overrides block from the package manager's source config. For pnpm, inspect the repo first: the
live block can be top-level overrides in pnpm-workspace.yaml, pnpm.overrides in package.json, or resolutions.
For npm, use overrides in package.json. Do not edit generated lockfile override metadata by hand.
Reinstall so resolution settles without the overrides.
Apply the package manager's audit fix. For npm, run npm audit fix without --force, which stays non-major. For
pnpm, run pnpm audit --fix; on pnpm 10 this can write targeted overrides pinning the patched versions, while older
pnpm versions may require adding targeted exact overrides manually from the remaining audit output. If pnpm edits
minimumReleaseAge, minimumReleaseAgeExclude, or related maturity-gate settings, revert those edits immediately; do
not use audit fix to bypass the maturity gate.
Reinstall again so the lockfile reflects the fixed tree.
Then inspect the result — do not trust the audit fix blindly:
Any advisory still reported needs a deliberate, documented override pinned to an exact version (Policy); anything now
resolved should stay removed.
An audit fix can pin a transitive dependency to a new major. Before keeping such an override, confirm the
dependent package actually supports it; otherwise revert it and track the advisory as blocked (see the transitive-major
rule in references/pnpm.md).
In pnpm repos, minimumReleaseAge also gates overrides: pnpm refuses an exact-version override still inside the
maturity window and can silently fall back to an older in-range version that is still vulnerable. Confirm with
pnpm why <pkg> -r plus a re-audit that the intended patched version actually landed. If the only patched version is
still inside the maturity window, treat the advisory as blocked and track it until the version matures — never widen
minimumReleaseAgeExclude to force it in. If pnpm audit --fix adds such an exclusion, revert it; do not accept the
silent, still-vulnerable fallback or compensate for maturity failures with config changes.
Re-run validation, because dropping or changing overrides can shift transitive versions across the workspace.
See references/pnpm.md and references/npm.md for the per-manager commands (on pnpm 10 pnpm audit --fix rewrites
overrides automatically; npm never writes overrides, so its flow relies on npm audit fix without --force plus
manual targeted overrides).
GitHub Actions
Workflow and composite-action files (.github/workflows/*.yml, .github/actions/**/action.yml) reference third-party
actions. Maintain them on the same lifecycle as packages: inventory, triage by release age, bump, validate.
Inventory the pins with a reproducible first pass:
The helper scans every external uses: pin and, for each action, reports the newest same-major release older than the
cutoff plus its exact commit SHA. It needs an authenticated gh CLI. The action gate is 7 days; adjust
--days/--minutes only if repo policy differs. When the same action is pinned to different SHAs across files, the
report sets conflictingPins and lists each variant — reconcile those before bumping.
Triage each pin:
Safe now: a newer same-major tag whose release is older than the cutoff. Bump both the SHA and the version comment.
Blocked (too fresh): the only newer tag is still inside the maturity window. Keep the current pin, note it, and
re-check after the release matures. Never bump to a release younger than the cutoff.
Pin drift: conflictingPins is true (different SHAs for the same action path). Align every workflow file to one SHA
and comment before applying any bump suggestion.
Comment drift: commentDrift is true (same SHA but different version comments). Align comments before bumping.
Major migration: a semver-major bump (for example a runner or Node baseline change). Track it in an issue instead of
bumping now, unless the user approves the major.
Apply a bump by replacing the SHA and the trailing comment together, so they never drift:
Local actions (uses: ./.github/actions/...) are first-party and need no pin. See references/github-actions.md for the
exact gh commands to resolve a tag to its commit SHA and confirm its release age.
Validation
Run the narrowest meaningful checks first, then broaden by blast radius:
install or clean install
audit after changes
lint, typecheck, build, and tests
repo-specific checks such as Docusaurus prebuild/build, Turbo filters, Prisma generate, Playwright/Storybook browsers,
Docker builds, Foundry/forge, subgraph codegen/tests, or generated-doc checks
for GitHub Actions changes: confirm every external uses: is a 40-character commit SHA with a matching version
comment, and that each bumped release cleared the age gate
If a command cannot run, report why. If CI fails, inspect the actual logs and classify the failure as introduced by the
update, exposed baseline debt, or external/non-actionable.
Open The PR
Open the PR only after local validation is green. Opening a PR is an outward-facing action, so commit the work on a
dedicated branch, then pause and confirm with the user before pushing and creating the PR.
Branch from the repo's base branch and commit with the repository's Conventional Commit format. Match the update set:
npm/pnpm only: stage manifest and lockfile changes together. Use the repo-approved scope (for example
deps(global): refresh dependencies).
GitHub Actions only: stage .github/workflows/*.yml and .github/actions/**/action.yml changes together. Use
deps(actions): refresh GitHub Actions to align with Dependabot's github-actions commit prefix.
Mixed JS and Actions updates: prefer separate commits per ecosystem, or one commit whose message names both scopes
explicitly.
Open a PR.
Open English follow-up issues for deferred major upgrades or blocked migration streams. Each issue should include
official docs, current and target versions, expected code areas, migration plan, validation, rollout risk, and rollback
notes.
Stop And Ask
Pause before contract deployments, public API breakage, package-manager migration, broad refactors, invalid override
trees, or CI failures that suggest a cross-cutting regression.
Additional Resources
For npm/package-lock repositories, read references/npm.md.
For pnpm workspace/catalog/override repositories, read references/pnpm.md.
For GitHub Actions SHA pinning and release-age checks, read references/github-actions.md.
For reproducible release-age inventory, run scripts/eligible-updates (npm/pnpm) or scripts/eligible-actions
(GitHub Actions).
