agent-tools

Agent Tools

Using Helper Scripts vs. Raw API Calls

Use the scripts in scripts/ as the primary interface for AI-delegated analysis and context gathering. References to scripts/... in this skill are relative to this skill directory. They encapsulate API boilerplate and formatting logic:

• Proper image encoding (WebP conversion, alpha removal)
• Task-tuned default model selection
• Structured output handling (e.g. boolean responses mapped to shell exit codes)
• Formatting structured data (like GitHub PRs and issues) into LLM-friendly Markdown

When to inspect script source: If a script lacks a specific parameter or fails due to a local dependency, inspect the script in scripts/. They demonstrate correct API schemas, request structures, and retry behaviors that you can adapt for custom calls.

Quick Start

Environment: AI commands require a Gemini API key (reads from GEMINI_API_KEY). Scripts will report clear errors if no key is found. gh-markdown optionally accepts a --token for GitHub API access.

Model selection: Every Gemini-backed script accepts --model MODEL and honors the GEMINI_MODEL environment variable (--model wins; each script's built-in default applies when neither is set). Defaults vary per tool and are tuned for its task; only override when you have a reason.

Dependencies: curl, jq, uv (all tools); base64, magick (image tools only)

# Gather context and analyze
scripts/context show gemini-api | scripts/emerson "Explain the key features"

# Transform an entire directory of documents or code
scripts/caxton "Translate the guides into French" --edit docs/

# Fetch a GitHub PR, Issue, or Workflow Run as Markdown
scripts/gh-markdown https://github.com/owner/repo/pull/123

# Describe an image (generate alt-text)
scripts/screenshot-describe screenshot.png

# Compare two images for visual differences
scripts/screenshot-compare before.png after.png

# Smart crop image around the detected primary subject
scripts/photo-smart-crop photo.jpg cropped.jpg

# Check if a photo prominently features people (exit code = answer)
scripts/photo-query @people photo.jpg

# Generic image query with a JSON schema
scripts/photo-query "Is there a fireplace?" \
  --schema "has_fireplace bool" photo.jpg

# Generate essay-length analysis from text
scripts/emerson "Summarize the key changes" < documentation.md

# Evaluate a boolean condition against text
echo "Hello world" | scripts/satisfies "is a greeting"

# Extract a structured purchase record from a receipt email
scripts/pacioli < order.eml

# Count tokens in text
cat document.md | scripts/token-count

# Interact with an Android UI via AI
scripts/popper "start an exercise"