Files

Defame1297 99e64d67fc chore(skill-author): backfill sources provenance from agentskillsio research

Records the upstream agentskills.io sources that informed skill-author,
completing the research → docs → skill provenance chain introduced in
the previous commit.

- New references/sources.md with all 7 extracted agentskillsio sources,
  Contributing files attributed per-source to SKILL.md, references/deployment-modes.md,
  and references/scripts.md
- source_keys frontmatter added to SKILL.md (all 7 slugs), references/deployment-modes.md
  (agentskills-spec), and references/scripts.md (agentskills-using-scripts)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-26 20:52:33 +00:00

2.9 KiB

Raw Blame History

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):

# /// 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