uv-tool-management — Claude Code skill for CLI tools
uv-tool-management is a Claude Code skill for managing global Python CLI tools with uv and running them temporarily with uvx, including as an alternative to pipx.
MIT 328 installs ★ 60 updated 2026-11-16
npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-codeWhat uv-tool-management does
This skill covers installing tools with uv tool install, launching them on demand with uvx, and listing, upgrading, or removing installed tools. It also shows how to choose a tool version or install from a Git repository. For instance, uvx ruff check . runs a check without a permanent ruff install.
Each installed tool has a separate virtual environment, keeping tool dependencies apart. The executable directory needs to be on PATH; otherwise, commands such as ruff will not run directly. The skill also distinguishes global CLI tools from project dependencies: use uv tool install for the former and uv add for the latter.
What it helps with
- install a Python CLI tool for use across projects
- run a tool once without installing it
- list installed tools and upgrade one
- remove a single tool or all installed tools
- pin a CLI tool version or install it from Git
Example prompts for the agent
- Install
ruffas a global CLI tool withuv. - Run
black --check .once without keeping it installed. - List the tools managed by
uvand upgradepytest.
How to install uv-tool-management
1Skills CLI (Vercel)
npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-code2Manually: put the files in place
~/.claude/skills/uv-tool-management/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/uv-tool-management/
1Skills CLI (Vercel)
npx skills add laurigates/claude-plugins --skill uv-tool-management -a codex2Manually: put the files in place
.agents/skills/uv-tool-management/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add laurigates/claude-plugins --skill uv-tool-management -a cursor2Manually: put the files in place
.cursor/skills/uv-tool-management/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install laurigates/claude-plugins python-plugin/skills/uv-tool-management2Manually: put the files in place
.github/skills/uv-tool-management/SKILL.md1Skills CLI (Vercel)
npx skills add laurigates/claude-plugins --skill uv-tool-management -a gemini-cli2Platform CLI
gemini skills install https://github.com/laurigates/claude-plugins --path python-plugin/skills/uv-tool-managementManually: put the files in place
.devin/skills/uv-tool-management/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add laurigates/claude-plugins --skill uv-tool-management -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about uv-tool-management
How do I install uv-tool-management in Claude Code?
Run npx skills add laurigates/claude-plugins --skill uv-tool-management -a claude-code. The skill file is at ~/.claude/skills/uv-tool-management/SKILL.md.
What does uv-tool-management do?
It guides you through managing global Python CLI tools with uv: installing, upgrading, removing, and running tools temporarily with uvx.
How is uv tool different from uv add?
Use uv tool install for CLI applications you want available across projects. Use uv add to add a dependency to a specific project.
Source text
SKILL.md · MIT
--- created: 2025-12-16 modified: 2026-11-14 reviewed: 2026-04-25 name: uv-tool-management description: Install and manage global Python CLI tools with uv (pipx alternative). Use when the user mentions uv tool, uvx, installing CLI tools globally, or pipx replacement. user-invocable: false allowed-tools: Bash(uv tool install *), Bash(uv tool list *), Bash(uv tool upgrade *), Bash(uv tool uninstall *), Bash(uvx ruff *), Bash(uvx black *), Read, Grep, Glob --- # UV Tool Management Quick reference for installing and managing global Python tools with UV (pipx alternative). ## When to Use This Skill | Use this skill when... | Use a focused sibling instead when... | |---|---| | Installing a global CLI tool (ruff, black, ipython) with `uv tool install` as a pipx replacement | Running a project script inside its venv — use uv-run | | Running a one-off CLI invocation via `uvx tool` without installing | Adding the tool as a project dev dependency — use uv-project-management | | Listing, upgrading, or uninstalling globally installed tools | Pinning the Python version a tool runs on — use uv-python-versions | ## When This Skill Applies - Installing command-line tools globally (like pipx) - Managing tool installations and updates - Running tools ephemerally without installation - Listing and removing installed tools - Tool version management ## Quick Reference ### Installing Tools ```bash # Install tool globally uv tool install ruff uv tool install black uv tool install pytest # Install specific version uv tool install [email protected] uv tool install 'pytest>=7.0' # Install from Git uv tool install git+https://github.com/astral-sh/ruff # Install with extras uv tool install 'mkdocs[i18n]' uv tool install 'fastapi[all]' ``` ### Running Tools ```bash # Run without installing (ephemeral) uvx pycowsay "hello world" uvx ruff check . uvx black --check . # uvx is alias for: uv tool run pycowsay "hello world" # Run with specific version uvx [email protected] check . # Run from Git uvx git+https://github.com/user/tool script.py ``` ### Managing Tools ```bash # List installed tools uv tool list # Update tool uv tool install ruff --reinstall uv tool upgrade ruff # Remove tool uv tool uninstall ruff # Remove all tools uv tool uninstall --all ``` ### Tool Information ```bash # Check tool version ruff --version # List tool binaries uv tool list --verbose # Show tool location which ruff # ~/.local/bin/ruff (Linux) # ~/Library/Application Support/uv/bin/ruff (macOS) ``` ## uvx vs uv tool run These commands are equivalent: ```bash uvx ruff check . uv tool run ruff check . ``` `uvx` is a convenient shorthand for ephemeral tool execution. ## Installation Locations ### Tools Directory ```bash # Linux ~/.local/share/uv/tools/ # macOS ~/Library/Application Support/uv/tools/ # Windows %LOCALAPPDATA%\uv\tools\ ``` ### Binaries (Executables) ```bash # Linux ~/.local/bin/ # macOS ~/Library/Application Support/uv/bin/ # Windows %LOCALAPPDATA%\uv\bin\ ``` **Add to PATH:** ```bash # Add to ~/.bashrc or ~/.zshrc export PATH="$HOME/.local/bin:$PATH" ``` ## Common Tools ```bash # Code quality uv tool install ruff uv tool install black uv tool install ty # Documentation uv tool install mkdocs uv tool install sphinx # Testing uv tool install pytest uv tool install tox # Build tools uv tool install build uv tool install twine # Utilities uv tool install httpie uv tool install pipx uv tool install cookiecutter ``` ## UV Tool vs Project Dependencies **Use `uv tool` for:** - Command-line applications - Global development tools - Utilities used across projects **Use `uv add` for:** - Project-specific dependencies - Libraries imported in code - Development dependencies in specific projects ```bash # Global tool (any project) uv tool install ruff # Project dependency (one project) uv add --dev ruff ``` ## Tool Isolation Each tool gets its own virtual environment: ```bash # Each tool is isolated ~/.local/share/uv/tools/ ├── ruff/ # Isolated environment for ruff ├── black/ # Isolated environment for black └── pytest/ # Isolated environment for pytest # No dependency conflicts between tools ``` ## Common Workflows ### Setup Development Tools ```bash # Install common development tools globally uv tool install ruff uv tool install ty uv tool install pytest uv tool install ipython # Now available in any project ruff check . ty check src/ pytest ipython ``` ### One-Off Tool Usage ```bash # Run without installing uvx pycowsay "Temporary tool!" uvx httpie https://api.github.com # No cleanup needed ``` ### Replace pipx ```bash # Old (pipx) pipx install black pipx run pycowsay "hello" # New (uv) uv tool install black uvx pycowsay "hello" ``` ## Key Features - **Fast**: 10-100x faster than pipx - **Isolated**: Each tool in separate environment - **Ephemeral**: Run tools without installation - **Version control**: Pin tool versions - **Git support**: Install from repositories ## See Also - `uv-project-management` - Project-specific dependencies - `uv-python-versions` - Python versions for tools - `python-code-quality` - Using ruff, ty, black ## References - Official docs: https://docs.astral.sh/uv/guides/tools/ - Tool directory: Use `uv cache dir` to find cache location - Detailed guide: See REFERENCE.md in this skill directory
© laurigates · MIT · laurigates/claude-plugins