drop another .md file to compare - side-by-side diff against gateway

gateway

Manages how your skills are shared and who can access them.

description: "Triggers on prompt mention of 'gateway'."

personal 2 files 10 recent evals

Export

What it does for you

Manages how your skills are shared and who can access them.

What it produces

A recent result, so you can see the kind of work it returns.

loading…

How to get it

These run inside the Snappy workspace. Want this working in your business? I set skills like this up with you, in one focused week.

Work with me

For developers how this skill is built, graded, and how it runs

at a glance- the short version

actorExported functions in state/lib/gateway.ts.

auditorNone wired yet - eval is manual (Robert review).

eval modeshape

categorySystem

stages3

dependssettings

what's inside - the parts that make up a skill 3/4 present

A skill is just a few plain-text files. Only the main one is required. The rest are optional, added as the work needs them. This is what the skill is made of; how it runs is just below.

The skill

state/skills/gateway/SKILL.md present

the skill itself, in plain text

The main file. It says what the skill is and lays out the steps in plain English.

Code

state/lib/gateway.ts present

code the skill can run

Reusable code this skill can call when it needs to.

Scripts

state/bin/gateway/ not present

helper scripts

Optional. Added when a skill has a few commands to run.

Loader

state/skills/gateway/AGENTS.md present

what the AI loads on the fly

Loaded automatically the moment this skill is needed. Kept short on purpose.

how it's graded - what counts as a good run 4 criteria · 3 deterministic · 1 judge

Each row is one thing a good run has to get right. deterministic means a quick check decides, pass or fail. judge means the AI reads the result and rates it. Grading each piece on its own (instead of one overall score) shows exactly where a run fell short, so the fix is obvious.

name

kind

check

calls_gateway_functions

deterministic

The skill execution invokes listSkills(), getSkill(), and publishSkill() functions from 'state/lib/gateway.ts'.

receives_valid_responses

judge

The outputs from listSkills(), getSkill(), and publishSkill() are valid and correctly formatted JSON representing skill data.

handles_input_parameters

deterministic

The skill correctly uses the provided listSkills_input, getSkill_input, and publishSkill_input parameters when calling the respective gateway functions.

logs_pending_eval_row

deterministic

The skill execution creates a new row in 'state/log/pending-eval.ndjson' for manual evaluation as per the Auditor instructions.

how it runs - the shared frame every skill uses 5/5 present

Every skill runs the same way. One part does the work, a separate part checks it, and a short loader hands the AI exactly what it needs for the job. Anything this skill doesn't use shows a one-line note saying why, on purpose, not by accident.

makes the work The worker

present

Exported functions in state/lib/gateway.ts. the worker

Does the actual work. Whatever it produces is what gets checked next.

checks the work The reviewer

present

None wired yet - eval is manual (Robert review). the checker

A separate checker grades the work, so the part that made it can't approve its own work.

frame

learns Self-correction

present

fixes itself learns from gaps

When a run hits a gap, the skill gets edited on the spot [FIXED] or queued for a bigger rewrite [LOGGED], so it keeps getting better.

tidies up Background fixes

present

queued for rewrite runs in the background

Bigger fixes that can't be made on the spot get queued and rewritten in the background later.

remembers Run history

present

state/log/pending-eval.ndjson pending runs

Every run is written down here, then reviewed by hand each week.

Critical rules the things this skill must not get wrong

The Worker at skills.snappy.ai is the only ingress to DO Spaces. Joe machines never hold DO credentials. (program.md sync section)
POST /_push and GET /_pull authenticate via SNAPPY_MASTER_KEY and derive tenant_id server-side; tenant prefixes are enforced on every write.
Public-tier reads (catalog, detail, docs, status, changelog) work without a key. Personal/client/subscriber tiers gated by per-tenant grants in s3://robert-storage/snappy-os-meta/tenants/<tenant_id>.json.
Default sync scope is state/. To push human-owned layers, MUST pass --scope program or --scope sources explicitly.

what it has learned - fixes written back in over time sample

When a run hits something this skill didn't handle, the fix gets written back into the skill so it doesn't happen again. FIXED means it was corrected on the spot. LOGGED means it's queued for a bigger rewrite. Either way, the skill gets a little better and never makes the same mistake twice.

Loading feedback rows…

how the work flows- who makes it, who checks it

inputs settings

actor Exported functions in state/lib/gateway.ts.

1 generator

invoke

actor = Exported functions in state/lib/gateway.ts.

import from `state/lib/gateway.ts` — `listSkills()`, `getSkill()`, `publishSkill()

+ eval for this step

auditor None wired yet - eval is manual (Robert review).

2 auditor

inspect

auditor = None wired yet - eval is manual (Robert review).

getSkill(name)` after publish to confirm the round-trip

+ eval for this step

3 data

eval log

`state/log/pending-eval.ndjson` (manual eval — skill: "gateway")

+ eval for this step

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

gateway

Skills gateway operations at skills.snappy.ai.

Ported from kernel snappy-gateway in Phase 0.5. See state/lib/gateway.ts for the full API surface.

Steps

listSkills() - see state/lib/gateway.ts
getSkill() - see state/lib/gateway.ts
publishSkill() - see state/lib/gateway.ts

Eval

Actor: the exported functions in state/lib/gateway.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Outcome	Score
Pass on first try	1.0
Failed first, auto-fix applied, re-check passed	0.5
Still failing or unrecoverable	0.0

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

realpathSync(process.argv[1]) CLI guard wrapped in try/catch

See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: calls_gateway_functions
    kind: deterministic
    check: "The skill execution invokes listSkills(), getSkill(), and publishSkill() functions from 'state/lib/gateway.ts'."
  - name: receives_valid_responses
    kind: judge
    check: "The outputs from listSkills(), getSkill(), and publishSkill() are valid and correctly formatted JSON representing skill data."
  - name: handles_input_parameters
    kind: deterministic
    check: "The skill correctly uses the provided listSkills_input, getSkill_input, and publishSkill_input parameters when calling the respective gateway functions."
  - name: logs_pending_eval_row
    kind: deterministic
    check: "The skill execution creates a new row in 'state/log/pending-eval.ndjson' for manual evaluation as per the Auditor instructions."

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

gateway - loader

Per-turn rules for the gateway skill. Full reference: state/skills/gateway/SKILL.md. Do not skip these.

Critical Rules

The Worker at skills.snappy.ai is the only ingress to DO Spaces. Joe machines never hold DO credentials. (program.md sync section)
POST /_push and GET /_pull authenticate via SNAPPY_MASTER_KEY and derive tenant_id server-side; tenant prefixes are enforced on every write.
Public-tier reads (catalog, detail, docs, status, changelog) work without a key. Personal/client/subscriber tiers gated by per-tenant grants in s3://robert-storage/snappy-os-meta/tenants/<tenant_id>.json.
Default sync scope is state/. To push human-owned layers, MUST pass --scope program or --scope sources explicitly.

Commands

| ui dashboard | state/skills/gateway/resources/ui.openui | |invoke: import from state/lib/gateway.ts - listSkills(), getSkill(), publishSkill() |verify: getSkill(name) after publish to confirm the round-trip |eval log: state/log/pending-eval.ndjson (manual eval - skill: "gateway")

OpenUI Resource

Skill-owned OpenUI Lang resource: state/skills/gateway/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

Hook fetch from gateway is cached 5 min, falls back to local repo if offline (program.md self-bootstrap section)
Wiki phases 1-15 (sync-primitives → ci-for-sync) document the worker contract - read state/docs/guides/worker-architecture.md before changing routes
Multi-batch push: Node's https module shares its SSL_CTX (and TLS session-ticket cache) across requests even when agent: false is set - agent: false only disables pooling, not crypto-state isolation. After Cloudflare invalidates a session ticket post-batch-1 response, batch 2 reuses the bad ticket and fails deterministically with ssl3_read_bytes: bad record mac (alert 20). Fix in bin/cli.js httpRequest (commit e04c9c8, 2026-04-27): build a fresh new https.Agent({keepAlive:false, maxSockets:1}) per request, .destroy() it after, and retry-once with 500ms backoff on transient TLS errors (bad record mac, ECONNRESET, EPIPE, socket hang up, alert 20/21). Don't revert.
.DS_Store and binary captures (state/bin/head-screen/captures/*.png, *.zip) trip sync-integrity.ts post-push drift even when the push itself succeeded - pre-existing, unrelated to TLS. Two paths to close: add .DS_Store to SYNC_DENY in cli.js or add eventual-consistency tolerance in the verifier.

Self-Test

An agent reading this should correctly:

[ ] Authenticate via SNAPPY_MASTER_KEY, never bake DO credentials into a Joe machine
[ ] Default sync scope to state/, require explicit flag for program/sources
[ ] Verify a publish with a fresh getSkill read

Self-report

If this loader fell short, append a line:

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

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

"I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

The goal: the next agent never has to leave the loader.

2. Log the result.

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

FIXED = you patched this loader inline (P-fix).
LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-gateway/api.ts -- Skills gateway operations at skills.snappy.ai.
 *
 * List, get, and publish skills via the gateway API + admin endpoints.
 *
 * Usage:
 *   npx tsx api.ts list
 *   npx tsx api.ts get snappy-slack
 *   npx tsx api.ts publish snappy-slack
 *
 * Or import as module:
 *   import { listSkills, getSkill, publishSkill } from "./gateway.ts";
 */

import { execSync } from "child_process";
import { env } from "./env.ts";
import { join } from "path";
import { realpathSync } from "fs";

const GATEWAY = "https://skills.snappy.ai";
const SKILLS_DIR = join(process.env.HOME!, ".claude/skills");
const PUBLISH_SCRIPT = join(process.env.HOME!, "projects/snappy-skills/scripts/publish-skill.js");

function masterKey(): string {
  return env("SNAPPY_GATEWAY_MASTER_KEY", false) || env("MASTER_KEY", false) || "";
}

/** List all skills from the gateway catalog. */
export async function listSkills(): Promise<any[]> {
  const key = masterKey();
  const headers: Record<string, string> = key ? { Authorization: `Bearer ${key}` } : {};
  const res = await fetch(`${GATEWAY}/.well-known/skills/index.json`, { headers });
  if (!res.ok) throw new Error(`Gateway list failed: ${res.status}`);
  const data = await res.json();
  return data.skills || [];
}

/** Get a specific skill's metadata from the catalog. */
export async function getSkill(name: string): Promise<any> {
  const key = masterKey();
  const headers: Record<string, string> = key ? { Authorization: `Bearer ${key}` } : {};
  const res = await fetch(`${GATEWAY}/.well-known/skills/${name}/SKILL.md`, { headers });
  if (!res.ok) throw new Error(`Skill ${name} not found: ${res.status}`);
  return { name, content: await res.text() };
}

/** Publish a skill from local skills dir to the gateway KV. */
export function publishSkill(skillName: string, tier = "personal"): string {
  const skillPath = join(SKILLS_DIR, skillName);
  const output = execSync(
    `node ${PUBLISH_SCRIPT} ${skillName} ${skillPath} ${tier}`,
    { encoding: "utf-8", timeout: 30_000, cwd: join(process.env.HOME!, "projects/snappy-skills") }
  ).trim();

  // Rebuild graph after publish
  const key = masterKey();
  if (key) {
    try {
      execSync(
        `curl -sf -H "Authorization: Bearer ${key}" ${GATEWAY}/admin/graph/rebuild`,
        { encoding: "utf-8", timeout: 15_000 }
      );
    } catch {
      // Graph rebuild is best-effort
    }
  }

  return output;
}

// --- 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 skills = await listSkills();
        for (const s of skills) {
          console.log(`${s.name}\t${s.tier || "?"}\t${s.description || ""}`);
        }
        break;
      }
      case "get": {
        const [name] = args;
        if (!name) { console.error("Usage: api.ts get <name>"); process.exit(1); }
        const skill = await getSkill(name);
        console.log(skill.content);
        break;
      }
      case "publish": {
        const [name, tier] = args;
        if (!name) { console.error("Usage: api.ts publish <name> [tier]"); process.exit(1); }
        console.log(publishSkill(name, tier || "personal"));
        console.log("published");
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|get|publish] ...");
    }
  })();
}

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

rubric shape schema-shape check (no inline rubric)

recent mean 1.00 · 10 runs actor/auditor: unverifiable

deps settings

timestamp	verb	score	primary_issue	artifact
2026-04-25 04:11Z	-	1.00	-	-
2026-04-21 15:58Z	-	1.00	-	-
2026-04-21 15:56Z	-	1.00	-	-
2026-04-21 03:53Z	-	1.00	-	-
2026-04-25 04:11Z	-	1.00	-	-
2026-04-21 15:58Z	-	1.00	-	-
2026-04-21 15:56Z	-	1.00	-	-
2026-04-21 03:53Z	-	1.00	-	-
2026-04-25 04:11Z	-	1.00	-	-
2026-04-21 15:58Z	-	1.00	-	-