Python Environment Manager Skill

Trigger On

• The user asks "How do I install a package?" or "Which package manager is this project using?".
• The user requests to add, remove, or update Python dependencies.
• Need to initialize a virtual environment or execute a Python script but unsure whether to use uv run, poetry run, or python.
• The project lacks explicit environment configuration and needs recommendations for suitable tools.

Workflow

1. Perceive:
   • Scan the project root for characteristic files: uv.lock, poetry.lock, pyproject.toml, requirements.txt.
   • Check the system environment to test if tools are installed: execute uv --version or poetry --version.
2. Reason:
   • Determine the tool the project should use based on characteristic files (Priority: uv > Poetry > pip).
   • Check tool availability: If the project is determined to use uv but it's not installed, or if the user wants to switch to uv/Poetry but the environment is not ready, mark it as "Pending Installation".
3. Act:
   • Tool Installation Suggestion: If the tool is not installed, must ask the user first: "Detected that the project uses [Tool Name], but it is not installed in your environment. Would you like me to provide the installation command and assist with the installation?"
   • Output Commands: Provide the correct operation commands for the identified management tool.
   • Execute Changes: If the user agrees to installation or dependency changes, provide CLI commands for user confirmation.

Tooling Commands Reference

1. uv (Recommended: Ultra-fast Tool)

• Detection Criteria: uv.lock exists.
• Installation (Unix/macOS): curl -LsSf https://astral.sh/uv/install.sh | sh
• Installation (Windows): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• Common Commands:
  • uv add <package> (Add package)
  • uv sync (Sync environment)
  • uv run <script.py> (Run script)

2. Poetry

• Detection Criteria: poetry.lock exists or [tool.poetry] in pyproject.toml.
• Installation (Cross-platform): curl -sSL https://install.python-poetry.org | python3 -
• Common Commands:
  • poetry add <package> (Add package)
  • poetry install (Install dependencies)
  • poetry run python <script.py> (Run script)

3. venv + pip (Legacy Standard)

• Detection Criteria: Only requirements.txt or .venv exists.
• Common Commands:
  • pip install <package>
  • pip install -r requirements.txt

Deliver

• Environment Detection Report: Inform the current environment status (e.g., uv installed, poetry.lock detected).
• Installation and Operation Guidance: If tools are missing, proactively ask for installation consent and provide the correct syntax.
• Environment Consistency Check: Ensure provided commands perfectly match the project's existing lock files.

Validate

• Never execute installation commands directly without asking the user.
• Installation commands must distinguish between operating systems (macOS/Linux vs Windows).