Skip to content

Scripts in Skills

Condensed from using scripts in skills. Load this when the skill should run commands or bundle scripts/.

This repository is primarily a guidance library. Prefer references/ unless a skill truly needs executable resources.

One-off Commands

If an existing package already does the work, put a pinned command in SKILL.md instead of bundling code.

State prerequisites in the body. Runtime-level requirements belong in compatibility when that field is in use.

Pin versions. When the command is hard to get right on the first try, move it into scripts/.

Common launchers: uvx, pipx, npx, bunx, deno run, go run.

Referencing Bundled Scripts

Paths are relative to the skill root. List scripts in SKILL.md so the agent knows they exist, then give the run command:

## Available scripts

- `scripts/validate.sh` — Validates configuration files
- `scripts/process.py` — Processes input data

bash scripts/validate.sh "$INPUT_FILE"
python3 scripts/process.py --input results.json

The same relative-path rule applies inside references/*.md; execution cwd is the skill root.

Self-contained Scripts

Prefer scripts that declare dependencies inline so there is no install step:

  • Python: PEP 723 script metadata, run with uv run (or pipx run)
  • Deno: npm: / jsr: specifiers
  • Bun: versioned imports with runtime auto-install
  • Ruby: bundler/inline

Pin versions (PEP 508 for Python).

Agent-safe Interfaces

Agents run non-interactive shells.

  • No TTY prompts, password dialogs, or confirmation menus. Flags, env, or stdin only.
  • --help documents description, flags, and examples. Keep it short; it enters context.
  • Errors name the failure, the expected set, and the received value.
  • Structured stdout (JSON/CSV/TSV); diagnostics on stderr.
  • Idempotent retries; reject ambiguous input; --dry-run for destructive work; distinct exit codes.
  • Bound output size. Harnesses truncate large tool output. Default to a summary or require --output.