python-uv-scripts_skill

Overview

This skill helps you author, convert, validate, and standardize Python single-file utilities using uv and PEP 723 inline metadata. It enforces correct inline dependency declarations, prevents invalid patterns like [tool.uv.metadata], and provides templates and tools to make scripts production-ready. Use it to manage dependencies, testing, CI integration, and team standards for self-contained scripts.

How this skill works

The skill inspects Python files for PEP 723 inline metadata blocks (the # /// script ... /// markers) and validates requires-python, dependencies, and allowed tool.uv fields. It offers conversion utilities to add inline metadata to existing scripts, a validator to catch anti-patterns such as [tool.uv.metadata], and templates (shebang + metadata + docstring) to create executable uv scripts. It also surfaces recommended dependency pinning, testing hooks, and CI snippets for running uv scripts in automation.

When to use it

• Creating a standalone utility that should carry its own dependencies and version constraints.
• Converting legacy scripts or requirements.txt-based utilities to uv single-file format.
• Adding reproducible shebang + metadata for CI/CD or scheduled jobs.
• Establishing team standards for naming, metadata, and error handling for scripts.
• Implementing lightweight testing and validation for simple utilities with inline tests.

Best practices

• Always declare requires-python (e.g., >=3.11) in the metadata block.
• Place dependencies in the PEP 723 block, avoid [tool.uv.metadata] TOML fields.
• Use shebang: #!/usr/bin/env -S uv run --script --quiet for production scripts.
• Keep scripts focused and under ~500 lines; move complex code to a project.
• Add a module docstring with Purpose, Team, Author, Usage, and examples.
• Provide a --test flag or inline tests for quick validation in CI.

Example use cases

• A cluster health checker packaged as a single executable script with Rich and Typer.
• Converting an old administrative script to uv format using the convert_to_uv tool.
• Running periodic health checks in GitHub Actions or GitLab CI using uv images.
• Small API clients or system automation utilities that need simple dependency management.
• Team adoption template for consistent script naming, shebangs, and metadata.