home / skills / 89jobrien / steve / python-scripting

python-scripting skill

safe

This skill creates self-contained Python scripts with auto dependency management using uv and PEP 723 metadata to streamline CLI utilities.

npx playbooks add skill 89jobrien/steve --skill python-scripting

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: python-scripting
description: Python scripting with uv and PEP 723 inline dependencies. Use when creating
  standalone Python scripts with automatic dependency management.
author: Joseph OBrien
status: unpublished
updated: '2025-12-23'
version: 1.0.1
tag: skill
type: skill
---

# Python Scripting Skill

Creates self-contained Python scripts using uv and PEP 723 inline script metadata.

## What This Skill Does

- Creates standalone Python scripts
- Uses PEP 723 inline dependencies
- Sets up argument parsing
- Handles input/output
- Configures reproducible builds

## When to Use

- Standalone utility scripts
- One-off automation tasks
- Quick data processing
- CLI tools
- Scripts that need dependencies

## Reference Files

- `references/UV_SCRIPT.template.py` - Python script template with PEP 723 metadata

## PEP 723 Format

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

## Running Scripts

```bash
uv run script.py [args]
```

Dependencies install automatically on first run.

## Best Practices

- Use `exclude-newer` for reproducibility
- Include docstring with usage examples
- Use argparse for CLI arguments
- Return exit codes (0 success, non-zero error)
- Keep scripts focused on one task

Overview

This skill helps you create self-contained Python scripts that declare inline dependencies using PEP 723 and run with uv for automatic dependency management. It produces templates and conventions for argument parsing, input/output handling, and reproducible builds. Use it to ship single-file CLI tools that install and isolate their dependencies on first run.

How this skill works

The skill generates a script template with PEP 723 metadata header that lists Python version and dependencies. Scripts run via uv (uv run script.py) which installs declared packages automatically on first execution. The template includes argparse setup, clear I/O patterns, and options for reproducible installs such as exclude-newer and pinned versions.

When to use it

Building a standalone utility you want to distribute as a single file
Automating one-off or ad-hoc tasks that require third-party packages
Creating small CLI tools or data-processing scripts for teammates
Prototyping functionality that depends on external libraries without virtualenv setup
Packaging scripts that must reproduce the same environment across machines

Best practices

Declare exact or ranged dependency versions and use exclude-newer for reproducible builds
Include a top-level docstring with usage examples and expected inputs/outputs
Use argparse for structured CLI arguments and return meaningful exit codes
Keep each script focused on a single responsibility to minimize dependency surface
Pin interpreter requirement (e.g., >=3.12) in PEP 723 header to avoid runtime surprises

Example use cases

A single-file downloader that uses requests and rich for progress and pretty output
A CSV cleanup utility that depends on pandas but ships as one script
A deployment helper that calls cloud APIs without requiring users to install packages manually
A quick data transformation CLI for teammates who lack Python environments
A reproducible test harness that installs exact deps for CI debugging

FAQ

How do dependencies get installed?

uv installs the PEP 723 declared dependencies automatically the first time the script runs, then caches them for subsequent runs.

Can I pin versions to ensure reproducibility?

Yes. Specify exact versions or version ranges in the dependencies list and use exclude-newer options to avoid implicit upgrades.