UV Deps

Arguments

Specific package names (e.g.

fastapi asyncpg

),

.

for all packages, or glob patterns (e.g.

django-*

).

If

$ARGUMENTS

is

help

,

--help

,

-h

, or

?

, skip the workflow and read references/interactive-help.md.

Workflow Selection

Based on user request:

• Security audit (audit, CVE, vulnerabilities, security): Read references/audit-workflow.md
• Dependency updates (update, upgrade, latest, modernize): Read references/update-workflow.md
• Ambiguous (no clear intent, or invoked with no args): Read references/interactive-help.md

Shared Process

1. Create Worktree

Create an isolated git worktree so the main working directory is never modified:

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BRANCH_NAME="py-uv-deps-$TIMESTAMP"
WORKTREE_PATH="${TMPDIR:-/tmp}/$BRANCH_NAME"
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

git worktree add

writes to

$TMPDIR

and requires

dangerouslyDisableSandbox: true

(filesystem access).

gh

,

git push

, and

git commit

also require it (keyring access for auth).

If

git worktree add

fails (e.g., sandbox permission error), prompt the user:

git worktree

requires write access to

$TMPDIR

. Choose an option:

1. Add

   $TMPDIR

   to your sandbox allowlist in

   settings.json

   (recommended)
2. Fall back to branch+stash approach

All subsequent steps operate within

$WORKTREE_PATH

. Discovery, syncs, edits, and commits all happen there. Paths like

cd <directory>

in reference files are relative to

$WORKTREE_PATH

.

2. Verify Tool Access

Verify that

uv

and

uvx

are available and can reach PyPI. See references/uv-commands.md for verification commands and troubleshooting.

All

uv

,

uvx

,

gh

,

git push

, and

git commit

commands require

dangerouslyDisableSandbox: true

.

Do not proceed until verification passes.

3. Discover Python Projects

This skill targets

pyproject.toml

-based projects managed by uv. Projects using only

requirements.txt

,

setup.py

, or other package managers (poetry, pipenv) are out of scope.

Find all directories containing

pyproject.toml

within

$WORKTREE_PATH

with a

[project.dependencies]

,

[project.optional-dependencies]

, or

[dependency-groups]

section, excluding

.venv

,

.tox

,

build

, and

dist

directories. Store results as an array of directories to process. If none found, report to user and skip to cleanup.

For uv workspaces (root

pyproject.toml

contains

[tool.uv.workspace]

): treat the workspace root as the single project directory and do not process member subdirectories individually — the root

uv.lock

covers all members. Run

uv sync

and

uv lock

from the workspace root only. To identify workspace members to exclude: after the initial glob, if the root

pyproject.toml

contains

[tool.uv.workspace]

, remove member directories from the discovered list, keeping only the workspace root in the

$DISCOVERED_DIRS

array. Note:

members

entries are glob patterns (e.g.

packages/*

), not literal paths — expand them to concrete paths before matching (e.g.

python3 -c "import glob, os; [print(p) for g in members for p in glob.glob(g, root_dir='$WORKTREE_PATH')]"

or run

uv workspace list --no-sync

from the root to enumerate members).

4. Sync Dependencies

Sync before identifying packages so that version checks are accurate. For each discovered project directory: Check

pyproject.toml

to determine which dev dependency pattern the project uses:

• If

  [dependency-groups]

  has a

  dev

  key (PEP 735): use

  uv sync --group dev

  ← preferred (newer standard)
• Else if

  [project.optional-dependencies]

  has a

  dev

  key: use

  uv sync --extra dev

• If neither exists: use

  uv sync

If both

[dependency-groups]

and

[project.optional-dependencies]

have a

dev

key (migration scenario), prefer

[dependency-groups]

as it is the PEP 735 standard.

If

uv sync

fails (e.g., resolver conflicts, missing packages, unsupported Python version), report the error, skip this project directory, and continue with the remaining directories.

See references/uv-commands.md for full command reference.

5. Identify Packages

• Parse

  $ARGUMENTS

  to determine packages
• For

  .

  , process all dependencies from

  [project.dependencies]

  ,

  [project.optional-dependencies]

  , and

  [dependency-groups]

• For globs (e.g.

  django-*

  ), expand against all dependency sections
• For specific names, validate they exist in

  [project.dependencies]

  ,

  [project.optional-dependencies]

  , or

  [dependency-groups]

• Warn if a package name or glob matches nothing and list available packages

6. Validate Changes

Detect available validators by checking

pyproject.toml

for

mypy

,

ruff

, and

pytest

in any dependency section. Run whichever are present via

uv run

(see references/uv-commands.md for commands). Prefer project task runners if present — check for

Makefile

,

tox.ini

, or

noxfile.py

files in the project directory (not just

pyproject.toml

).

• On overall validation failure: continue running validation to collect all errors before reporting
• On per-package failure after update: revert that package before continuing with the next package (revert commands below)

If validation fails for a specific package update, revert before continuing with remaining packages (replace

<directory>

with the actual project path):

# Run from within $WORKTREE_PATH/<directory>
git checkout -- pyproject.toml
git checkout -- uv.lock 2>/dev/null || true  # uv.lock may not be committed
uv sync  # run from project directory

7. Commit Changes

After all updates are validated, check whether there are changes to commit, then commit:

# Run from $WORKTREE_PATH
# Check if there are any changes before committing
if git diff HEAD --quiet -- '*.toml' '*.lock' 2>/dev/null; then
  echo "No changes to commit — all updates were reverted or no updates applied."
  # skip to cleanup
else
  # Stage all modified pyproject.toml files (root and workspace members)
  # 'git diff HEAD --name-only' covers both root and subdirectory files
  git diff HEAD --name-only | grep 'pyproject\.toml$' | xargs git add 2>/dev/null || true

  # Stage uv.lock files only if already tracked in git (root and per-subdirectory)
  git diff HEAD --name-only | grep 'uv\.lock$' | while read -r lockfile; do
    git ls-files --error-unmatch "$lockfile" > /dev/null 2>&1 && git add "$lockfile" || true
  done

  # Select commit message based on workflow type:
  #   Security audit:    fix: patch vulnerable Python dependencies
  #   Dependency update: chore: update Python dependencies
  COMMIT_MSG="<select from above>"
  git commit -m "$COMMIT_MSG"
  # If commit fails due to GPG keyring access, retry with --no-gpg-sign
fi

Commit message format:

• Security audit:

  fix: patch vulnerable Python dependencies

• Dependency update:

  chore: update Python dependencies

8. Cleanup

Remove the worktree. The main working directory was never modified, so no stash restore is needed.

git worktree remove "$WORKTREE_PATH" --force
# Only delete branch if no PR was created (requires dangerouslyDisableSandbox: true)
# If gh fails (network issue, sandbox, etc.), PR_URL will be empty — preserve branch on ambiguity
PR_URL=$(gh pr list --head "$BRANCH_NAME" --json url --jq '.[0].url' 2>/dev/null)
GH_EXIT=$?
if [ $GH_EXIT -eq 0 ] && [ -z "$PR_URL" ]; then
  # gh succeeded and returned no PR — safe to delete
  git branch -d "$BRANCH_NAME" 2>/dev/null || git branch -D "$BRANCH_NAME"
else
  echo "Branch '$BRANCH_NAME' preserved (PR exists or gh check was inconclusive)."
fi

--force

handles cases where the skill failed mid-run with uncommitted changes in the worktree.

Edge Cases

• Resolver conflicts after major upgrades: When upgrading causes dependency conflicts (e.g., package A requires

  foo<2.0

  but package B needs

  foo>=2.0

  ), document the conflict, offer to skip or add a version constraint, and continue with remaining packages
• Dev dependency placement: After adding dev packages, verify they landed in

  [project.optional-dependencies]

  or

  [dependency-groups]

  , not

  [project.dependencies]