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

criteria:
  - name: box_result_nonzero
    kind: deterministic
    check: "Called function returns non-empty/non-null result. listRoutes returns array with length > 0. runSql/callRoute return object with data fields. deploy returns {status, ...}."
  - name: http_200_success
    kind: deterministic
    check: "Box server HTTP response code is 200/201 (success). No timeout, connection refused, or 5xx errors in logs."
  - name: result_matches_api
    kind: deterministic
    check: "Result schema matches Box REST API. Routes array includes {id, path, ...}. SQL result includes rows or affected_count. callRoute returns the endpoint response."
  - name: eval_row_persisted
    kind: deterministic
    check: "state/log/evals.ndjson or state/log/pending-eval.ndjson receives row with skill='box', score, and result summary."

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-box/api.ts -- Box server HTTP API for all snappy-* skills.
 *
 * Required env vars (set in .env.cache):
 *   SNAPPY_BOX_URL        - Base URL of your box server, e.g. http://192.168.1.10:8080
 *   BOX_API_KEY           - API key for x-api-key auth
 *
 * Optional env vars:
 *   SNAPPY_BOX_SSH_TARGET - SSH target for retrieving BOX_API_KEY, e.g. user@192.168.1.10
 *
 * If SNAPPY_BOX_URL is not set, all box calls return a feature-unavailable message.
 *
 * Boundary: box = the Box self-editing server (routes, SQL, deploy routes).
 *   snappy-deploy = trigger Vercel/Fly deployments.
 *   snappy-infra = health probes + SSH to box.
 *
 * Usage:
 *   npx tsx api.ts routes                  # list deployed routes
 *   npx tsx api.ts sql "SELECT 1"          # run SQL query
 *   npx tsx api.ts call GET /pulse         # call any route
 *
 * Or import as module:
 *   import { listRoutes, runSql, deploy, callRoute } from "./box.ts";
 */

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

const BOX_URL: string | null = process.env.SNAPPY_BOX_URL ?? null;

function apiKey(): string {
  return env("BOX_API_KEY", false);
}

async function box(
  path: string,
  options?: { method?: string; body?: unknown }
): Promise<unknown> {
  if (!BOX_URL) {
    throw new Error(
      "[snappy-box] feature unavailable: set SNAPPY_BOX_URL=http://your-box:port in .env.cache"
    );
  }

  const key = apiKey();
  if (!key) {
    const sshTarget = process.env.SNAPPY_BOX_SSH_TARGET ?? "<box-host>";
    throw new Error(
      "[snappy-box] BOX_API_KEY not in .env.cache. " +
      `Retrieve via: ssh ${sshTarget} "/usr/local/bin/docker exec box-box-1 printenv BOX_API_KEY". ` +
      "Set SNAPPY_BOX_URL and SNAPPY_BOX_SSH_TARGET to point at your box."
    );
  }

  const res = await fetch(`${BOX_URL}${path}`, {
    method: options?.method || "GET",
    headers: {
      "x-api-key": key,
      ...(options?.body ? { "Content-Type": "application/json" } : {}),
    },
    body: options?.body ? JSON.stringify(options.body) : undefined,
  });

  const text = await res.text();
  try {
    return JSON.parse(text);
  } catch {
    if (!res.ok) throw new Error(`Box ${path} failed (${res.status}): ${text}`);
    return text;
  }
}

// --- Public API ---

/** List all deployed routes. */
export async function listRoutes() {
  return box("/_routes");
}

/** Run a SQL query against Box's internal database. */
export async function runSql(query: string) {
  return box("/system/sql", { method: "POST", body: { query } });
}

/**
 * Deploy a route to Box.
 * routeConfig should include: name, method, path, code, and optionally pack, meta.
 */
export async function deploy(routeConfig: {
  name: string;
  method: string;
  path: string;
  code: string;
  pack?: string;
  meta?: { description?: string; inputs?: unknown[]; outputs?: unknown };
}) {
  return box("/_deploy", { method: "POST", body: routeConfig });
}

/** Generic route caller -- hit any Box endpoint. */
export async function callRoute(method: string, path: string, body?: unknown) {
  return box(path, { method, body: body || undefined });
}

// --- CLI ---

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

    switch (cmd) {
      case "routes": {
        const data = await listRoutes() as { deployed?: { name: string; method: string; path: string }[] };
        if (data?.deployed) {
          for (const r of data.deployed) {
            console.log(`${r.method}\t${r.path}\t${r.name}`);
          }
        } else {
          console.log(JSON.stringify(data, null, 2));
        }
        break;
      }
      case "sql": {
        const [query] = args;
        if (!query) { console.error("Usage: api.ts sql <query>"); process.exit(1); }
        const result = await runSql(query);
        console.log(JSON.stringify(result, null, 2));
        break;
      }
      case "call": {
        const [method, path, ...bodyParts] = args;
        if (!method || !path) { console.error("Usage: api.ts call <METHOD> <path> [json-body]"); process.exit(1); }
        const body = bodyParts.length ? JSON.parse(bodyParts.join(" ")) : undefined;
        const result = await callRoute(method, path, body);
        console.log(JSON.stringify(result, null, 2));
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [routes|sql|call] ...");
    }
  })();
}

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

no recent runs logged - the eval contract is declared but nothing has been graded yet