Agent Skills: Python Shebang Validation

<file_paths>$ARGUMENTS</file_paths>

Python Shebang Validation

The model validates Python shebangs against dependency requirements and ensures correct PEP 723 inline script metadata.

Arguments

<file_paths/>

Instructions

If file paths provided above:

1. Read each file using the Read tool
2. Check for shebang presence and correctness
3. Validate against the rules below
4. Check execute bit status
5. Fix any misalignments with this guidance
6. Report findings for each file using the Mandatory Verification Format below

If no arguments provided:

1. Ask the user which files or directories need shebang validation
2. Suggest searching for Python files that might need shebangs
3. Offer to check if existing shebangs are correct

Shebang Selection Rules

Rule 1: Stdlib-only executable scripts

Pattern: #!/usr/bin/env python3

Conditions:

• File is executable
• Has no external dependencies
• Uses only Python standard library

Reasoning: No dependency installation required, standard Python interpreter sufficient.

Rule 2: Package executables

Pattern: #!/usr/bin/env python3

Conditions:

• File is part of installed package
• Has setup.py or pyproject.toml managing dependencies

Reasoning: Dependencies installed via package manager, not script metadata.

Rule 3: Standalone scripts with external dependencies

Pattern: #!/usr/bin/env -S uv run --quiet --script

Conditions:

• File is executable standalone script
• Requires external packages

Reasoning: PEP 723 inline metadata declares dependencies, uv installs them automatically. Never add --active: it makes uv run prefer an ambient activated virtual environment over the isolated ephemeral one PEP 723 scripts are supposed to get, installing the script's dependencies into the caller's shared .venv instead of a throwaway environment — empirically verified: a probe script declaring a dependency absent from a project venv, run under --active --script with VIRTUAL_ENV set, measurably installed into that venv; with --active omitted, the same probe resolved into an isolated uv cache environment instead, leaving the project venv untouched.

Rule 4: Non-executable files

Pattern: No shebang line

Conditions:

• File is library module
• Imported by other code
• Not directly executable

Reasoning: Not intended for direct execution.

UV Shebang Command Structure

The shebang: #!/usr/bin/env -S uv run --quiet --script

Component Breakdown

| Component | Position | Purpose | | -------------------- | ----------- | ---------------------------------------------------------------| | #!/usr/bin/env -S | Prefix | Shebang invoking env with -S flag for multiple arguments | | uv | Command | The uv binary on PATH | | run | Subcommand | Executes Python scripts with automatic environment management | | --quiet | Global flag | Suppresses progress output from uv | | --script | run flag | Indicates file contains PEP 723 inline script metadata |

Flag Ordering

--quiet/-q is a global option — uv --help and uv run --help list it identically, and uv run --quiet --script / uv --quiet run --script are confirmed equivalent at runtime (both exit 0, identical output). Either ordering works; use uv run --quiet --script as the canonical form for consistency.

Invalid Variations

The model MUST reject any shebang carrying --active in any position — it breaks PEP 723 isolation (see Rule 3 above) — and any PEP-723-metadata file missing --script.

Execute Bit Requirement

All files with shebangs MUST have execute permission set.

chmod +x filename

Without execute bit, the shebang is ignored by the kernel.

Mandatory Verification Format

For each file, output in this exact order:

1. Current shebang: [exact line from file or "none"]
2. PEP 723 metadata dependencies: [exact list or "none"]
3. External package count: [number with evidence]
4. Import analysis:
   • stdlib: [list]
   • external: [list]
5. Rule condition evaluation:
   • Rule 1: [condition 1 MET/NOT MET] [condition 2 MET/NOT MET] [condition 3 MET/NOT MET]
   • Rule 2: [condition 1 MET/NOT MET] [condition 2 MET/NOT MET]
   • Rule 3: [condition 1 MET/NOT MET] [condition 2 MET/NOT MET]
   • Rule 4: [condition 1 MET/NOT MET]
6. Applicable rule: [number] because [one-sentence justification citing specific unmet/met conditions]
7. Execute bit: [executable/not executable via test command]
8. Verdict: CORRECT / INCORRECT [if incorrect, Edit the file to fix]

Transformation Examples

Example 1: Remove redundant PEP 723 from stdlib-only script

Before (invalid - no external dependencies):

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

from __future__ import annotations

import re
from pathlib import Path

After (corrected):

#!/usr/bin/env python3

from __future__ import annotations

import re
from pathlib import Path

Bundled Transitive Dependency Constraint

typer>=0.12.0 ships with rich and shellingham as bundled transitive dependencies. When typer appears in a PEP 723 dependencies block, the model MUST NOT add rich or shellingham as separate entries.

# WRONG — rich is transitively installed by typer
# dependencies = [
#   "typer>=0.21.2",
#   "rich>=13.0.0",   # redundant, DO NOT ADD
# ]

# CORRECT — typer only; rich and shellingham arrive automatically
# dependencies = [
#   "typer>=0.21.2",
# ]

This rule applies regardless of how much rich API surface the script uses (Console, Panel, Progress, Table, etc.). The import works because typer guarantees rich's presence.

SOURCE: "By default, typer comes with rich and shellingham." — https://typer.tiangolo.com/#installation (accessed 2026-02-22)

Example 2: Add PEP 723 to script with external dependencies

Before (invalid - missing PEP 723):

#!/usr/bin/env python

from __future__ import annotations

from pathlib import Path
from typing import Annotated

import typer
from rich.console import Console
from rich.panel import Panel

After (corrected):

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "typer>=0.21.2",
# ]
# ///

from __future__ import annotations

from pathlib import Path
from typing import Annotated

import typer
from rich.console import Console
from rich.panel import Panel

References

• PEP 723 - Inline Script Metadata
• uv CLI Reference
• uv run Subcommand