ln-713-pip-upgrader

Upgrades Python pip/poetry/pipenv dependencies with breaking change handling

⭐25stars🔀7forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

The ln-713-pip-upgrader is a specialized Claude skill designed to automate the maintenance of Python environments. It intelligently upgrades dependencies across pip, poetry, and pipenv while proactively identifying and resolving breaking changes through automated documentation searches, security audits, and installation verification.

Use Cases

  • Automated Security Patching: Periodically scanning and upgrading packages to resolve vulnerabilities identified by security audits like pip-audit or poetry audit.
  • Major Version Migrations: Handling complex transitions between major library versions (e.g., Pydantic v1 to v2) by automatically searching for migration guides and verifying API compatibility.
  • Legacy Project Maintenance: Quickly bringing outdated Python projects up to modern standards by resolving dependency conflicts and updating requirements.txt or pyproject.toml files.
  • CI/CD Workflow Enhancement: Integrating automated dependency health checks and upgrades into development pipelines to prevent technical debt and ensure environment stability.
nameln-713-pip-upgrader
descriptionUpgrades Python pip/poetry/pipenv dependencies with breaking change handling

ln-713-pip-upgrader

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader

Upgrades Python dependencies with automatic breaking change detection.


Overview

Aspect Details
Input Project path, package manager type
Output Updated requirements.txt/pyproject.toml
Supports pip, poetry, pipenv

Workflow

See diagram.html for visual 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 OR pyproject.toml OR Pipfile Yes Block upgrade
Virtual environment active No Warn user (risk of system pollution)

Workers assume coordinator (ln-710) already verified git state and created backup.


Phase 1: Detect Manager

Manager Indicator Files
pip requirements.txt
poetry pyproject.toml + poetry.lock
pipenv Pipfile + Pipfile.lock

Phase 2: Security Audit

Commands

Manager Command
pip pip-audit --json
poetry poetry audit (via plugin)
pipenv pipenv check

Actions

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

Phase 3: Check Outdated

Commands

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

Phase 4: Apply Upgrades

Commands

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

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 PyPI
3 WebSearch Latest info, community solutions

Context7 Usage

Step Tool Parameters
1. Find library mcp__context7__resolve-library-id libraryName: "pydantic"
2. Query docs mcp__context7__query-docs query: "pydantic v1 to v2 migration breaking changes"

MCP Ref Usage

Action Tool Query Example
Search mcp__Ref__ref_search_documentation "python pydantic 2 migration guide"
Read mcp__Ref__ref_read_url URL from search results

WebSearch Fallback

Use when Context7/Ref return no results:

  • "<package> python <version> breaking changes migration"
  • "<ImportError message> <package> fix"

Phase 5: Verify Installation

Commands

Check Command
Import test python -c "import <package>"
Tests pytest or python -m pytest

Phase 6: Report Results

Report Schema

Field Description
project Project path
packageManager pip, poetry, or pipenv
duration Total time
upgrades[] Applied upgrades
verification PASSED or FAILED

Common Breaking Changes

See breaking_changes_patterns.md for full patterns.

Package Breaking Version Key Changes
pydantic 1 → 2 V1 compatibility layer needed
sqlalchemy 1 → 2 Query syntax changes
fastapi 0.99 → 0.100+ Pydantic v2 required

Configuration

Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Security
  auditLevel: high
  minimumReleaseAge: 14

  # Python specific
  pythonVersion: "3.12"
  useVirtualenv: true

  # Verification
  runTests: true

Error Handling

Error Cause Solution
ImportError Breaking API change Search Context7/Ref for migration
Dependency conflict Version mismatch Try pip-compile or poetry lock

References


Version: 1.1.0 Last Updated: 2026-01-10