@runecraft/grimoire 1.0.0

package/skills/skill-forge/references/description-optimization.md

@@ -0,0 +1,171 @@
+# Description Optimization (Trigger Eval)
+
+> Read this in Phase 5 (OPTIMIZE) when you need to systematically improve a skill's triggering accuracy. The description is the only thing the agent sees at startup — if it doesn't trigger on the right prompts, nothing else matters.
+
+## How triggering works
+
+Agents use progressive disclosure. At startup they load only `name` and `description` of each skill — just enough to decide when a skill might be relevant. When a user's task matches, the agent reads the full `SKILL.md` and follows the instructions.
+
+The description carries the entire burden of triggering. If it doesn't convey when the skill is useful, the agent won't reach for it.
+
+One nuance: agents typically only consult skills for tasks requiring knowledge or capabilities beyond what they handle alone. A simple "read this PDF" may not trigger a PDF skill even with a perfect description, because the agent can handle it with basic tools. Skills matter most where there's specialized knowledge — an unfamiliar API, a domain workflow, an uncommon format.
+
+## Writing effective descriptions
+
+- **Imperative phrasing.** "Use this skill when…" not "This skill does…". The agent is deciding whether to act; tell it when to act.
+- **Focus on user intent, not implementation.** Describe what the user is trying to achieve, not the skill's internal mechanics.
+- **Err on the side of being pushy.** List contexts where the skill applies, including cases where the user doesn't name the domain directly: "even if they don't explicitly mention 'CSV' or 'analysis.'"
+- **Keep it concise.** A few sentences to a short paragraph. The spec enforces 1024 chars.
+
+## Designing trigger eval queries
+
+Build a set of realistic user prompts, each labeled with whether it should trigger the skill.
+
+```json eval_queries.json
+[
+  { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D — can you add a profit margin column and highlight anything under 10%?", "should_trigger": true },
+  { "query": "whats the quickest way to convert this json file to yaml", "should_trigger": false }
+]
+```
+
+Aim for ~20 queries: 8-10 should-trigger, 8-10 should-NOT-trigger.
+
+### Should-trigger queries
+
+Vary along several axes:
+
+- **Phrasing:** formal, casual, typos, abbreviations.
+- **Explicitness:** some name the domain ("analyze this CSV"); others describe the need without naming it ("my boss wants a chart from this data file").
+- **Detail:** terse prompts alongside context-heavy ones with file paths, column names, backstory.
+- **Complexity:** single-step tasks alongside multi-step workflows.
+
+The most useful should-trigger queries are ones where the skill would help but the connection isn't obvious. If the query already asks for exactly what the skill does, any reasonable description would trigger.
+
+### Should-not-trigger queries
+
+The most valuable negative test cases are **near-misses** — queries that share keywords or concepts with the skill but actually need something different. These test whether the description is precise, not just broad.
+
+Weak negatives (test nothing):
+
+- "Write a fibonacci function" — obviously irrelevant.
+- "What's the weather today?" — no keyword overlap.
+
+Strong negatives:
+
+- "I need to update the formulas in my Excel budget spreadsheet" — shares "spreadsheet" and "data" concepts, but needs Excel editing, not CSV analysis.
+- "Can you write a python script that reads a csv and uploads each row to our postgres database" — involves CSV, but the task is database ETL, not analysis.
+
+### Tips for realism
+
+Real user prompts contain context generic test queries lack. Include:
+
+- File paths (`~/Downloads/report_final_v2.xlsx`)
+- Personal context (`"my manager asked me to..."`)
+- Specific details (column names, company names, values)
+- Casual language, abbreviations, occasional typos
+
+## Testing whether a description triggers
+
+The basic approach: run each query through your agent with the skill installed, observe whether the agent invokes it. Make sure the skill is registered and discoverable — how varies by client.
+
+Most agents provide observability — execution logs, tool call histories, verbose output — so you can see which skills were consulted. The skill triggered if the agent loaded the SKILL.md; it didn't if the agent proceeded without consulting it.
+
+A query passes if:
+
+- `should_trigger: true` and the skill was invoked, or
+- `should_trigger: false` and the skill was not invoked.
+
+### Running multiple times
+
+Model behavior is nondeterministic — the same query might trigger the skill on one run but not the next. Run each query multiple times (3 is a reasonable start) and compute a **trigger rate**: the fraction of runs where the skill was invoked.
+
+A should-trigger query passes if its trigger rate is above a threshold (0.5 is a reasonable default). A should-not-trigger query passes if its trigger rate is below that threshold.
+
+With 20 queries at 3 runs each, that's 60 invocations. Script it.
+
+```bash
+#!/bin/bash
+# Example: Claude Code with JSON output. Replace the `claude` invocation and
+# detection logic with whatever your agent client provides.
+QUERIES_FILE="${1:?Usage: $0 <queries.json>}"
+SKILL_NAME="my-skill"
+RUNS=3
+
+check_triggered() {
+  local query="$1"
+  claude -p "$query" --output-format json 2>/dev/null \
+    | jq -e --arg skill "$SKILL_NAME" \
+      'any(.messages[].content[]; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
+      > /dev/null 2>&1
+}
+
+count=$(jq length "$QUERIES_FILE")
+for i in $(seq 0 $((count - 1))); do
+  query=$(jq -r ".[$i].query" "$QUERIES_FILE")
+  should_trigger=$(jq -r ".[$i].should_trigger" "$QUERIES_FILE")
+  triggers=0
+
+  for run in $(seq 1 $RUNS); do
+    check_triggered "$query" && triggers=$((triggers + 1))
+  done
+
+  jq -n \
+    --arg query "$query" \
+    --argjson should_trigger "$should_trigger" \
+    --argjson triggers "$triggers" \
+    --argjson runs "$RUNS" \
+    '{query: $query, should_trigger: $should_trigger, triggers: $triggers, runs: $runs, trigger_rate: ($triggers / $runs)}'
+done | jq -s '.'
+```
+
+If your client supports it, stop a run early once the outcome is clear — the agent either consulted the skill or started working without it.
+
+## Avoiding overfitting with train/validation splits
+
+If you optimize the description against all queries, you risk overfitting — a description that works for these phrasings but fails on new ones.
+
+Split the query set:
+
+- **Train set (~60%):** queries you use to identify failures and guide improvements.
+- **Validation set (~40%):** queries set aside, used only to check whether improvements generalize.
+
+Both sets need a proportional mix of should-trigger and should-NOT-trigger. Shuffle randomly, keep the split fixed across iterations so you're comparing apples to apples.
+
+## The optimization loop
+
+1. **Evaluate** the current description on both train and validation sets. Train results guide changes; validation results tell you whether they generalize.
+2. **Identify failures** in the *train* set: which should-trigger queries didn't trigger? Which should-NOT-trigger did? Use only train failures to guide changes.
+3. **Revise the description.** Focus on generalizing:
+   - If should-trigger failures → description may be too narrow. Broaden scope or add context.
+   - If should-NOT-trigger false-positives → too broad. Add specificity about what the skill does NOT do.
+   - Avoid adding specific keywords from failed queries — that's overfitting. Find the general category those queries represent.
+   - If stuck after several iterations, try a structurally different framing rather than incremental tweaks.
+   - Keep description under 1024 chars (descriptions tend to grow).
+4. **Repeat** steps 1-3 until all train queries pass or you stop seeing improvement.
+5. **Select the best iteration** by its validation pass rate. The best description may not be the last — an earlier iteration might generalize better.
+
+Five iterations is usually enough. If performance isn't improving, the issue may be the queries (too easy, too hard, or poorly labeled).
+
+## Applying the result
+
+Once you've selected the best description:
+
+1. Update the `description` field in `SKILL.md` frontmatter.
+2. Verify it's under 1024 chars.
+3. Verify triggering as expected with manual sanity checks. For a rigorous test, write 5-10 fresh queries (mix of should/shouldn't) and run them — these were never in the optimization, so they give an honest generalization check.
+
+Before/after:
+
+```yaml
+# Before
+description: Process CSV files.
+
+# After
+description: >
+  Analyze CSV and tabular data files — compute summary statistics, add derived columns,
+  generate charts, and clean messy data. Use this skill when the user has a CSV, TSV,
+  or Excel file and wants to explore, transform, or visualize the data, even if they
+  don't explicitly mention "CSV" or "analysis."
+```
+
+The improved description is more specific about what the skill does (summary stats, derived columns, charts, cleaning) and broader about when it applies (CSV, TSV, Excel; even without explicit keywords).

package/skills/skill-forge/references/output-evaluation.md

@@ -0,0 +1,276 @@
+# Output Quality Evaluation
+
+> Read this in Phase 5 (OPTIMIZE) when you need to verify that a skill actually improves output quality, not just that it triggers. Workflow skills especially benefit from this loop.
+
+You wrote a skill, tried it on a prompt, and it seemed to work. But does it work reliably — across varied prompts, in edge cases, better than no skill at all? Structured evaluations (evals) answer these and give you a feedback loop for systematic improvement.
+
+## Designing test cases
+
+A test case has three parts:
+
+- **Prompt:** a realistic user message.
+- **Expected output:** a human-readable description of what success looks like.
+- **Input files** (optional): files the skill needs to work with.
+
+Store test cases in `evals/evals.json` inside the skill directory:
+
+```json evals/evals.json
+{
+  "skill_name": "csv-analyzer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a CSV of monthly sales data in data/sales_2025.csv. Can you find the top 3 months by revenue and make a bar chart?",
+      "expected_output": "A bar chart image showing the top 3 months by revenue, with labeled axes and values.",
+      "files": ["evals/files/sales_2025.csv"]
+    },
+    {
+      "id": 2,
+      "prompt": "there's a csv in my downloads called customers.csv, some rows have missing emails — can you clean it up and tell me how many were missing?",
+      "expected_output": "A cleaned CSV with missing emails handled, plus a count of how many were missing.",
+      "files": ["evals/files/customers.csv"]
+    }
+  ]
+}
+```
+
+Tips for good test prompts:
+
+- Start with 2-3. Don't over-invest before seeing the first round of results.
+- Vary the prompts: different phrasings, detail levels, formality.
+- Cover edge cases. Include at least one boundary condition — malformed input, unusual request, or a case where the skill's instructions might be ambiguous.
+- Use realistic context. Real users mention file paths, column names, personal context.
+
+Don't define specific pass/fail checks yet. Add detailed assertions after you see what the first run produces.
+
+## Running evals
+
+The core pattern: run each test case twice — once **with the skill**, once **without it** (or with a previous version). This gives a baseline to compare against.
+
+### Workspace structure
+
+Organize eval results in a workspace directory alongside the skill. Each pass through the full eval loop gets its own `iteration-N/` directory. Within that, each test case gets an eval directory with `with_skill/` and `without_skill/` subdirectories:
+
+```
+csv-analyzer/
+├── SKILL.md
+└── evals/
+    └── evals.json
+csv-analyzer-workspace/
+└── iteration-1/
+    ├── eval-top-months-chart/
+    │   ├── with_skill/
+    │   │   ├── outputs/       # Files produced by the run
+    │   │   ├── timing.json    # Tokens and duration
+    │   │   └── grading.json   # Assertion results
+    │   └── without_skill/
+    │       ├── outputs/
+    │       ├── timing.json
+    │       └── grading.json
+    ├── eval-clean-missing-emails/
+    │   ├── with_skill/
+    │   │   └── ...
+    │   └── without_skill/
+    │       └── ...
+    └── benchmark.json         # Aggregated statistics
+```
+
+The main file you author is `evals/evals.json`. The rest (`grading.json`, `timing.json`, `benchmark.json`) are produced during the eval process.
+
+### Spawning runs
+
+Each run should start with a clean context — no leftover state from previous runs or skill development. In environments with subagents (Claude Code, etc.) this isolation comes naturally; without subagents, use a separate session per run.
+
+For each run, provide:
+
+- The skill path (or no skill for the baseline)
+- The test prompt
+- Any input files
+- The output directory
+
+Example instructions for a single with-skill run:
+
+```
+Execute this task:
+- Skill path: /path/to/csv-analyzer
+- Task: I have a CSV of monthly sales data in data/sales_2025.csv. Can you find the top 3 months by revenue and make a bar chart?
+- Input files: evals/files/sales_2025.csv
+- Save outputs to: csv-analyzer-workspace/iteration-1/eval-top-months-chart/with_skill/outputs/
+```
+
+For the baseline, same prompt but no skill path, saving to `without_skill/outputs/`.
+
+When improving an existing skill, use the previous version as baseline. Snapshot before editing (`cp -r <skill-path> <workspace>/skill-snapshot/`) and point the baseline run at the snapshot.
+
+### Capturing timing data
+
+Record the token count and duration per run:
+
+```json timing.json
+{
+  "total_tokens": 84852,
+  "duration_ms": 23332
+}
+```
+
+A skill that dramatically improves output but triples token usage is a different tradeoff than one that's both better and cheaper.
+
+## Writing assertions
+
+Assertions are verifiable statements about what the output should contain. Add them after you see your first round of outputs — you often don't know what "good" looks like until the skill has run.
+
+Good assertions:
+
+- "The output file is valid JSON" — programmatically verifiable.
+- "The bar chart has labeled axes" — specific and observable.
+- "The report includes at least 3 recommendations" — countable.
+
+Weak assertions:
+
+- "The output is good" — too vague.
+- "The output uses exactly the phrase 'Total Revenue: $X'" — too brittle; correct output with different wording would fail.
+
+Not everything needs an assertion. Style, visual design, "feels right" — those are better caught in human review. Reserve assertions for things checkable objectively.
+
+Add to each test case in `evals/evals.json`:
+
+```json
+{
+  "id": 1,
+  "prompt": "...",
+  "expected_output": "...",
+  "files": ["evals/files/sales_2025.csv"],
+  "assertions": [
+    "The output includes a bar chart image file",
+    "The chart shows exactly 3 months",
+    "Both axes are labeled",
+    "The chart title or caption mentions revenue"
+  ]
+}
+```
+
+## Grading outputs
+
+Evaluate each assertion against the actual outputs and record **PASS** or **FAIL** with specific evidence. The evidence should quote or reference the output, not just state an opinion.
+
+Simplest approach: give outputs and assertions to an LLM and ask it to evaluate each one. For code-checkable assertions (valid JSON, correct row count, file exists with expected dimensions), use a verification script — more reliable than LLM judgment for mechanical checks, and reusable across iterations.
+
+```json grading.json
+{
+  "assertion_results": [
+    {
+      "text": "The output includes a bar chart image file",
+      "passed": true,
+      "evidence": "Found chart.png (45KB) in outputs directory"
+    },
+    {
+      "text": "The chart shows exactly 3 months",
+      "passed": true,
+      "evidence": "Chart displays bars for March, July, November"
+    },
+    {
+      "text": "Both axes are labeled",
+      "passed": false,
+      "evidence": "Y-axis labeled 'Revenue ($)' but X-axis has no label"
+    },
+    {
+      "text": "The chart title or caption mentions revenue",
+      "passed": true,
+      "evidence": "Chart title reads 'Top 3 Months by Revenue'"
+    }
+  ],
+  "summary": {
+    "passed": 3,
+    "failed": 1,
+    "total": 4,
+    "pass_rate": 0.75
+  }
+}
+```
+
+### Grading principles
+
+- **Require concrete evidence for a PASS.** Don't give the benefit of the doubt. If "includes a summary" and the output has a section titled "Summary" with one vague sentence, that's a FAIL.
+- **Review the assertions themselves, not just results.** While grading, notice when assertions are too easy (always pass), too hard (always fail), or unverifiable.
+
+For comparing two skill versions, try **blind comparison**: present both outputs to an LLM judge without revealing which is which. Judge scores holistic qualities — organization, formatting, polish — free from bias.
+
+## Aggregating results
+
+Once every run in the iteration is graded, compute summary statistics per configuration and save to `benchmark.json`:
+
+```json benchmark.json
+{
+  "run_summary": {
+    "with_skill": {
+      "pass_rate": { "mean": 0.83, "stddev": 0.06 },
+      "time_seconds": { "mean": 45.0, "stddev": 12.0 },
+      "tokens": { "mean": 3800, "stddev": 400 }
+    },
+    "without_skill": {
+      "pass_rate": { "mean": 0.33, "stddev": 0.10 },
+      "time_seconds": { "mean": 32.0, "stddev": 8.0 },
+      "tokens": { "mean": 2100, "stddev": 300 }
+    },
+    "delta": {
+      "pass_rate": 0.50,
+      "time_seconds": 13.0,
+      "tokens": 1700
+    }
+  }
+}
+```
+
+`delta` tells you what the skill costs (more time, more tokens) and what it buys (higher pass rate). A skill that adds 13 seconds for a 50-point pass-rate jump is probably worth it. A skill that doubles tokens for 2 points might not be.
+
+Standard deviation is meaningful only with multiple runs per eval. In early iterations with 2-3 cases and single runs, focus on raw pass counts and delta.
+
+## Analyzing patterns
+
+Aggregate statistics can hide important patterns. After computing benchmarks:
+
+- **Remove or replace assertions that always pass in both configurations.** They don't tell you anything.
+- **Investigate assertions that always fail in both.** Either the assertion is broken, the test case is too hard, or the assertion checks the wrong thing.
+- **Study assertions that pass with-skill but fail without.** That's where the skill is clearly adding value. Understand *why* — which instructions or scripts made the difference?
+- **Tighten instructions when results are inconsistent.** High stddev means flaky eval or ambiguous skill instructions. Add examples or more specific guidance.
+- **Check time and token outliers.** If one eval takes 3x longer, read its execution transcript to find the bottleneck.
+
+## Reviewing results with a human
+
+Assertion grading catches a lot, but only what you thought to check for. A human reviewer catches issues you didn't anticipate. For each test case, review the actual outputs alongside the grades.
+
+Record feedback per test case in `feedback.json` next to the eval directories:
+
+```json feedback.json
+{
+  "eval-top-months-chart": "The chart is missing axis labels and the months are in alphabetical order instead of chronological.",
+  "eval-clean-missing-emails": ""
+}
+```
+
+Empty feedback means the output looked fine. Actionable feedback ("missing axis labels") beats vague ("looks bad").
+
+## Iterating on the skill
+
+After grading and reviewing, three sources of signal:
+
+- **Failed assertions** point to specific gaps.
+- **Human feedback** points to broader quality issues.
+- **Execution transcripts** reveal *why* things went wrong.
+
+The most effective way to turn these into improvements: give all three — along with the current `SKILL.md` — to an LLM and ask it to propose changes. When prompting the LLM, include these guidelines:
+
+- **Generalize from feedback.** Fixes should address underlying issues broadly, not narrow patches for specific examples.
+- **Keep the skill lean.** Fewer, better instructions often outperform exhaustive rules. If pass rates plateau despite adding rules, the skill may be over-constrained — try removing instructions.
+- **Explain the why.** Reasoning-based instructions ("Do X because Y tends to cause Z") work better than rigid directives.
+- **Bundle repeated work.** If every test run independently wrote a similar helper script, that's the signal to bundle it.
+
+### The loop
+
+1. Give the eval signals and current `SKILL.md` to an LLM; ask it to propose improvements.
+2. Review and apply changes.
+3. Rerun all test cases in a new `iteration-<N+1>/` directory.
+4. Grade and aggregate.
+5. Review with a human. Repeat.
+
+Stop when you're satisfied, feedback is consistently empty, or you're not seeing meaningful improvement between iterations.

package/skills/skill-forge/references/scripts-guide.md

@@ -0,0 +1,232 @@
+# Scripts Guide
+
+> Read this when designing or bundling scripts in the `scripts/` directory of a skill. The agent runs your scripts and reads stdout/stderr to decide what to do next — design choices here have outsized impact on reliability.
+
+## One-off commands
+
+When an existing package already does what you need, reference it directly in `SKILL.md` without a `scripts/` directory. Many ecosystems provide tools that auto-resolve dependencies at runtime.
+
+| Runner | Install | Use when |
+|---|---|---|
+| `uvx` | Ships with `uv` | Python tools, fast, caches aggressively |
+| `pipx` | OS package manager | Python tools, mature, broad OS availability |
+| `npx` | Ships with npm | Node tools, no extra install |
+| `bunx` | Ships with Bun | Node tools, Bun environment |
+| `deno run` | Ships with Deno | TS/JS with permission flags |
+| `go run` | Built into Go | Go tools, pinned versions |
+
+Examples:
+
+```bash
+uvx ruff@0.8.0 check .
+npx eslint@9 --fix .
+deno run --allow-read npm:eslint@9 -- --fix .
+go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run
+```
+
+Tips for one-off commands in skills:
+
+- **Pin versions** (`npx eslint@9.0.0`) so the command behaves the same over time.
+- **State prerequisites** in `SKILL.md` ("Requires Node.js 18+"). For runtime-level requirements, use the `compatibility` frontmatter field.
+- **Move complex commands into scripts.** When a command grows complex enough that it's hard to get right on the first try, bundle a tested script.
+
+## Referencing scripts from `SKILL.md`
+
+Use **relative paths from the skill directory root** to reference bundled files. The agent resolves these automatically.
+
+List available scripts in your `SKILL.md` so the agent knows they exist:
+
+```markdown
+## Available scripts
+
+- **`scripts/validate.sh`** — Validates configuration files
+- **`scripts/process.py`** — Processes input data
+```
+
+Then instruct the agent to run them:
+
+```markdown
+## Workflow
+
+1. Run the validation script:
+
+   ```bash
+   bash scripts/validate.sh "$INPUT_FILE"
+   ```
+
+2. Process the results:
+
+   ```bash
+   python3 scripts/process.py --input results.json
+   ```
+```
+
+The same relative-path convention works in support files like `references/*.md` — script execution paths are relative to the **skill directory root**.
+
+## Self-contained scripts
+
+When you need reusable logic, bundle a script in `scripts/` that declares its own dependencies inline. The agent can run it with a single command — no separate manifest or install step.
+
+### Python (PEP 723)
+
+Declare dependencies in a TOML block inside `# ///` markers:
+
+```python scripts/extract.py
+# /// script
+# dependencies = [
+#   "beautifulsoup4",
+# ]
+# requires-python = ">=3.11"
+# ///
+
+from bs4 import BeautifulSoup
+
+html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
+print(BeautifulSoup(html, "html.parser").select_one("p.info").get_text())
+```
+
+Run with `uv` (recommended):
+
+```bash
+uv run scripts/extract.py
+```
+
+`uv run` creates an isolated environment, installs declared dependencies, and runs the script. Pin with PEP 508 specifiers: `"beautifulsoup4>=4.12,<5"`. Use `uv lock --script` to create a lockfile for full reproducibility.
+
+### Deno
+
+`npm:` and `jsr:` import specifiers make every script self-contained:
+
+```typescript scripts/extract.ts
+#!/usr/bin/env -S deno run
+
+import * as cheerio from "npm:cheerio@1.0.0";
+
+const html = `<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>`;
+const $ = cheerio.load(html);
+console.log($("p.info").text());
+```
+
+```bash
+deno run scripts/extract.ts
+```
+
+Use `npm:` for npm packages, `jsr:` for Deno-native. Pin with semver: `@1.0.0` exact, `@^1.0.0` compatible. Packages with native addons (node-gyp) may not work; pre-built binaries work best.
+
+### Bun
+
+Bun auto-installs missing packages at runtime when no `node_modules/` exists. Pin versions in the import path:
+
+```typescript scripts/extract.ts
+#!/usr/bin/env bun
+
+import * as cheerio from "cheerio@1.0.0";
+
+const html = `<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>`;
+const $ = cheerio.load(html);
+console.log($("p.info").text());
+```
+
+```bash
+bun run scripts/extract.ts
+```
+
+No `package.json` or `node_modules` needed; TypeScript works natively. If a `node_modules` exists anywhere up the tree, auto-install is disabled and Bun falls back to standard Node resolution.
+
+### Ruby
+
+Bundler ships with Ruby since 2.6. Use `bundler/inline` to declare gems in the script:
+
+```ruby scripts/extract.rb
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'nokogiri'
+end
+
+html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
+doc = Nokogiri::HTML(html)
+puts doc.at_css('p.info').text
+```
+
+```bash
+ruby scripts/extract.rb
+```
+
+Pin versions explicitly (`gem 'nokogiri', '~> 1.16'`) — there's no lockfile. An existing `Gemfile` or `BUNDLE_GEMFILE` env var in the working directory can interfere.
+
+## Designing scripts for agentic use
+
+When the agent runs your script, it reads stdout and stderr to decide what to do next. A few design choices make scripts dramatically easier to use.
+
+### Avoid interactive prompts
+
+Hard requirement of the agent environment. Agents operate in non-interactive shells — they cannot respond to TTY prompts, password dialogs, or confirmation menus. A script that blocks on interactive input will hang indefinitely.
+
+Accept all input via command-line flags, environment variables, or stdin:
+
+```text
+# Bad: hangs waiting for input
+$ python scripts/deploy.py
+Target environment: _
+
+# Good: clear error with guidance
+$ python scripts/deploy.py
+Error: --env is required. Options: development, staging, production.
+Usage: python scripts/deploy.py --env staging --tag v1.2.3
+```
+
+### Document usage with `--help`
+
+`--help` output is the primary way an agent learns your script's interface. Include a brief description, available flags, and usage examples:
+
+```text
+Usage: scripts/process.py [OPTIONS] INPUT_FILE
+
+Process input data and produce a summary report.
+
+Options:
+  --format FORMAT    Output format: json, csv, table (default: json)
+  --output FILE      Write output to FILE instead of stdout
+  --verbose          Print progress to stderr
+
+Examples:
+  scripts/process.py data.csv
+  scripts/process.py --format csv --output report.csv data.csv
+```
+
+Keep it concise — the output enters the agent's context window alongside everything else.
+
+### Write helpful error messages
+
+When an agent gets an error, the message directly shapes its next attempt. Opaque "Error: invalid input" wastes a turn. Say what went wrong, what was expected, and what to try:
+
+```text
+Error: --format must be one of: json, csv, table.
+       Received: "xml"
+```
+
+### Use structured output
+
+Prefer structured formats — JSON, CSV, TSV — over free-form text. Structured formats can be consumed by both the agent and standard tools (`jq`, `cut`, `awk`):
+
+```text
+# Whitespace-aligned — hard to parse
+NAME          STATUS    CREATED
+my-service    running   2025-01-15
+
+# Delimited — unambiguous
+{"name": "my-service", "status": "running", "created": "2025-01-15"}
+```
+
+**Separate data from diagnostics:** send structured data to stdout and progress messages, warnings, and other diagnostics to stderr. The agent can capture clean output while keeping access to diagnostic info.
+
+### Further considerations
+
+- **Idempotency.** Agents may retry. "Create if not exists" is safer than "create and fail on duplicate."
+- **Input constraints.** Reject ambiguous input with a clear error rather than guessing. Use enums and closed sets where possible.
+- **Dry-run support.** For destructive or stateful operations, a `--dry-run` flag lets the agent preview what will happen.
+- **Meaningful exit codes.** Use distinct exit codes for different failure types (not found, invalid arguments, auth failure) and document them in `--help` so the agent knows what each code means.
+- **Safe defaults.** Consider whether destructive operations should require explicit confirmation (`--confirm`, `--force`) or other safeguards appropriate to the risk level.
+- **Predictable output size.** Many harnesses automatically truncate tool output beyond a threshold (e.g. 10-30K characters), potentially losing critical information. If your script may produce large output, default to a summary and support flags like `--offset` for pagination, or require an explicit `--output` flag.