Files

Defame1297 252741a312 fix(kyberforge): apply skill-audit findings to skill-author

Body discipline: collapsed 4-bullet script rules to single critical callout
(no interactive prompts); full contract stays in references/scripts.md.
stderr discipline: redirect all confirmation/progress output in new-skill.sh
to stderr per scripts.md contract. Also expands references/scripts.md with
input validation and --help guidance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ

2026-06-24 19:52:16 +00:00

2.9 KiB

Raw Blame History

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
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.

2.9 KiB Raw Blame History Unescape Escape