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. Ifshared/is missing, fetch files via WebFetch fromhttps://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 or 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: trueError 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-820passes deterministicrunIdand exactsummaryArtifactPath- write the summary to the provided
summaryArtifactPath
Standalone mode:
- omit
runIdandsummaryArtifactPath - 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-workersummary artifact written to the managed or standalone path
Version: 1.1.0 Last Updated: 2026-01-10