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

criteria:
  - name: api_sniffer_output_exists
    kind: deterministic
    check: "A non-empty output file, e.g., 'sniffer.log', is present after execution."
  - name: api_sniffer_log_format
    kind: judge
    check: "The output log adheres to the expected format for captured XHR/fetch traffic."
  - name: captured_traffic_relevance
    kind: judge
    check: "The captured traffic directly relates to the actions implied by 'capture_input', 'loadSnifferRecipe_input', and 'replay_input'."
  - name: no_runtime_errors
    kind: deterministic
    check: "The skill execution completes without throwing unhandled exceptions or critical errors visible in stdout/stderr or logs."

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

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

echo "[$(date -u +%FT%TZ)] api-sniffer: <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-api-sniffer/api.ts -- Capture XHR/fetch traffic from a real browser session
 * and emit replayable "recipes" that consumer skills can call with plain fetch().
 *
 * Why this exists: many surfaces (Skool, LinkedIn feeds, etc.) gate their internal
 * APIs behind JS challenges or Next.js middleware that reject cookie-curl. Running
 * them through a real Playwright session via snappy-browse captures the real calls;
 * this skill turns those calls into replay recipes.
 *
 * Composition (DRY):
 *   snappy-browse ------ Playwright transport (navigate, eval, network requests)
 *     └─ snappy-api-sniffer ------ capture → filter → emit recipe → replay
 *
 * Usage:
 *   npx tsx api.ts capture https://www.skool.com/snappy "api2.skool.com" skool-feed
 *     → navigates, waits, filters requests by URL substring, writes recipe json
 *
 *   npx tsx api.ts replay skool-feed
 *     → reads recipe, re-executes via fetch() with stored cookies
 */

import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
import { join, dirname } from "path";
import { env } from "./env.ts";
import {
  navigate,
  clearRequests,
  captureRequests,
  close,
  type CapturedRequest,
} from "./browse.ts";

const RECIPE_DIR = join(process.env.HOME!, ".claude/skills/snappy-api-sniffer/recipes");

export interface ApiRecipe {
  name: string;
  captured_at: string;
  source_url: string;
  filter: string;
  requests: CapturedRequest[];
  cookies_hint?: string; // path to auth state file used at capture time
}

/** Normalize a captured request into a shape consumer skills can replay. */
function toRecipeEntry(r: CapturedRequest) {
  return {
    url: r.url,
    method: r.method,
    resource_type: r.resource_type,
    status: r.status,
    // Strip cookies from headers (cookies come from the state file at replay time)
    request_headers: Object.fromEntries(
      Object.entries(r.request_headers || {}).filter(([k]) => k.toLowerCase() !== "cookie")
    ),
    post_data: r.post_data,
  };
}

/**
 * Capture all XHR/fetch traffic on a page and write a recipe file.
 * sourceUrl: where to navigate. filter: substring/pattern to keep.
 * statePath: optional Playwright storage_state.json to load cookies from.
 */
export async function capture(
  name: string,
  sourceUrl: string,
  filter: string,
  opts: { statePath?: string; waitMs?: number } = {}
): Promise<ApiRecipe> {
  const waitMs = opts.waitMs ?? 4000;
  // Force fresh daemon if a state file was supplied — otherwise --state is ignored.
  if (opts.statePath) {
    try { close(); } catch {}
  }
  navigate(sourceUrl, opts.statePath);
  clearRequests();
  // Trigger a soft reload so the settled page re-fires its XHRs and they land in the capture buffer.
  try { navigate(sourceUrl, opts.statePath); } catch {}
  await new Promise((r) => setTimeout(r, waitMs));

  const all = captureRequests(filter);
  const xhrOnly = all.filter(
    (r) => r.resource_type === "xhr" || r.resource_type === "fetch"
  );

  const recipe: ApiRecipe = {
    name,
    captured_at: new Date().toISOString(),
    source_url: sourceUrl,
    filter,
    requests: xhrOnly.map(toRecipeEntry) as CapturedRequest[],
    cookies_hint: opts.statePath,
  };

  mkdirSync(RECIPE_DIR, { recursive: true });
  const path = join(RECIPE_DIR, `${name}.json`);
  writeFileSync(path, JSON.stringify(recipe, null, 2));
  return recipe;
}

/** Load a previously-captured recipe. */
export function loadSnifferRecipe(name: string): ApiRecipe {
  const path = join(RECIPE_DIR, `${name}.json`);
  if (!existsSync(path)) throw new Error(`Recipe not found: ${path}`);
  return JSON.parse(readFileSync(path, "utf-8"));
}

/**
 * Replay a single request from a recipe via plain fetch().
 * Loads cookies from the recipe's statePath (Playwright storage_state format).
 */
export async function replay(
  recipeName: string,
  index = 0,
  overrides: { urlRewrite?: (u: string) => string } = {}
): Promise<{ status: number; body: string }> {
  const recipe = loadSnifferRecipe(recipeName);
  const entry = recipe.requests[index];
  if (!entry) throw new Error(`Recipe ${recipeName} has no request #${index}`);

  let cookie = "";
  if (recipe.cookies_hint && existsSync(recipe.cookies_hint)) {
    const state = JSON.parse(readFileSync(recipe.cookies_hint, "utf-8"));
    cookie = (state.cookies || [])
      .map((c: { name: string; value: string }) => `${c.name}=${c.value}`)
      .join("; ");
  }

  const url = overrides.urlRewrite ? overrides.urlRewrite(entry.url) : entry.url;
  const headers: Record<string, string> = {
    ...(entry.request_headers || {}),
    ...(cookie ? { Cookie: cookie } : {}),
  };
  // Drop headers that fetch refuses to set
  for (const h of ["host", "content-length", "connection"]) delete headers[h];

  const res = await fetch(url, {
    method: entry.method,
    headers,
    body: entry.post_data,
  });
  const body = await res.text();
  return { status: res.status, body };
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;
    switch (cmd) {
      case "capture": {
        const [sourceUrl, filter, name, statePath] = args;
        if (!sourceUrl || !filter || !name) {
          console.error("Usage: api.ts capture <url> <filter> <name> [statePath]");
          process.exit(1);
        }
        const recipe = await capture(name, sourceUrl, filter, { statePath });
        console.log(`captured ${recipe.requests.length} requests → ${name}.json`);
        for (const r of recipe.requests) {
          console.log(`  ${r.method} ${r.url}`);
        }
        try { close(); } catch {}
        break;
      }
      case "replay": {
        const [name, idxStr] = args;
        if (!name) { console.error("Usage: api.ts replay <name> [index]"); process.exit(1); }
        const out = await replay(name, Number(idxStr || 0));
        console.log(`status=${out.status}`);
        console.log(out.body.slice(0, 2000));
        break;
      }
      case "list": {
        const recipe = loadSnifferRecipe(args[0]);
        for (let i = 0; i < recipe.requests.length; i++) {
          console.log(`${i}: ${recipe.requests[i].method} ${recipe.requests[i].url}`);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [capture|replay|list] ...");
    }
  })();
}

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