Scripts in a skill

Read this when the user asks whether something should be a script, why Smithy wrote one, or how scripts in a skill are run.

A script does work that has one right answer per input: parsing, counting, resolving paths, validating structure, rendering a template, diffing, generating random values. Prose does work that turns on meaning: judgment, tone, what to do with a result. A line on the wrong side is a defect the review catches: prose counting tokens or checking structure is paid on every run and done differently each time; a script deciding what a sentence means breaks when the phrasing shifts.

How a script is written: Python with a PEP 723 header (requires-python = ">=3.11", dependencies listed), --help, JSON on stdout when the agent reads the result, a non-zero exit with a reason rather than an error left for the agent to notice, standard library first. A unittest test sits beside it at scripts/tests/test_<name>.py. No model ids anywhere; users run any model. No network unless the docstring says why.

How a script is run: always uv run <path>, with the skill's own scripts as uv run {skill-root}/scripts/<name>.py and the project's runtime scripts as uv run {project-root}/_bmad/scripts/<name>.py. Never python, python3 or pip; uv run reads the header and provides the dependencies, so the user installs nothing. Never a bare scripts/x.py, which resolves from wherever the agent happens to be.

Tests assert what a script produced, never what a model wrote or what a prompt file says.