UV for Portable Python in Agent Skills
Python scripts are a natural choice for agent skills and agentic workflows, but traditional package management creates portability problems. Scripts need to run reliably across different execution environments — your local machine with a coding agent, a remote agent environment, or someone else’s setup entirely when sharing a skill.
Traditionally, Python package and environment management is a bit messy. It depends on a Python interpreter that could be installed in many different paths, plus creating a virtual environment — which is itself rather hacky, operating by creating directories and setting shell variables. These inconsistencies cause failures when skills move between environments.
UV — the modern Python package manager from Astral — solves this elegantly. A UV-based script declares its dependencies inline and runs identically everywhere, with no environment setup required.
How It Works
UV provides two features that matter here:
Interpreter management — UV can run and, if necessary, install the correct Python interpreter, so you always work with the correct version.
On-the-fly package installation — UV fetches, installs, and caches packages automatically when running a script.
When a script includes PEP 723 inline metadata, UV handles everything. The metadata lives at the top of your script:
# /// script
# requires-python = “>=3.11”
# dependencies = [
# “requests==2.32.5”,
# “markdown==3.10”,
# ]
# ///
import requests
import markdown
# ... rest of script
Running uv run script.py installs any missing packages, caches them for future runs, and executes the script — no virtual environment creation, no permanent installation, no shell manipulation.
Applying This to Skills
In your skill’s SKILL.md, specify that scripts should run via UV:
Run the foo script to produce bar:
```bash
uv run scripts/foo.py
```For agent-wide consistency, add instructions to your agent’s configuration:
## Python
- Unless instructed otherwise, always use the `uv` Python environment and package manager for Python.
- `uv run ...` for running a python script.
- `uvx ...` for running a program directly from a PyPI package.
- `uv pip ...` for managing environments, installing packages, etc.Why This Matters
The full dependency specification travels with the script itself. We can package a script without requiring the execution environment to do any particular installation or virtual environment setup. This means consistent behavior and consistent performance across different execution environments — exactly what portable skills require.
A new user can check out your skill and run it immediately. UV handles the rest. This follows the same principle behind explicit dependency declaration in any robust system: never rely on implicit existence of packages in the surrounding environment. The full and explicit dependency specification should apply uniformly across all environments where the code runs.
If you do need to install packages into an environment, UV handles that too — it can use its own package management format or work with requirements.txt and other standard formats.
Summary
By sticking to UV in skills and agentic workflows for running and managing Python scripts, you get portable, repeatable, reproducible behavior. For Python-based skills meant to be shared and reused, this portability is not optional. UV makes it practical.