Skip to content
Skills Library
Programming · Building & coding

standalone-script

/standalone-script

Use when generating a self-contained Python script with PEP 723 inline dependency metadata: writing the script block header, making a script runnable with uv run --script, combining with a Typer CLI for argument handling, or creating a one-off analysis tool that should not live inside a package and must declare its own dependencies inline.

Repository
marketplace ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/pep723_typer_script.py

What it does and when to use it

Use when generating a self-contained Python script with PEP 723 inline dependency metadata: writing the script block header, making a script runnable with uv run --script, combining with a Typer CLI for argument handling, or creating a one-off analysis tool that should not live inside a package and must declare its own dependencies inline.

Original author description

Use when generating a self-contained Python script with PEP 723 inline dependency metadata: writing the script block header, making a script runnable with uv run --script, combining with a Typer CLI for argument handling, or creating a one-off analysis tool that should not live inside a package and must declare its own dependencies inline.

How it works

  1. Overview
  2. When to Use
  3. Key Concepts
  4. Canonical Patterns
  5. Gotchas
  6. Interop
  7. Docs
Original SKILL.md headings · 160 lines, 773 words
SKILL.md preview
---
name: standalone-script
description: >-
  Use when generating a self-contained Python script with PEP 723 inline
  dependency metadata: writing the script block header, making a script runnable
  with uv run --script, combining with a Typer CLI for argument handling, or
  creating a one-off analysis tool that should not live inside a package and
  must declare its own dependencies inline.
---

# Standalone Script

## Overview

PEP 723 (Python 3.12+, backported via `uv`) lets a `.py` file declare its own
dependencies in a `# /// script` comment block. Running the script with
`uv run --script <file>` automatically installs deps into a temporary
environment. This is the right pattern for one-off analysis scripts, quick
tools, and anything you want to share as a single file.

## When to Use

- Writing a one-off analysis script that doesn't belong in a package
- Creating a self-contained tool to share with collaborators (single file, no
  `pip install` instructions)
- Combining with `hep-python-tools:cli-creator` for a proper CLI layer
- Replacing an ad-hoc `requirements.txt` + `python script.py` workflow

## Key Concepts

| Concept                           | Notes                                                      |
| --------------------------------- | ---------------------------------------------------------- |
| `# /// script` block              | Top-level comment block; by convention placed near the top |
| `requires-python`                 | Minimum Python version for the script                      |
| `dependencies`                    | PEP 508 dependency specs — same syntax as `pyproject.toml` |
| `uv run --script <file>`          | Installs deps and runs in one step                         |
| `uv lock --script <file>`         | Write a `<file>.lock` adjacent to the script               |
| `uv run --script --frozen <file>` | Use the existing lock without re-resolving (needs `.lock`) |

## Canonical Patterns

```python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "uproot>=5",
#   "awkward>=2",
#   "hist>=2.7",
#   "vector>=1",
#   "typer>=0.9",
#   "mplhep",
# ]
# ///
"""Fetch jet pT from a local ROOT file and plot a histogram."""
from __future__ import annotations
from pathlib import Path
from typing import Annotated

import awkward as ak
import hist
import mplhep
import matplotlib.pyplot as plt
import typer
import uproot
import vector

vector.register_awkward()
mplhep.style.use("ATLAS")

app = typer.Typer()

@app.command()
def main(
    root_file: Annotated[Path, typer.Argument(help="Input ROOT file", exists=True)],
    tree: Annotated[str, typer.Option(help="TTree name")] = "reco",
    output: Annotated[Path, typer.Option(help="Output plot")] = Path("jet_pt.pdf"),
) -> None:
    """Plot jet pT distribution from ROOT_FILE."""
    with uproot.open(root_file) as f:
        jets = f[tree].arrays(["jet_pt", "jet_eta"], library="ak")

    selected = jets[ak.num(jets.jet_pt) >= 1]
    pts = ak.to_numpy(ak.flatten(selected.jet_pt)) / 1000  # MeV → GeV

    h = hist.Hist(hist.axis.Regular(50, 0, 500, name="pt", label=r"$p_T$ [GeV]"))
    h.fill(pt=pts)

    fig, ax = plt.subplots()
    h.plot1d(ax=ax)
    ax.set_ylabel("Events")
    fig.savefig(output)
    typer.echo(f"Saved: {output}")

if __name__ == "__main__":
    app()
```

**Run it**:

```bash
uv run --script my_analysis.py data.root --output jet_pt.pdf
```

**For testing with a specific tree**:

```bash
uv run --script my_analysis.py data.root --tree reco
```

### Pinning Dependencies

For reproducibility in scripts that will be shared or run in CI:

```python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "uproot==5.3.9",
#   "awkward==2.6.5",
# ]
# ///
```

Or generate a lockfile once and run frozen in CI. `--frozen` reuses the lock and
errors if `analysis.py.lock` is missing, so you must `uv lock --script` first:

```bash
uv lock --script analysis.py            # writes analysis.py.lock (commit it)
uv run --script --frozen analysis.py input.root
```

## Gotchas

- **Block placement is flexible, but convention is top-of-file**: PEP 723 only
  requires the `# /// script` block to be a _top-level comment block_ (every
  line starts at column 0); it does not have to precede imports or the module
  docstring. `uv` scans the whole file for it. Place it near the top (after an
  optional shebang) for readability. There must be exactly **one** `script`
  block, or tools error.
- **Comments inside the block**: Each content line must start with `# ` (or be a
  bare `#`). A line that does not start with `#` ends the block.
- **`uv run --script` re-resolves when there is no lock**: For repeatable CI
  runs, `uv lock --script` once (commit the `.lock`) then run with `--frozen`,
  which reuses the lock instead of re-resolving.
- **Not the same as `uv run <file>`**: `--script` flag tells uv to treat the
  file as a PEP 723 script; without it, uv runs the file in the current
  project's virtualenv.
- **Python version**: The `requires-python` constraint is enforced — if your
  system Python is older, uv downloads a matching interpreter automatically (if
  using `uv` with Python management enabled).
- **Shebang alternative**: You can add `#!/usr/bin/env -S uv run --script` as
  the first line for a truly self-running script on Unix.

## Interop

- **cli-creator**: Combine PEP 723 header + Typer app for a complete
  self-contained CLI script — copy `assets/pep723_typer_script.py` as a starting
  template (PEP 723 header + a minimal Typer app with a `-v`/ `--verbose` count
  option already wired to logging level).
- **uv**: `uv run --script` is the primary runner; also works with `pixi run`
- **pixi**: `pixi run python script.py` works if deps are in the pixi
  environment; PEP 723 is not needed in that case

## Docs

- PEP 723:
  https://packaging.python.org/en/latest/specifications/inline-script-metadata/
- uv scripts guide: https://docs.astral.sh/uv/guides/scripts/
Files in this package (2)
  • SKILL.md 6 KB
  • assets/pep723_typer_script.py 1 KB

Versions

The database has no other skills named standalone-script.

Database snapshot: 13.11.2026 · package version a42173ac3685 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ac-tools-single-file-uv-scripter
    Creates self-contained Python scripts with inline PEP 723 metadata for UV. Embeds dependencies directly in script headers for zero-config execution via `uv run`. Triggers on keywords: uv script, single file script, inline dependencies, PEP 723, self-contained python, uv run script, standalone script
  • 100python-development
    Use when writing, reviewing, refactoring, running, linting, formatting, or packaging Python code and self-contained Python scripts using modern Python, uv, Ruff, ty, and PEP 723 inline script metadata. Always use `uv` instead of pip/python/venv.
  • 90dev10x:py-uv
    Guide UV installation and migrate Python scripts from legacy shebangs to UV inline metadata (PEP 723). TRIGGER when: migrating scripts to uv, setting up uv for the first time, or converting shebangs to PEP 723 format. DO NOT TRIGGER when: uv is already configured, or user is…
  • 95building-python-clis
    Builds command-line interfaces for Python libraries using Click or Typer. Includes command groups, argument handling, progress bars, shell completion, and CLI testing with CliRunner. Use when adding CLI functionality to a library or building standalone command-line tools.
  • 100uv-run
    Run Python scripts with uv (PEP 723 inline deps, --with for one-off deps). Use when running scripts without venv activation or needing one-off dependencies.
  • 100uv-workflow
    Use when a coding agent needs to run Python code, modules, one-liners, tools, tests, or standalone scripts through uv, or create and maintain PEP 723 scripts with uv init/add/remove --script. Avoid direct python/python3 shell entrypoints.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.