Defame1297
7ec34dd0de
- Add name field format constraints (1-64 chars, hyphens rules) - Add output format template pattern to ## Patterns - Add scope design note before prerequisites checklist - Add reference depth rule (one level deep) - Restore Placement table to README - Trim script rules to 2 inline + full contract in references/scripts.md - Add script contract section to references/scripts.md (error messages, dry-run/confirm pairing, output size, idempotency, exit codes) - Update Step 5 headings to "Validate and close" in both flows - Remove "Performs best when preceded by grill session" from description - Condense Include/Exclude block to single forwarding sentence - Fix README Files table: add README.md row, update scripts.md description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ
2.6 KiB
2.6 KiB
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):
# /// script
# dependencies = [
# "beautifulsoup4>=4.12,<5",
# ]
# requires-python = ">=3.12"
# ///
from bs4 import BeautifulSoup
uv run scripts/extract.py
TypeScript (Deno):
#!/usr/bin/env -S deno run
import * as cheerio from "npm:cheerio@1.0.0";
deno run scripts/extract.ts
TypeScript (Bun):
#!/usr/bin/env bun
import * as cheerio from "cheerio@1.0.0";
bun run scripts/extract.ts
Ruby (bundler/inline):
require 'bundler/inline'
gemfile do
source 'https://rubygems.org'
gem 'nokogiri', '~> 1.16'
end
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
- Meaningful exit codes —
0success, non-zero failure; document in--help - Dry-run support — add
--dry-runfor destructive operations; pair with--confirm/--forcefor 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
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.