ln-711-npm-upgrader
Upgrades npm/yarn/pnpm dependencies with breaking change handling
How do I install this agent skill?
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-711-npm-upgraderIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill automates Node.js dependency upgrades and code migrations using standard package managers. It follows typical development workflows, though it includes an inherent surface for indirect prompt injection when processing external documentation.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerpass
1/3 files flagged
What does this agent skill do?
Paths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
ln-711-npm-upgrader
Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader
Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.
Overview
| Aspect | Details |
|---|---|
| Input | Project path, package manager type |
| Output | Updated package.json, lock file, migration report |
| Supports | npm, yarn (classic & berry), pnpm |
Workflow
See diagram.html for visual workflow.
Phases: Pre-flight → Analyze → Security Audit → Check Outdated → Identify Breaking → Apply Upgrades → Apply Migrations → Verify Build → Report
Phase 0: Pre-flight Checks
| Check | Required | Action if Missing |
|---|---|---|
| Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml) | Yes | Warn and run npm install first |
| package.json | Yes | Block upgrade |
Workers assume coordinator (ln-710) already verified git state and created backup.
Phase 1: Analyze Dependencies
Read package.json and categorize dependencies for upgrade priority.
Dependency Categories
| Category | Examples | Priority |
|---|---|---|
| framework | react, vue, angular | 2 (after peer deps) |
| build | vite, webpack, esbuild | 3 |
| ui | @radix-ui/*, tailwindcss | 4 |
| state | @tanstack/react-query, zustand | 5 |
| utils | lodash, date-fns | 6 |
| dev | eslint, prettier, typescript | 7 |
| peer | @types/*, typescript | 1 (first) |
Phase 2: Security Audit
Commands
| Manager | Command |
|---|---|
| npm | npm audit --audit-level=high |
| yarn | yarn audit --level high |
| pnpm | pnpm audit --audit-level high |
Actions
| Severity | Action |
|---|---|
| Critical | Block upgrade, report |
| High | Warn, continue |
| Moderate/Low | Log only |
Phase 3: Check Outdated
Commands
| Manager | Command |
|---|---|
| npm | npm outdated --json |
| yarn | yarn outdated --json |
| pnpm | pnpm outdated --json |
Phase 4: Identify Breaking Changes
Detection
MANDATORY READ: Load breaking_changes_patterns.md for full patterns.
- Compare current vs latest major versions
- Check breaking_changes_patterns.md for known patterns
- Query Context7/Ref for migration guides
Common Breaking Changes
| Package | Breaking Version | Key Changes |
|---|---|---|
| react | 18 → 19 | JSX Transform, ref as prop |
| vite | 5 → 6 | ESM only, Node 18+ |
| eslint | 8 → 9 | Flat config required |
| tailwindcss | 3 → 4 | CSS-based config |
| typescript | 5.4 → 5.5+ | Stricter inference |
Phase 5: Apply Upgrades
Upgrade Order
- Peer dependencies (TypeScript, @types/*)
- Framework packages (React, Vue core)
- Build tools (Vite, webpack)
- UI libraries (after framework)
- Utilities (lodash, date-fns)
- Dev dependencies (testing, linting)
Commands
| Manager | Command |
|---|---|
| npm | npm install <package>@latest --save |
| yarn | yarn add <package>@latest |
| pnpm | pnpm add <package>@latest |
Peer Dependency Conflicts
| Situation | Solution |
|---|---|
| ERESOLVE error | npm install --legacy-peer-deps |
| Still fails | npm install --force (last resort) |
MCP Tools for Migration Search
Priority Order (Fallback Strategy)
| Priority | Tool | When to Use |
|---|---|---|
| 1 | mcp__context7__query-docs | First choice for library docs |
| 2 | mcp__Ref__ref_search_documentation | Official docs and GitHub |
| 3 | WebSearch | Latest info, community solutions |
Context7 Usage
| Step | Tool | Parameters |
|---|---|---|
| 1. Find library | mcp__context7__resolve-library-id | libraryName: "react", query: "migration guide" |
| 2. Query docs | mcp__context7__query-docs | libraryId: "/facebook/react", query: "react 18 to 19 migration" |
MCP Ref Usage
| Action | Tool | Query Example |
|---|---|---|
| Search | mcp__Ref__ref_search_documentation | "react 19 migration guide breaking changes" |
| Read | mcp__Ref__ref_read_url | URL from search results |
WebSearch Fallback
Use when Context7/Ref return no results:
"<package> <version> breaking changes migration {current_year}""<package> <error message> fix stackoverflow"
Phase 6: Apply Migrations
Process
- Use MCP tools (see section above) to find migration guide
- Apply automated code transforms via Edit tool
- Log manual migration steps for user
Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.
Phase 7: Verify Build
Commands
| Check | Command |
|---|---|
| TypeScript | npm run check or npx tsc --noEmit |
| Build | npm run build |
| Tests | npm test (if available) |
On Failure
- Identify failing package from error
- Search Context7/Ref for fix
- If unresolved: rollback package, continue with others
Phase 8: Report Results
Report Schema
| Field | Description |
|---|---|
| project | Project path |
| packageManager | npm, yarn, or pnpm |
| duration | Total time |
| upgrades.major[] | Breaking changes applied |
| upgrades.minor[] | Feature updates |
| upgrades.patch[] | Bug fixes |
| migrations[] | Applied migrations |
| skipped[] | Already latest |
| buildVerification | PASSED or FAILED |
| warnings[] | Non-blocking issues |
Configuration
Options:
# Upgrade scope
upgradeType: major # major | minor | patch
# Breaking changes
allowBreaking: true
autoMigrate: true
queryMigrationGuides: true # Use Context7/Ref
# Security
auditLevel: high # none | low | moderate | high | critical
minimumReleaseAge: 14 # days
# Peer dependencies
legacyPeerDeps: false
force: false
# Verification
runBuild: true
runTests: false
runTypeCheck: true
# Rollback
createBackup: true
rollbackOnFailure: true
Error Handling
| Error | Cause | Solution |
|---|---|---|
| ERESOLVE | Peer dep conflict | --legacy-peer-deps |
| ENOENT | Missing lock file | npm install first |
| Build fail | Breaking change | Apply migration via Context7 |
| Type errors | Version mismatch | Update @types/* |
Rollback
Restore package.json and lock file from git, then run clean install to restore previous state.
References
Definition of Done
- Lock file and package.json verified present
- Dependencies categorized and prioritized (peer deps first)
- Security audit completed (critical blocks upgrade)
- Outdated packages identified via
npm/yarn/pnpm outdated - Breaking changes detected via breaking_changes_patterns.md and MCP tools
- Upgrades applied in priority order with rollback on failure
- Build and type checks pass after upgrades
- Report returned with major/minor/patch counts, migrations, and build status
Version: 1.1.0 Last Updated: 2026-01-10
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/levnikolaevich/claude-code-skills/ln-711-npm-upgrader">View ln-711-npm-upgrader on skillZs</a>