Using uv for Portable Python in Gemini Skills

Keeping Python environments in sync for shared CLI tools can be a struggle. By using uv, we can create Gemini CLI skills that declare their own dependencies inline, making them instantly portable.

How It Works

uv solves the portability problem in two ways:

1. Interpreter Management: It finds or installs the correct Python version.
2. On-the-fly Dependencies: It reads inline script metadata to install packages automatically.

Inline Script Metadata

Instead of a separate requirements.txt or venv setup, you can declare dependencies directly at the top of your script using PEP 723 format:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "requests",
#     "python-dotenv",
# ]
# ///

import requests
# ...

When you run this with uv run script.py (or directly if you use the shebang), uv handles the rest.

Applying This to Skills

To ensure your agent uses this capability uniformly, you can add a guideline to your agent's system instructions or SKILL.md:

Python: Unless instructed otherwise, always use uv to run Python scripts (uv run scripts/name.py). This ensures dependencies are handled automatically.

Example Structure

Here is a minimal pattern for a reusable skill script:

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = ["requests"]
# ///

import sys
import requests

def main():
    # Your skill logic here
    print("Running securely with auto-managed dependencies!")

if __name__ == "__main__":
    main()

Why This Matters

By packaging the dependency specification with the script itself, we gain:

• Portability: The script runs anywhere uv is installed without manual setup.
• Consistency: The execution environment is reproducible.
• Speed: uv is extremely fast at resolving and installing dependencies.

This is ideal for Agent Skills, where you want to drop a folder into your skills directory and have it "just work" for the agent.

Always read before implementing a skill

• https://geminicli.com/docs/cli/skills.md
• https://agentskills.io/llms.txt