uv_skill

Overview

This skill manages Python projects and scripts with the uv toolchain, handling dependencies, virtual environments, lockfiles, and CI/Docker patterns. It helps create or migrate projects to pyproject.toml + uv.lock, run scripts with inline dependencies, use one-off CLI tools via uvx, and configure the IDE to use the project .venv. The guidance emphasizes reproducible environments and recommended uv workflows.

How this skill works

The skill inspects project files (pyproject.toml, requirements.txt, poetry.lock, Pipfile, environment.yml, uv.lock) to choose the correct mode: project, script, tool, or pip-compatible. It issues concrete uv commands (uv init, uv add, uv sync, uv run, uvx, uv tool install, uv python pin) and updates workspace settings to point the IDE at the created .venv. For migrations, it suggests using uvx migrate-to-uv and preserves the lockfile workflow and git-tracked uv.lock.

When to use it

• Creating a new Python project and managing deps with a lockfile
• Converting or migrating from requirements.txt, poetry, pipenv, or conda to uv (ask first)
• Running a single script that needs packages without a full project (inline script metadata)
• Running one-off CLI tools from PyPI using uvx or installing repeatable tools with uv tool install
• Configuring CI (GitHub Actions) or Docker builds to use uv and uv.lock for reproducible installs
• Setting or updating the IDE Python interpreter to the project .venv after uv creates/syncs it

Best practices

• Prefer uv add and uv remove for dependency changes; avoid manual editing of pyproject.toml for deps
• Always commit uv.lock and use uv sync (or uv sync --locked in CI) to ensure parity across machines
• Use uv run for all commands to avoid manual venv activation and ensure the right interpreter is used
• When migrating from other tools, ask the user first and prefer uvx migrate-to-uv to convert metadata and lockfiles
• Keep .venv in .gitignore and set workspace IDE settings (e.g. .vscode/settings.json) to the project .venv path
• For one-off tools prefer uvx; install frequently used tools with uv tool install

Example use cases

• Initialize a new library: uv init mylib && uv add requests && uv sync && uv run pytest
• Add a dependency to an existing project: uv add pandas && uv sync (uv updates uv.lock and the env)
• Run a standalone script with deps: add script metadata or run uv add --script script.py requests; then uv run script.py
• Run a linter once: uvx ruff check . or install for repeated use: uv tool install ruff
• CI job: install uv via astral-sh/setup-uv, cache by uv.lock+pyproject.toml, run uv sync --locked