---
source_keys:
  - agentskills-using-scripts
---

# Scripts Reference

## Package runners (no install required)

When an existing package does what you need, use a runner directly in SKILL.md without writing a script file.

| Runner | Language | Notes |
|--------|----------|-------|
| `uvx package@version` | Python | Recommended. Aggressive caching via uv. |
| `pipx run 'package==version'` | Python | Broader OS availability. |
| `npx package@version` | Node.js | Ships with npm/Node.js. |
| `bunx package@version` | Node.js | Bun environments only. |
| `deno run npm:package@version` | TypeScript | Requires permission flags (`--allow-read`, etc.). |
| `go run golang.org/x/...@version` | Go | Built into Go toolchain. |

Always pin versions. Never use `pip install` or `npm install -g` at runtime — they are not idempotent and pollute the environment.

## Inline dependency patterns

Use these when the script requires packages but should remain a single portable file.

**Python (PEP 723 + uv):**
```python
# /// script
# dependencies = [
#   "beautifulsoup4>=4.12,<5",
# ]
# requires-python = ">=3.12"
# ///
from bs4 import BeautifulSoup
```
```bash
uv run scripts/extract.py
```

**TypeScript (Deno):**
```typescript
#!/usr/bin/env -S deno run
import * as cheerio from "npm:cheerio@1.0.0";
```
```bash
deno run scripts/extract.ts
```

**TypeScript (Bun):**
```typescript
#!/usr/bin/env bun
import * as cheerio from "cheerio@1.0.0";
```
```bash
bun run scripts/extract.ts
```

**Ruby (bundler/inline):**
```ruby
require 'bundler/inline'
gemfile do
  source 'https://rubygems.org'
  gem 'nokogiri', '~> 1.16'
end
```
```bash
ruby scripts/extract.rb
```

## Script contract

Rules for all agentic scripts:

- **Self-contained** — bundle dependencies inline so the agent can run the script with a single command; do not require a separate install step
- **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr
- **Idempotent** — "create if not exists"; agents may retry on failure
- **Input constraints** — validate inputs early; reject unknown or ambiguous values with a clear error rather than proceeding silently
- **Meaningful exit codes** — `0` success, non-zero failure; document in `--help`
- **Dry-run support** — add `--dry-run` for destructive operations; pair with `--confirm`/`--force` for operations that can't be undone
- **Error messages** — on failure, state what went wrong, what was expected, and what to try; vague errors leave agents unable to self-correct

## --help output

Keep `--help` output concise — it enters the agent's context window. Include: usage line, one-line description, options with defaults, exit codes. Omit prose explanations.

## Output size

Many harnesses truncate tool output beyond 10–30K characters. Default to a summary or a reasonable output limit. For scripts that can produce large output: support `--offset N` for pagination, or use `--output FILE` to write to disk and keep stdout clean.