Agent skill

uv

Python package manager and project tooling using uv. Use when working with Python projects, managing dependencies, creating virtual environments, running Python scripts, configuring workspaces/monorepos, or troubleshooting uv issues. Triggers on pyproject.toml projects, uv commands, pip replacement workflows, Python version management, workspace configuration, or CI/CD Python setup.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/stickystyle/claude-skills/tree/main/skills/uv

SKILL.md

uv Field Manual

Assumption: uv is already installed and available on PATH.

Sanity Check

bash
uv --version               # verify installation; exits 0

If the command fails, halt and report to the user.

Project ("cargo-style") Flow

bash
uv init myproj                     # create pyproject.toml + .venv
cd myproj
uv add ruff pytest httpx           # fast resolver + lock update
uv run pytest -q                   # run tests in project venv
uv lock                            # refresh uv.lock (if needed)
uv sync --locked                   # reproducible install (CI-safe)

Workspaces (Monorepo)

Workspaces organize large codebases by splitting them into multiple packages with shared dependencies and a single lockfile.

Workspace root pyproject.toml:

toml
[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["shared-lib", "requests"]

[tool.uv.sources]
shared-lib = { workspace = true }    # resolve from workspace

[tool.uv.workspace]
members = ["packages/*"]             # glob patterns supported
exclude = ["packages/experimental"]  # optional exclusions

Workspace member (packages/shared-lib/pyproject.toml):

toml
[project]
name = "shared-lib"
version = "0.1.0"
dependencies = ["pydantic"]

Key commands:

bash
uv init mylib --package             # add new member to existing workspace
uv lock                             # locks entire workspace
uv sync                             # syncs workspace root by default
uv run --package shared-lib pytest  # run in specific member
uv sync --all-packages              # sync all members into .venv
uv sync --no-install-workspace      # deps only (good for Docker layers)

Behaviors:

  • uv lock operates on entire workspace
  • uv run/uv sync default to workspace root; use --package for members
  • Root tool.uv.sources apply to all members unless overridden
  • Member dependencies are always editable

Script-Centric Flow (PEP 723)

bash
uv run hello.py                    # zero-dep script, auto-env
uv add --script hello.py rich      # embeds dep metadata
uv run --with rich hello.py        # transient deps, no state

CLI Tools (pipx Replacement)

bash
uvx ruff check .                   # ephemeral run
uv tool install ruff               # user-wide persistent install
uv tool list                       # audit installed CLIs
uv tool update --all               # keep them fresh

Python Version Management

bash
uv python install 3.10 3.11 3.12
uv python pin 3.12                 # writes .python-version
uv run --python 3.10 script.py

Legacy Pip Interface

bash
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip sync -r requirements.txt    # deterministic install

Performance Tuning

Env Var Purpose Typical Value
UV_CONCURRENT_DOWNLOADS saturate fat pipes 16 or 32
UV_CONCURRENT_INSTALLS parallel wheel installs CPU_CORES
UV_OFFLINE enforce cache-only mode 1
UV_INDEX_URL internal mirror https://…
UV_PYTHON pin interpreter in CI 3.11
bash
uv cache dir && uv cache info      # show path + stats
uv cache clean                     # wipe wheels & sources

Migration Matrix

Legacy Tool uv Replacement
python -m venv uv venv
pip install uv pip install
pip-tools compile uv lock
pipx run uvx / uv tool run
poetry add uv add
pyenv install uv python install

Troubleshooting

Symptom Resolution
Python X.Y not found uv python install X.Y or set UV_PYTHON
Proxy throttling downloads UV_HTTP_TIMEOUT=120 UV_INDEX_URL=https://mirror.local/simple
C-extension build errors unset UV_NO_BUILD_ISOLATION
Need fresh env uv cache clean && rm -rf .venv && uv sync
Still stuck? RUST_LOG=debug uv ... and open a GitHub issue

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

stickystyle/claude-skills

markdown-oxide-lsp

markdown-oxide language server for Markdown/Obsidian vault intelligence. Provides wikilink completion, hover info, goto-definition, and diagnostics for Markdown files.

1 0
Explore
stickystyle/claude-skills

aboutme-index

Index-based file discovery using ABOUTME headers. Use INSTEAD of grep or Explore agent when searching for files by purpose or feature. Faster and more accurate than scanning code. Invoke this skill when user asks "which files handle X", "where is Y implemented", or when you need to find files related to a feature or task.

1 0
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

scaffold-exercises

Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.

111,310 9,758
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results