SKILL.md- the skill, written out in plain English

criteria:
  - name: generate_content_responds
    kind: deterministic
    check: "Skill completes without error when generateContent_input is provided and does not timeout."
  - name: describe_image_responds
    kind: deterministic
    check: "Skill completes without error when describeImage_input is provided and does not timeout."
  - name: generate_image_responds
    kind: deterministic
    check: "Skill completes without error when generateImage_input is provided and does not timeout."
  - name: response_relevance_and_quality
    kind: judge
    check: "The output of the Gemini model function called (generateContent, describeImage, or generateImage) is relevant to the input and of high quality."

AGENTS.md- what the AI loads when this skill comes up

echo "[$(date -u +%FT%TZ)] gemini: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] gemini: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-gemini/api.ts -- Google Generative AI REST API for all snappy-* skills.
 *
 * Uses GEMINI_API_KEY from snappy-settings/.env.cache.
 * Direct REST calls to generativelanguage.googleapis.com.
 *
 * Usage:
 *   npx tsx api.ts generate "Explain quantum tunneling"
 *   npx tsx api.ts generate "Summarize this" --model gemini-2.5-pro
 *
 * Or import as module:
 *   import { generateContent, generateContentStream, describeImage } from "./gemini.ts";
 */

import { env } from "./env.ts";
import { readFileSync, realpathSync } from "fs";

const BASE = "https://generativelanguage.googleapis.com/v1beta";
const DEFAULT_MODEL = "gemini-2.5-flash";

interface GeminiOptions {
  model?: string;
  systemInstruction?: string;
  temperature?: number;
  maxTokens?: number;
  responseSchema?: Record<string, unknown>;
}

async function gemini(model: string, body: Record<string, unknown>, stream = false) {
  const endpoint = stream ? "streamGenerateContent?alt=sse" : "generateContent";
  const res = await fetch(`${BASE}/models/${model}:${endpoint}`, {
    method: "POST",
    headers: {
      "x-goog-api-key": env("GEMINI_API_KEY"),
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`Gemini ${model} failed (${res.status}): ${err}`);
  }
  return stream ? res : res.json();
}

function buildRequest(prompt: string, opts: GeminiOptions, extraParts?: Record<string, unknown>[]) {
  const body: Record<string, unknown> = {
    contents: [{ parts: [{ text: prompt }, ...(extraParts || [])] }],
    generationConfig: {
      ...(opts.temperature != null ? { temperature: opts.temperature } : {}),
      ...(opts.maxTokens ? { maxOutputTokens: opts.maxTokens } : {}),
      ...(opts.responseSchema ? { responseMimeType: "application/json", responseSchema: opts.responseSchema } : {}),
    },
  };
  if (opts.systemInstruction) {
    body.systemInstruction = { parts: [{ text: opts.systemInstruction }] };
  }
  return body;
}

// --- Public API ---

export async function generateContent(prompt: string, opts: GeminiOptions = {}): Promise<{ text: string; raw: unknown }> {
  const model = opts.model || DEFAULT_MODEL;
  const body = buildRequest(prompt, opts);
  const data = await gemini(model, body) as any;
  const text = data.candidates?.[0]?.content?.parts?.[0]?.text || "";
  return { text, raw: data };
}

export async function* generateContentStream(prompt: string, opts: GeminiOptions = {}): AsyncGenerator<string> {
  const model = opts.model || DEFAULT_MODEL;
  const body = buildRequest(prompt, opts);
  const res = await gemini(model, body, true) as Response;
  const reader = res.body!.getReader();
  const decoder = new TextDecoder();
  let buf = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    const lines = buf.split("\n");
    buf = lines.pop() || "";
    for (const line of lines) {
      if (!line.startsWith("data: ")) continue;
      const json = line.slice(6);
      if (json === "[DONE]") return;
      try {
        const chunk = JSON.parse(json);
        const text = chunk.candidates?.[0]?.content?.parts?.[0]?.text;
        if (text) yield text;
      } catch {}
    }
  }
}

export async function describeImage(imageUrl: string, prompt = "Describe this image in detail."): Promise<{ text: string; raw: unknown }> {
  const model = DEFAULT_MODEL;
  let inlineData: { mimeType: string; data: string } | undefined;
  let fileUri: string | undefined;

  if (imageUrl.startsWith("http")) {
    // Fetch and inline as base64
    const res = await fetch(imageUrl);
    const buf = Buffer.from(await res.arrayBuffer());
    const mime = res.headers.get("content-type") || "image/png";
    inlineData = { mimeType: mime, data: buf.toString("base64") };
  } else {
    // Local file
    const data = readFileSync(imageUrl);
    const ext = imageUrl.split(".").pop()?.toLowerCase();
    const mimeMap: Record<string, string> = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
    inlineData = { mimeType: mimeMap[ext || ""] || "image/png", data: data.toString("base64") };
  }

  const body: Record<string, unknown> = {
    contents: [{
      parts: [
        { text: prompt },
        ...(inlineData ? [{ inlineData }] : []),
      ],
    }],
  };

  const data = await gemini(model, body) as any;
  const text = data.candidates?.[0]?.content?.parts?.[0]?.text || "";
  return { text, raw: data };
}

export async function generateImage(
  prompt: string,
  opts: { model?: string; out?: string; ref?: string | string[] } = {}
): Promise<{ b64: string; mime: string; path?: string }> {
  const model = opts.model || "gemini-3.1-flash-image-preview";
  const parts: Record<string, unknown>[] = [{ text: prompt }];

  const refs: string[] = opts.ref ? (Array.isArray(opts.ref) ? opts.ref : [opts.ref]) : [];
  for (const refPath of refs) {
    const data = readFileSync(refPath);
    const ext = refPath.split(".").pop()?.toLowerCase();
    const mimeMap: Record<string, string> = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp" };
    parts.push({ inlineData: { mimeType: mimeMap[ext || ""] || "image/png", data: data.toString("base64") } });
  }

  const body = {
    contents: [{ role: "user", parts }],
    generationConfig: { responseModalities: ["IMAGE", "TEXT"] },
  };

  const data = await gemini(model, body) as any;
  const imagePart = data.candidates?.[0]?.content?.parts?.find((p: any) => p.inlineData);
  if (!imagePart) throw new Error("Gemini returned no image");

  const result = { b64: imagePart.inlineData.data, mime: imagePart.inlineData.mimeType, path: undefined as string | undefined };

  if (opts.out) {
    const { writeFileSync } = await import("fs");
    writeFileSync(opts.out, Buffer.from(result.b64, "base64"));
    result.path = opts.out;
  }

  return result;
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "generate": {
        const prompt = args.filter(a => !a.startsWith("--")).join(" ");
        const modelIdx = args.indexOf("--model");
        const model = modelIdx >= 0 ? args[modelIdx + 1] : undefined;
        if (!prompt) { console.error("Usage: api.ts generate <prompt> [--model <model>]"); process.exit(1); }
        const { text } = await generateContent(prompt, { model });
        console.log(text);
        break;
      }
      case "describe": {
        const imageUrl = args[0];
        const prompt = args.slice(1).join(" ") || undefined;
        if (!imageUrl) { console.error("Usage: api.ts describe <image_url_or_path> [prompt]"); process.exit(1); }
        const { text } = await describeImage(imageUrl, prompt);
        console.log(text);
        break;
      }
      case "image": {
        const prompt = args.filter(a => !a.startsWith("--")).join(" ");
        const modelIdx = args.indexOf("--model");
        const model = modelIdx >= 0 ? args[modelIdx + 1] : undefined;
        const outIdx = args.indexOf("--out");
        const out = outIdx >= 0 ? args[outIdx + 1] : undefined;
        // Collect all --ref flags (supports multiple refs)
        const refs: string[] = [];
        for (let i = 0; i < args.length; i++) {
          if (args[i] === "--ref" && args[i + 1]) refs.push(args[i + 1]);
        }
        if (!prompt) { console.error("Usage: api.ts image <prompt> [--model <model>] [--out <path>] [--ref <path> ...]"); process.exit(1); }
        const result = await generateImage(prompt, { model, out, ref: refs.length ? refs : undefined });
        if (result.path) console.log(result.path);
        else console.log(JSON.stringify({ mime: result.mime, b64_length: result.b64.length }));
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [generate|describe|image] ...");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs