python-uv-workflow

Runs Python repository tasks with uv commands and repo-defined entrypoints.

5|1|Updated May 5, 2026
One-click install
npx skills add https://github.com/cbusillo/codex-skills --skill python-uv-workflow-cbusillo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-uv-workflow
Source: https://github.com/cbusillo/codex-skills/tree/main/skills/python-uv-workflow
Command: npx skills add https://github.com/cbusillo/codex-skills --skill python-uv-workflow-cbusillo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Python repositories often mix system Python, pip, and ad hoc virtualenv commands, leading to broken environments, out-of-sync lockfiles, and inconsistent test or release runs. This Skill steers every setup, test, dependency, packaging, and release task toward uv and the repository's own defined entrypoints. ## Core Features & Use Cases - uv-first command selection: Prefers uv run, uv sync, and uv lock over system python, pip, or manual virtualenvs, and inspects pyproject.toml before choosing commands. - Repo-defined entrypoints: Favors [project.scripts] entrypoints, repo wrapper commands, AGENTS.md, and .github/github.json quality gates over generic pytest invocations. - Dependency and release discipline: Keeps pyproject.toml and uv.lock in sync, supports uv build and twine check for packaging, and never publishes or tags without explicit user request. - Use Case: When asked to run tests in a uv-managed repo, the agent checks the repo's documented commands and runs uv run test or the documented wrapper instead of guessing pytest against a system interpreter. ## Quick Start Use the python-uv-workflow skill to set up this repository and run its test suite with uv.

Frequently Asked Questions about python-uv-workflow

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run tests in a uv-managed Python project?

Run tests with uv by first checking the repo's documented commands, then preferring wrappers like `uv run test` or `[project.scripts]` entrypoints over generic `uv run pytest`. Inspect pyproject.toml and AGENTS.md before choosing a command.

How do I update dependencies and the uv lockfile?

Update dependency metadata in pyproject.toml, then refresh the lockfile with `uv lock` and verify with `uv sync --locked` or the repo's documented lock check. Commit pyproject.toml and uv.lock together when both changed for the same update.

Should I use uv run or call repo shell wrappers directly?

Run executable shell wrappers directly rather than wrapping them in `uv run`, because uv may install the caller's project before the wrapper starts. Reserve `uv run` for Python commands, scripts, and project entrypoints.

Can I use pip install in a uv-managed repository?

No, do not use `pip install` to mutate the environment in a uv-managed repo. Use `uv sync` for environment setup and `uv lock` for dependency changes so the lockfile stays consistent.

How do I build and check a Python package before release with uv?

Build the package with `uv build` and validate distributions with `uv run twine check dist/*`, but only when the repo has the relevant tooling or documents that workflow. Never publish, tag, or dispatch release workflows unless the user explicitly asks.

When should I not trigger uv workflow commands?

Do not trigger uv workflows just because a Python file is being edited; they apply only to setup, tests, scripts, dependencies, packaging, release, or runtime commands. For standalone utilities, use PEP 723 metadata with `uv run` or `uv run --no-project`.