Python Venv

---

name: python-venv description: "Python environment management skill. Automatically detect project type and existing environments, recommend based on popularity. Minimize interruptions, only ask when necessary."

---

Python Environment Management Skill

Core Principles

1. Reuse Existing Environments - Don't recreate, reuse existing virtual environments 2. Use Project-Type Decision - Auto-select based on lock files 3. Recommend by Popularity - uv > pip > conda > venv 4. Minimize Interruption - Only ask when necessary

---

Tool Popularity Ranking

| Priority | Tool | Best For | |----------|------|----------| | 🥇 | uv | New projects, fast installs | | 🥈 | pip | Compatibility first | | 🥉 | conda | Data science, specific versions | | 4 | venv | Built-in, no extra install | | 5 | poetry | Existing poetry.lock | | 6 | pipenv | Existing Pipfile (declining) |

---

Decision Flow

┌─────────────────────────────────────┐
│  Detect project dependency files     │
└─────────────────────────────────────┘
              ↓
    ┌─────────┴─────────┐
    ↓                   ↓
  Clear decision       Unclear
    ↓                   ↓
  Use directly     Detect existing env
                        ↓
                  ┌─────┴─────┐
                  ↓           ↓
              Has env        No env
                  ↓           ↓
              Reuse      Assess complexity
                            ↓
                  ┌─────────┴─────────┐
                  ↓                   ↓
              Simple task       Needs deps
                  ↓                   ↓
            System Python      Recommend uv/conda

---

1. Clear Decisions (Execute Directly, No Ask)

When these files are detected, use the corresponding tool directly:

| Detected File | Execute | |--------------|---------| | uv.lock exists | uv sync or uv pip install -r requirements.txt | | poetry.lock exists | poetry install | | environment.yml exists | conda env create -f environment.yml | | Pipfile.lock exists | pipenv install |

---

2. Detect Existing Environments (Reuse First)

# Priority: uv venv > conda > venv
2.1 Detect uv virtual environment
ls -la .venv/ 2>/dev/null && uv pip list 2>/dev/null | head -3
2.2 Detect conda environment
conda info --envs 2>/dev/null | grep "*" || echo $CONDA_PREFIX
2.3 Detect standard venv
ls -la venv/ .venv/ env/ 2>/dev/null
2.4 If exists → Reuse (activate and run commands)

Reuse Example:

Detected existing .venv/ directory
→ Activate: source .venv/bin/activate
→ Run: uv pip install 

---

3. When Unclear (Assess Complexity)

| Scenario | Action | |----------|--------| | Stdlib only, no 3rd party | System Python (python3) | | Simple pip install test | System Python (temp) | | Has requirements.txt | Recommend uv > pip > venv | | Has pyproject.toml | Recommend uv > pip | | Multi-file project, needs isolation | Recommend uv |

---

4. When to Ask User (Only These Cases)

✅ Ask: 1. Empty project + first dependency install → Ask which tool 2. Both requirements.txt + pyproject.toml → Ask which to use 3. User explicitly wants different tool → e.g., "I want conda"

❌ Don't Ask:

Has uv.lock but user didn't specify

Has .venv/ directory

Regular pip install task

---

5. Recommended Tool (No Clear Directive)

First: uv
  ├── uv venv (create)
  ├── uv pip install (install)
  └── uv sync (sync)
Backup: pip
  ├── python3 -m venv .venv
  └── pip install
Special: conda
  ├── conda create -n envname python=x.x
  └── conda env create

---

Detection Commands

# Check available tools
which uv
which conda
which pip
which python3
Check project files
ls -la *.lock pyproject.toml requirements.txt environment.yml Pipfile 2>/dev/null
Check existing environments
ls -la .venv/ venv/ env/ 2>/dev/null
conda info --envs 2>/dev/null
Check current environment
echo $VIRTUAL_ENV
echo $CONDA_PREFIX

---

Interaction Examples (Only When Needed)

🔍 Detection result:
Project file: pyproject.toml
Existing env: None
Recommended: uv (fastest)
Running: uv pip install 

🔍 Detection result:
Project file: requirements.txt
Existing env: None
Recommended: uv
Available options:
1) uv (recommended) - faster
2) pip - better compatibility
3) venv - uses stdlib
4) conda - if specific version needed
Enter option or press Enter to use recommended:

---

Quick Command Reference

| Action | uv | pip | conda | venv | |--------|-----|-----|-------|------| | Create env | uv venv | - | conda create | python3 -m venv | | Install pkg | uv pip install | pip install | conda install | pip install | | Install deps | uv sync | pip install -r | conda env create | pip install -r | | Activate | (auto) | (auto) | conda activate | source venv/bin/activate |

---

Core Principle

"Do more, ask less" - Execute directly when you can determine, only ask when truly unclear.