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

criteria:
  - name: corpus_function_returns_nonzero
    kind: deterministic
    check: "Called function returns non-null result. listTranscripts returns array.length > 0. readTranscript returns {id, content, ...}. searchCorpus returns array with matches."
  - name: function_executes_no_errors
    kind: deterministic
    check: "Function completes with exit code 0; stderr empty or warnings-only. No auth/auth_expired or timeout errors."
  - name: result_matches_schema
    kind: deterministic
    check: "listTranscripts returns array of {id, title, date, ...}. readTranscript returns {id, text, speakers, ...}. searchCorpus returns {query, results: [...]}"
  - name: eval_row_logged
    kind: deterministic
    check: "state/log/evals.ndjson or state/log/pending-eval.ndjson receives row with skill='corpus', score, item_count."

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

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-corpus/api.ts -- Krisp transcript corpus operations for all snappy-* skills.
 *
 * Usage:
 *   npx tsx api.ts list                    # list all transcripts
 *   npx tsx api.ts list 2026 04            # list transcripts for April 2026
 *   npx tsx api.ts read <path> [offset] [limit]  # read transcript in chunks
 *   npx tsx api.ts search <query>          # grep across all transcripts
 *
 * Or import as module:
 *   import { listTranscripts, readTranscript, searchCorpus } from "./corpus.ts";
 */

import { existsSync, readFileSync, realpathSync } from "fs";
import { join, resolve, relative } from "path";
import { execSync, execFileSync } from "child_process";
import { env } from "./env.ts";

const CORPUS_ROOT = join(process.env.HOME!, ".claude/corpus/krisp");

/** Lists transcript .md files, optionally filtered by year/month. Excludes .summary.md and .nuggets.json. */
export function listTranscripts(year?: string, month?: string): string[] {
  // Validate year and month parameters to prevent injection
  if (year && !/^\d{4}$/.test(year)) throw new Error("year must be YYYY format");
  if (month && !/^\d{2}$/.test(month)) throw new Error("month must be MM format");

  const pattern = year && month
    ? `${CORPUS_ROOT}/${year}/${month}/*.md`
    : year
    ? `${CORPUS_ROOT}/${year}/**/*.md`
    : `${CORPUS_ROOT}/**/*.md`;

  try {
    const output = execSync(`ls ${pattern} 2>/dev/null || true`, { encoding: "utf-8" });
    return output
      .split("\n")
      .filter((f: string) => f.endsWith(".md") && !f.endsWith(".summary.md"))
      .sort();
  } catch {
    return [];
  }
}

/** Reads a transcript file in chunks. Default: first 200 lines. */
export function readTranscript(path: string, offset = 0, limit = 200): { lines: string[]; total: number } {
  // Reject absolute paths
  if (path.startsWith("/")) throw new Error("absolute paths not allowed");
  // Resolve and verify path is within CORPUS_ROOT
  const absPath = resolve(CORPUS_ROOT, path);
  const rel = relative(CORPUS_ROOT, absPath);
  if (rel.startsWith("..")) throw new Error("path traversal not allowed");
  if (!existsSync(absPath)) throw new Error(`Transcript not found: ${absPath}`);
  const content = readFileSync(absPath, "utf-8");
  const allLines = content.split("\n");
  return {
    lines: allLines.slice(offset, offset + limit),
    total: allLines.length,
  };
}

/** Greps across all transcripts for a query string. Returns matching file:line pairs. */
export function searchCorpus(query: string): { file: string; line: number; text: string }[] {
  try {
    const output = execFileSync(
      "grep",
      ["-rni", "--include=*.md", "--", query, CORPUS_ROOT + "/"],
      { encoding: "utf-8", timeout: 30_000 }
    );
    return output
      .split("\n")
      .filter((line) => line.length > 0 && !line.includes(".summary.md"))
      .slice(0, 100)
      .map((line) => {
        const firstColon = line.indexOf(":");
        const secondColon = line.indexOf(":", firstColon + 1);
        return {
          file: line.slice(0, firstColon),
          line: parseInt(line.slice(firstColon + 1, secondColon), 10) || 0,
          text: line.slice(secondColon + 1).trim(),
        };
      });
  } catch {
    return [];
  }
}

// --- CLI ---

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

    switch (cmd) {
      case "list": {
        const [year, month] = args;
        const files = listTranscripts(year, month);
        console.log(`${files.length} transcripts:`);
        for (const f of files) console.log(`  ${f}`);
        break;
      }
      case "read": {
        const [path, offsetStr, limitStr] = args;
        if (!path) { console.error("Usage: api.ts read <path> [offset] [limit]"); process.exit(1); }
        const result = readTranscript(path, parseInt(offsetStr) || 0, parseInt(limitStr) || 200);
        console.log(`Lines ${parseInt(offsetStr) || 0}-${(parseInt(offsetStr) || 0) + result.lines.length} of ${result.total}:`);
        console.log(result.lines.join("\n"));
        break;
      }
      case "search": {
        const query = args.join(" ");
        if (!query) { console.error("Usage: api.ts search <query>"); process.exit(1); }
        const results = searchCorpus(query);
        console.log(`${results.length} matches:`);
        for (const r of results) {
          console.log(`  ${r.file}:${r.line}\t${r.text.slice(0, 120)}`);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|read|search] ...");
    }
  })();
}

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