# scripts/

Executable code bundled with this skill. Agents run scripts in this directory
to perform repeatable operations rather than reinventing the logic each run.

## When to add a script

Add a script when agents independently reinvent the same logic across runs —
building the same parser, chart, or validation routine from scratch each time.
Bundle it here once, tested and reliable.

## Script requirements (agentskills.io)

Scripts must be designed for non-interactive, agentic execution:

- **No interactive prompts** — agents run in non-interactive shells.
  Accept all input via flags, env vars, or stdin. A script that blocks on
  TTY input hangs indefinitely.
- **Expose `--help`** — this is how agents learn your script's interface.
  Keep the output concise; it enters the agent's context window.
- **Structured output** — write data (JSON, CSV, TSV) to stdout.
  Write progress, warnings, and diagnostics to stderr.
- **Idempotent** — prefer "create if not exists" over "create and fail on
  duplicate". Agents may retry on failure.
- **Meaningful exit codes** — `0` for success, non-zero for failure.
  Use distinct codes for different failure types; document them in `--help`.
- **Dry-run support** — add `--dry-run` for destructive operations.

## Self-contained scripts

Bundle dependencies inline so the agent can run the script with a single command.

Python (PEP 723 + uv):
```python
# /// script
# dependencies = ["requests>=2.31,<3"]
# requires-python = ">=3.11"
# ///
import requests
```
```bash
uv run scripts/my-script.py
```

## If no scripts are needed

Delete this README and the `scripts/` directory entirely.