---
name: project-uv
description: Probe for python once per conversation, before the first `python`, `pip`, `uv run`, or `.py` invocation. Skip if the correct uv invocation for this repo is already established in the conversation.
globs:
  - pyproject.toml
---

# project-uv

Probe once per conversation. Read keys, don't guess.

## Run

POSIX: `sh "$CLAUDE_PLUGIN_ROOT/skills/project-uv/scripts/probe.sh"`
Windows: `& "$env:CLAUDE_PLUGIN_ROOT\skills\project-uv\scripts\probe.ps1"`

Successful execution is the proof python works here. If it fails, stop and report.

## Env-var contract

- `SCRIPTS_UV` — path to the `uv` executable.
- `SCRIPTS_DIR` — project script dir (default `scripts/`).
- `SCRIPTS_STORE` — scratch dir for throwaway scripts (default: platform temp).

Output echoes each as a key — empty value means unset or invalid. Use the `uv=` value if `scripts_uv=` is empty.

## Acting on `mode`

- `managed-project-locked` — `uv run <cmd>`; `uv sync` if `.venv` missing.
- `managed-project-unlocked` — `uv run <cmd>`; `uv sync` to create env.
- `pep723-only` — `uv run path/to/script.py`; edit `# /// script` block for deps.
- `uv-tool-only` — `[tool.uv]` without `[project]`; ask before assuming.
- `agent-tool-only` — uv exists but no python project; use for agent scratchpad in `scripts_store`.
- `none` — no python here; stop.

## Other keys

- `venv_tainted=true` — warn the user; uv isn't fully embraced here.
- `recipes=` — if a `just:`/`make:` recipe covers the task, prefer it.
- `default_packages=` — already importable; no install needed.

## Out of scope

Does not install uv, modify `pyproject.toml`, or pick a Python version.