菜单
Manage dependencies and run code in uv-based Python projects. Use when adding/upgrading dependencies, running Python code or scripts, bumping the project version, or bypassing the uv dependency cooldown for a security fix.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | python-uv-workflow |
| description | Manage dependencies and run code in uv-based Python projects. Use when adding/upgrading dependencies, running Python code or scripts, bumping the project version, or bypassing the uv dependency cooldown for a security fix. |
Standards for working in a uv project. Prefer the uv CLI to
manage dependencies and the project version — let it edit pyproject.toml and uv.lock
rather than hand-editing them.
Never activate a venv or call pip/python directly. Use the CLI so deps stay in sync
across pyproject.toml and uv.lock:
uv add httpx # add a dependency (uv add --dev for dev-only; uv remove to drop)
uv run pytest # run a command in the project environment
uvicorn, pytest plugins) in dev
dependencies (uv add --dev), and keep heavy or specialised dependencies out of
shared core packages so every consumer doesn't inherit them.[dependency-groups] (what
uv add --dev/--group write to), not [project.optional-dependencies].uv lock --upgrade-package <pkg> rather than a
blanket uv lock --upgrade, to keep lock churn reviewable.uv sync --locked (or uv lock --check).pyproject.toml (no upper bound without a documented reason),
and pin Docker base images to a patch-level tag (e.g. python:3.13.1, not
python:3.13).For a one-off script outside the project, declare deps inline with
PEP 723; uv run builds an ephemeral env from them:
# /// script
# dependencies = ["httpx"]
# ///
import httpx
uv run script.py # runs in an ephemeral env with httpx
uv add --script script.py rich # add a dep to the script's metadata
uv version reads or updates the version in pyproject.toml (and re-locks) — use it
instead of hand-editing:
uv version # read current version
uv version --bump patch # 0.1.0 -> 0.1.1 (also: minor, major)
uv version 2.0.0 # set an explicit version
--bump also accepts stable, alpha, beta, rc, post, dev (stackable, e.g.
--bump minor --bump rc -> 1.1.0rc1). Add --dry-run to preview.
The cooldown (exclude-newer under [tool.uv], e.g. "1 week") holds back freshly
released versions. To take a newer version for a security fix, exempt only the affected
package(s) — one of the few settings with no CLI equivalent, so edit pyproject.toml
directly. A CLI-only --exclude-newer-package "<pkg>=false" is not durable: the next
uv lock/uv sync re-resolves and strips it back out.
Add or extend the exemption table under [tool.uv] (keep existing entries):
[tool.uv]
exclude-newer = "1 week"
exclude-newer-package = { cryptography = false }
Force the upgrade — editing alone won't move an already-locked package — then commit
pyproject.toml and uv.lock:
uv lock --upgrade-package cryptography
Remove the entry and re-lock once the version is older than the cooldown window.
Write agent output for the accountable human reviewer — route narrative by audience and lifespan, lead with a budgeted summary, keep detail collapsed, and plan before building. Use when writing PR or issue descriptions, commit messages, or code comments, when addressing or resolving PR review comments, when deciding whether to raise an issue or where work-narrative belongs, or when scoping a non-trivial change before generating code.
Write asyncio Python to this project's standards — concurrent coroutines, async-all-the-way, and safe handling of errors from concurrent tasks. Use when writing async/await code, gathering coroutines, designing async FastAPI endpoints or clients, or handling failures from concurrent work.
Write Python source to this project's standards. Use when authoring or refactoring Python code and deciding on style, type hints, docstrings, comments, imports, or language idioms.
Work with dates, times, and timezones to this project's standards. Use when creating, parsing, serialising, comparing, or storing datetimes, or handling timezones.
Handle errors in Python to this project's standards — custom domain exceptions, narrow catches, and failing fast. Use when raising or catching exceptions, writing try/except, designing an exceptions module, or deciding whether to swallow or propagate an error.
Reach for this project's preferred, well-supported libraries instead of hand-rolling. Use when choosing a library for HTTP, retries, JSON, or parsing, or whenever you are about to write something the standard library or a maintained package already does.