Uv

uv

Use this skill when working with Python projects that use or should use uv.

This skill ensures instructions follow uv-native workflows and avoids common mistakes when mixing Python packaging tools.

Apply this skill when the user:

• mentions uv
• asks about Python dependency management
• asks about environment setup
• asks how to run Python commands or tests
• wants to migrate from pip / poetry / pip-tools
• needs help debugging a broken Python environment
• wants correct Python CLI tool usage

Do not apply when:

• the task is unrelated to Python tooling
• the user explicitly wants a different ecosystem (conda, poetry, pip) without discussing uv
• the question is purely about application design rather than tooling workflow

Invocation heuristics

Prefer this skill when the user:

• mentions uv
• asks about Python dependency or environment management
• shows pyproject.toml, uv.lock, or requirements.txt
• asks how to run tests, scripts, or tools in a uv-managed repo
• is migrating from pip, poetry, or pip-tools to uv

Do not prefer this skill when:

• the user explicitly wants conda, poetry, or raw pip workflows
• the task is about app architecture rather than Python tooling

Hard constraints

In a uv-managed workflow, never default to:

• pip install ...
• python -m venv ...
• source .venv/bin/activate
• poetry add ...
• poetry run ...
• uv pip install ... as the standard dependency workflow

Only use or mention those when the user explicitly asks for them, or when explaining migration/interoperability constraints.

If the repository already mixes workflows, call that out explicitly and recommend a single consistent path.

Mission

Provide correct, minimal uv-native workflows.

The skill should:

1. enforce uv workflow invariants
2. detect mixed-tool anti-patterns
3. give minimal copy-pasteable commands
4. preserve repo structure unless migration is explicitly requested
5. prefer correctness over verbosity

Do not recommend unrelated packages, frameworks, or project architecture.

Core uv mental model

uv is project-centric.

Projects are defined by:

• pyproject.toml
• uv.lock

Workflows revolve around:

• dependency resolution
• environment synchronization
• command execution within the project

uv manages environments automatically.

Manual environment management should not be the default workflow.

The 5 uv invariants

Always follow these rules.

1. Dependency changes use uv commands

Correct:

uv add uv remove

Avoid:

pip install uv pip install

unless the user explicitly asks for pip compatibility.

2. Commands run through uv

Correct:

uv run pytest uv run python script.py uv run python -m module

Avoid defaulting to:

pytest python script.py

when the project is uv-managed.

3. Environments are managed automatically

Do not center workflows around:

python -m venv source .venv/bin/activate

Activation may exist but is not required for normal workflows.

Prefer execution through uv run.

4. Tools use uv tool or uvx

Ephemeral execution:

uvx

Persistent installation:

uv tool install

Avoid recommending:

pip install

for global CLI usage.

5. Do not mix packaging systems

Avoid mixing uv with:

• poetry commands
• pip install workflows
• manual dependency lists as the primary source of truth
• pip-tools compilation as the primary workflow

If a repo mixes systems, identify it and recommend one consistent workflow.

Standard operating procedure

Step 1 — Inspect project state

Check for:

• pyproject.toml
• uv.lock
• existing uv commands in documentation
• requirements.txt
• poetry or pip-tools configuration

Detect if the project is:

• uv-native
• mixed workflow
• legacy pip workflow
• poetry/pdm workflow

Step 2 — Classify the request

Identify the task category:

• initialize uv
• manage dependencies
• run commands
• manage tools
• manage Python versions
• migration to uv
• fix broken workflow
• explain uv concepts

Step 3 — Provide uv-native solution

Return:

• minimal commands
• short explanation when needed
• warnings if anti-patterns exist

Do not redesign the repository unless requested.

Dependency management

Add dependencies:

uv add

Remove dependencies:

uv remove

Import existing dependency lists:

uv add -r requirements.txt

Do not recommend manual editing of dependency lists unless explicitly requested.

Lockfile and environment synchronization

Generate/update lockfile:

uv lock

Synchronize environment:

uv sync

Most normal workflows do not require manual sync commands.

Command execution

Run commands inside the project environment using:

uv run

Examples:

uv run pytest uv run python script.py uv run python -m module

Python version management

Install Python:

uv python install

Pin project Python version:

uv python pin

Tool execution

Temporary execution:

uvx

Persistent installation:

uv tool install

Migration guidelines

1. Identify existing dependency source (requirements.txt, poetry config, pip workflows).
2. Establish pyproject.toml as the canonical project definition.
3. Import dependencies:

uv add -r requirements.txt

1. Replace execution commands:

pytest -> uv run pytest python script.py -> uv run python script.py

1. Remove conflicting documentation.

Anti-pattern detection

Mixed installers (bad):

uv add fastapi pip install sqlalchemy

pip-first workflow in uv project (bad):

pip install requests

Correct:

uv add requests

Manual venv workflow (bad):

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

Preferred:

uv run

pip compatibility misuse:

uv pip exists but should not be the default dependency workflow.

Response style

• minimal commands
• concise explanations
• explicit anti-pattern detection
• no package or framework recommendations

Completion checklist

Before finishing an answer verify:

• commands are uv-native
• no accidental pip workflow slipped in
• commands are minimal and copy-pasteable
• migration advice preserves project structure
• no unrelated packages or frameworks were introduced

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: robhowley
• Source: robhowley/py-pit-skills
• License: MIT

Install and usage instructions live in the source repository linked above.