Claude-code-skills ln-823-pip-upgrader

Upgrades Python pip/poetry/pipenv dependencies with breaking change handling. Use when updating Python dependencies.

install

source · Clone the upstream repo

git clone https://github.com/levnikolaevich/claude-code-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/levnikolaevich/claude-code-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills-catalog/ln-823-pip-upgrader" ~/.claude/skills/levnikolaevich-claude-code-skills-ln-823-pip-upgrader && rm -rf "$T"

manifest: skills-catalog/ln-823-pip-upgrader/SKILL.md

source content

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. If
shared/
is missing, fetch files via WebFetch from
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}
.

ln-823-pip-upgrader

Type: L3 Worker Category: 8XX Optimization

Upgrades Python dependencies with automatic breaking change detection.

Overview

Aspect	Details
Input	Project path plus package manager type
Output	Updated dependency manifests and a machine-readable dependency upgrade summary
Supports	pip, poetry, pipenv

Workflow

Phases: Pre-flight -> Detect Manager -> Security Audit -> Check Outdated -> Apply Upgrades -> Verify Installation -> Report

Phase 0: Pre-flight Checks

Check	Required	Action if Missing
`requirements.txt` , `pyproject.toml` , or `Pipfile`	Yes	Block upgrade
Python package manager available	Yes	Block upgrade
Virtual environment active	No	Warn user if managed environment is unclear
Workspace baseline safe	Yes	In managed runs coordinator already prepared it; in standalone runs protect rollback locally

Runtime Coordination

Managed runs receive deterministic

runId

and exact

summaryArtifactPath

from

ln-820

. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

Phase 1: Detect Manager

Manager Indicator Files

pip

requirements.txt

poetry

pyproject.toml

poetry.lock

pipenv

Pipfile

Pipfile.lock

Phase 2: Security Audit

Manager	Command
pip	`pip-audit --json`
poetry	`poetry audit`
pipenv	`pipenv check`

Actions:

Severity	Action
Critical	Block and report
High	Warn and continue
Moderate/Low	Log only

Phase 3: Check Outdated

Manager	Command
pip	`pip list --outdated --format=json`
poetry	`poetry show --outdated`
pipenv	`pipenv update --outdated`

Phase 4: Apply Upgrades

Manager	Command
pip	`pip install --upgrade <package>`
pip (freeze)	`pip freeze > requirements.txt`
poetry	`poetry update`
pipenv	`pipenv update`

MCP Tools for Migration Search

Priority	Tool	When to Use
1	`mcp__context7__query-docs`	First choice for library docs
2	`mcp__Ref__ref_search_documentation`	Official docs and PyPI
3	WebSearch	Latest info and community fixes

Use MCP tools whenever a package upgrade crosses a major version or introduces import errors.

Phase 5: Verify Installation

Check Command

Import smoke test

python -c "import <package>"

Tests

pytest

python -m pytest

Common breaking examples:

MANDATORY READ: Load breaking_changes_patterns.md for shared patterns.

Package	Breaking Version	Key Changes
pydantic	1 -> 2	Compatibility layer required
sqlalchemy	1 -> 2	Query API changes
fastapi	0.99 -> 0.100+	Pydantic v2 alignment

Phase 6: Report Results

Field	Description
`project`	Project path
`packageManager`	pip, poetry, or pipenv
`duration`	Total time
`upgrades[]`	Applied upgrades
`verification`	Import/test verdict
`warnings[]`	Non-blocking issues
`artifact_path`	Durable worker report path, if written

Configuration

Options:
  upgradeType: major          # major | minor | patch
  auditLevel: high
  minimumReleaseAge: 14
  pythonVersion: "3.12"
  useVirtualenv: true
  runTests: true

Error Handling

Error	Cause	Solution
ImportError	Breaking API change	Search current migration docs
Dependency conflict	Version mismatch	Regenerate lock file or rollback offending package

References

Runtime Summary Artifact

MANDATORY READ: Load

shared/references/coordinator_summary_contract.md

Emit a

dependency-worker

summary envelope.

Managed mode:

```
ln-820
```
passes deterministic
```
runId
```
and exact
```
summaryArtifactPath
```
write the summary to the provided
```
summaryArtifactPath
```

Standalone mode:

omit
```
runId
```
and
```
summaryArtifactPath
```

write

.hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-823--{identifier}.json

Monitor (2.1.98+): For install/audit/test commands expected >30s, use

Monitor

. Fallback:

Bash(run_in_background=true)

Definition of Done

Package manager detected from project indicators
Security audit completed for the selected Python manager
Outdated packages identified
Breaking changes checked via patterns plus current docs
Upgrades applied with manifest and lock updates persisted
Import smoke test and required tests succeed
```
dependency-worker
```
summary artifact written to the managed or standalone path

Version: 1.1.0 Last Updated: 2026-01-10