---

name: add-dep description: Safely install a Python package, verify it imports correctly, and pin it to requirements.txt

Add Dependency Skill

Safely add a new Python dependency to the project with verification and pinning.

When to Use

• User asks to "add", "install", or "use" a new package
• You need to add a dependency for implementing a feature
• Upgrading or changing an existing dependency

Process

Step 1: Install the Package

Copypip install --no-input PACKAGE_NAME

For a specific version:

Copypip install --no-input PACKAGE_NAME==1.2.3

Step 2: Verify Import Works

Copypython -c "import PACKAGE_NAME; print(f'{PACKAGE_NAME.__name__} v{getattr(PACKAGE_NAME, \"__version__\", \"unknown\")} OK')"

For packages with different import names:

Copy# PIL is imported as pillow
python -c "from PIL import Image; print('Pillow OK')"

# sklearn is imported from scikit-learn
python -c "import sklearn; print('scikit-learn OK')"

Step 3: Get Installed Version

Copypip show PACKAGE_NAME | grep Version

Step 4: Pin to requirements.txt

Add the exact installed version to requirements.txt with robust duplicate checking:

Copy# Get the exact version using pip show (not grep which can match partial names)
VERSION=$(pip show PACKAGE_NAME | grep "^Version:" | cut -d' ' -f2)

# Check if package already exists (case-insensitive, any version specifier, handles whitespace)
# Matches: package==1.0, package >= 1.0, package~=1.0, Package==1.0, etc.
if grep -iEq "^PACKAGE_NAME[[:space:]]*[<>=!~\[]" requirements.txt 2>/dev/null || grep -iq "^PACKAGE_NAME$" requirements.txt 2>/dev/null; then
    # Update existing entry (handles optional whitespace around operators)
    sed -i "s/^[Pp][Aa][Cc][Kk][Aa][Gg][Ee]_[Nn][Aa][Mm][Ee][[:space:]]*[<>=!~\[].*/PACKAGE_NAME==$VERSION/I" requirements.txt
    sed -i "s/^[Pp][Aa][Cc][Kk][Aa][Gg][Ee]_[Nn][Aa][Mm][Ee]$/PACKAGE_NAME==$VERSION/I" requirements.txt
    echo "Updated PACKAGE_NAME==$VERSION in requirements.txt"
else
    # Add new entry
    echo "PACKAGE_NAME==$VERSION" >> requirements.txt
    echo "Added PACKAGE_NAME==$VERSION to requirements.txt"
fi

Important Notes:

• Uses case-insensitive matching (-i flag) to catch Requests vs requests
• Handles whitespace around operators (requests >= 2.0 and requests>=2.0)
• Detects any version specifier: ==, >=, <=, ~=, !=, [extras]
• Also catches bare package names without version specifiers
• Do NOT use pip freeze | grep as it can match partial names (e.g., requests matching requests-oauthlib)

Step 5: Verify requirements.txt

Copy# Use case-insensitive match to verify
grep -i "^PACKAGE_NAME" requirements.txt

Common Package Mappings

Some packages have different install and import names:

Example: Adding requests

Copy# 1. Install
pip install --no-input requests

# 2. Verify
python -c "import requests; print(requests.__version__)"

# 3. Pin (with case-insensitive duplicate check, handles whitespace)
VERSION=$(pip show requests | grep "^Version:" | cut -d' ' -f2)
if ! grep -iEq "^requests[[:space:]]*[<>=!~\[]" requirements.txt 2>/dev/null; then
    echo "requests==$VERSION" >> requirements.txt
fi

# 4. Confirm
grep "^requests==" requirements.txt

Output:

Copy2.31.0
requests==2.31.0

Example: Adding pandas with specific version

Copy# 1. Install specific version
pip install --no-input pandas==2.1.0

# 2. Verify
python -c "import pandas as pd; print(pd.__version__)"

# 3. Pin
echo "pandas==2.1.0" >> requirements.txt

Dev Dependencies

For development-only dependencies (testing, linting), add to requirements-dev.txt:

Copypip install --no-input pytest
VERSION=$(pip show pytest | grep "^Version:" | cut -d' ' -f2)
if ! grep -iEq "^pytest[[:space:]]*[<>=!~\[]" requirements-dev.txt 2>/dev/null; then
    echo "pytest==$VERSION" >> requirements-dev.txt
fi

Handling Failures

Installation Fails

Copy# Check if package name is correct
pip search PACKAGE_NAME  # May be disabled

# Try with verbose output
pip install --no-input -v PACKAGE_NAME

Import Fails

Copy# Check installed packages
pip list | grep -i PACKAGE_NAME

# Check for correct import name
pip show PACKAGE_NAME | grep -E "Name|Location"

Version Conflict

Copy# See what's conflicting
pip check

# See dependency tree
pip install --no-input pipdeptree && pipdeptree

Web Environment Notes

In Claude Code Web (headless):

• Always use --no-input flag
• Suppress progress bar with --progress-bar off
• Verify immediately after install (session may restart)

Copypip install --no-input --progress-bar off PACKAGE_NAME && \
python -c "import PACKAGE_NAME; print('OK')"