OR Key
drop another .md file to compare - side-by-side diff against bundle-snapshot

bundle-snapshot

Shows what's connected and switched on in your setup at a glance.
description: "Triggers on prompt mention of 'bundle-snapshot', 'what is the bundle context', 'what's mounted', 'show me connectors', 'bundle status'."
personal 2 files 3 recent evals
Export

What it does for you

Shows what's connected and switched on in your setup at a glance.

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

actorSnapshot() in state/lib/bundle-snapshot.ts.
auditorState/lint/library-shape.ts (the lib must export
eval modeshape
stages2

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/bundle-snapshot/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/bundle-snapshot.ts present
code the skill can run
Reusable code this skill can call when it needs to.
Scripts
state/bin/bundle-snapshot/ not present
helper scripts
Optional. Added when a skill has a few commands to run.
Loader
state/skills/bundle-snapshot/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 3 criteria · 2 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
shape_matches_parser
deterministic
snapshot() returns { contextPanel: { connectors: [...] } } where each connector has id, label, status in {on|off|loading}, optional icon — exactly the shape parseContextPanelArgs in web/src/tool-args.ts accepts.
dispatcher_intent_match
deterministic
Trigger phrases route to a ContextPanel TOOL_CALL emission, not text fallback.
bundle_signal_truth
judge
Bundle connector status reflects the real /bundle/status response: 'on' when mounted and not ejected, 'off' otherwise.

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
Snapshot() in state/lib/bundle-snapshot.ts. the worker
Does the actual work. Whatever it produces is what gets checked next.
checks the work The reviewer
present
State/lint/library-shape.ts (the lib must export 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/evals.ndjson shape runs
Every run is written down here, so the next time this skill is used it already knows how the last runs went.
Critical rules the things this skill must not get wrong
No must-not-break rules called out for this skill. Anything important lives in the writeup below.

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.

  1. Loading feedback rows…

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

actor Snapshot() in state/lib/bundle-snapshot.ts.
1 generator
invoke
actor = Snapshot() in state/lib/bundle-snapshot.ts.
import { snapshot } from "../lib/bundle-snapshot.ts"
+ eval for this step
auditor State/lint/library-shape.ts (the lib must export
2 data
eval log
`state/log/evals.ndjson` (skill: "bundle-snapshot", eval_mode: shape)
+ eval for this step

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

bundle-snapshot

Producer skill that closes the catalog-to-cockpit drift gap: when the cockpit asks "what is the snappy-os bundle context", the dispatcher used to fall back to plain text because no skill emitted the right TOOL_CALL_ARGS shape. bundle-snapshot reads the head-screen /bundle/status endpoint plus a couple of on-disk signals and shapes them into the ContextPanel contract that snappy-chat/web/src/tool-args.ts:parseContextPanelArgs accepts.

The lib at state/lib/bundle-snapshot.ts is the action scope. The dispatcher at state/bin/head-screen/server.ts wires the intent matcher and emits the TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple after the assistant text streams.

Pure read. Never writes. Scope-only by snappy-os convention.

Steps

  1. snapshot({ headScreenUrl?, offline? }):
  • Probe ${HEAD_SCREEN_BASE}/bundle/status (2s timeout). On any failure

return null and downgrade the head-screen connector to off.

  • Read state/config/dispatch.json for chat.backend / chat.model.
  • Check .env.cache presence at the repo root.
  • Build six connector chips: bundle, head-screen, dispatch, credentials,

web, browser. Each chip carries {id, label, status, icon} per the parseContextPanelArgs shape.

Dispatcher wiring

state/bin/head-screen/server.ts adds a regex matcher to the chat dispatch intent loop. Trigger phrases: "what is the bundle context", "what's mounted", "show me connectors", "bundle status". When matched and llmEmittedNames does not already contain ContextPanel, the dispatcher imports snapshot() from this lib and calls emitTriple("ContextPanel", payload.contextPanel).

Eval

Actor: snapshot() in state/lib/bundle-snapshot.ts. Auditor: state/lint/library-shape.ts (the lib must export snapshot) plus the dogfood loop screenshot that proves the card rendered (not text fallback).

OutcomeScore
Card renders in chat with bundle path + connector states1.0
Card renders but a connector status is wrong0.5
Plain text fallback (intent didn't match)0.0

Rubric

criteria:
  - name: shape_matches_parser
    kind: deterministic
    check: "snapshot() returns { contextPanel: { connectors: [...] } } where each connector has id, label, status in {on|off|loading}, optional icon — exactly the shape parseContextPanelArgs in web/src/tool-args.ts accepts."
  - name: dispatcher_intent_match
    kind: deterministic
    check: "Trigger phrases route to a ContextPanel TOOL_CALL emission, not text fallback."
  - name: bundle_signal_truth
    kind: judge
    check: "Bundle connector status reflects the real /bundle/status response: 'on' when mounted and not ejected, 'off' otherwise."

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

bundle-snapshot - loader

Per-turn rules for the bundle-snapshot skill. Closes the catalog-to-cockpit drift gap: when the cockpit asks "what's mounted?", this producer emits a ContextPanel payload that snappy-chat's generative UI renders inline.

Lib: state/lib/bundle-snapshot.ts. Dispatcher: state/bin/head-screen/server.ts (regex matcher → emitTriple("ContextPanel", payload.contextPanel)).

Critical Rules

  1. Pure read. NEVER writes. Scope-only by snappy-os convention; no probe is allowed to mutate state.
  2. Status enum is on|off|loading - exactly. parseContextPanelArgs validates this; any off-enum value kills the card silently.
  3. Single emit per turn. The dispatcher MUST NOT re-emit ContextPanel if llmEmittedNames already contains it.
  4. 2s probe timeout. Slow networks must NOT block the card render. On timeout, downgrade head-screen connector to off and continue rendering the other five.
  5. Bundle chip reflects real /bundle/status. on only when mounted and not ejected; off otherwise. Never fake-green.

Commands

| ui dashboard | state/skills/bundle-snapshot/resources/ui.openui | |invoke: import { snapshot } from "../lib/bundle-snapshot.ts" |cli: npx tsx state/lib/bundle-snapshot.ts (returns JSON to stdout) |dispatcher: state/bin/head-screen/server.ts (regex matcher + emitTriple("ContextPanel", payload.contextPanel)) |trigger phrases: "what is the bundle context" / "what's mounted" / "show me connectors" / "bundle status" |reads: GET ${HEAD_SCREEN_BASE}/bundle/status (2s timeout); state/config/dispatch.json; .env.cache |eval log: state/log/evals.ndjson (skill: "bundle-snapshot", eval_mode: shape)

Six connectors

Hard-coded chip set returned as {id, label, status, icon} per parseContextPanelArgs:

  • bundle - mount state from /bundle/status
  • head-screen - cockpit reachability on 127.0.0.1:3147 (or HEAD_SCREEN_URL)
  • dispatch - chat backend/model from state/config/dispatch.json
  • credentials - .env.cache presence at repo root
  • web - outbound web reachability flag
  • browser - agent-browser availability

Trigger phrases

  • "what is the bundle context"
  • "what's mounted"
  • "show me connectors"
  • "bundle status"

OpenUI Resource

  • Skill-owned OpenUI Lang resource: state/skills/bundle-snapshot/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

  • /bundle/status hits 127.0.0.1:3147 by default. If the head-screen server is dead, that single chip flips to off - the rest still render. Restart with bash state/bin/head-screen/launch.sh.
  • HEAD_SCREEN_URL env override is required for non-default cockpit instances. Pass via snapshot({ headScreenUrl }) or env.
  • Six connectors are hard-coded. Adding a seventh requires changes in BOTH state/lib/bundle-snapshot.ts AND the snappy-chat ContextPanel renderer - keep them in lockstep.

Self-Test

An agent reading this should correctly:

  1. [ ] Confirm no chip status returned by snapshot() falls outside on|off|loading
  2. [ ] Confirm the dispatcher's regex matcher recognizes all four trigger phrases
  3. [ ] Confirm the /bundle/status probe is bounded by a 2s timeout (non-blocking on failure)
  4. [ ] Confirm the snapshot path is pure-read - no writes anywhere in the call graph
  5. [ ] Confirm only one ContextPanel emit per turn (llmEmittedNames guard honored)

Self-report

If this loader fell short, append a line:

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

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

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)] bundle-snapshot: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log
  • <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

  • 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.

  • action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

  • shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

  • skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

  • loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

  • pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

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
/**
 * state/lib/bundle-snapshot.ts -- read snappy-os bundle + connector state
 * and produce a ContextPanel payload for the snappy-chat generative UI.
 *
 * Closes the catalog→cockpit drift gap surfaced by the dogfood loop: the
 * intent "what is the snappy-os bundle context" used to fall back to plain
 * text because no producer skill emitted the right TOOL_CALL shape.
 *
 * The shape matches web/src/tool-args.ts:parseContextPanelArgs — a flat
 * list of connector chips. Each chip carries:
 *   - id     stable slug used as React key
 *   - label  human-readable name
 *   - status "on" | "off" | "loading"
 *   - icon?  optional glyph hint
 *
 *   import { snapshot } from "../lib/bundle-snapshot.ts";
 *   const { contextPanel } = await snapshot();
 *
 * Pure read. Never writes. Scope-only by snappy-os convention.
 */

import { existsSync, readFileSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");

const HEAD_SCREEN_BASE =
  process.env.HEAD_SCREEN_URL ?? "http://127.0.0.1:3147";

export type ContextPanelStatus = "on" | "off" | "loading";

export interface ContextPanelConnector {
  id: string;
  label: string;
  status: ContextPanelStatus;
  icon?: string;
}

export interface ContextPanelPayload {
  connectors: ContextPanelConnector[];
}

export interface SnapshotOpts {
  /** Override head-screen base URL (mostly for tests). */
  headScreenUrl?: string;
  /** Skip the live HTTP probe and read bundle status from disk only. */
  offline?: boolean;
}

interface BundleStatus {
  ok?: boolean;
  mounted?: boolean;
  ejected?: boolean;
  root?: string | null;
  meta?: { name?: string | null } | null;
  default_root?: string | null;
}

async function fetchBundleStatus(base: string): Promise<BundleStatus | null> {
  try {
    const res = await fetch(`${base}/bundle/status`, {
      signal: AbortSignal.timeout(2_000),
    });
    if (!res.ok) return null;
    return (await res.json()) as BundleStatus;
  } catch {
    return null;
  }
}

function readEnvCachePresence(): boolean {
  // The .env.cache symlink in the repo root is the canonical credential
  // store. If it's missing or broken, the secrets connector is "off".
  const p = join(ROOT, ".env.cache");
  return existsSync(p);
}

function readDispatchConfigBackend(): { backend: string | null; model: string | null } {
  const p = join(ROOT, "state", "config", "dispatch.json");
  if (!existsSync(p)) return { backend: null, model: null };
  try {
    const o = JSON.parse(readFileSync(p, "utf8")) as {
      chat?: { backend?: string; model?: string };
    };
    return {
      backend: o.chat?.backend ?? null,
      model: o.chat?.model ?? null,
    };
  } catch {
    return { backend: null, model: null };
  }
}

/**
 * Build a ContextPanel describing the active bundle and the connectors the
 * cockpit knows about. Connector status is derived from disk where
 * possible; the head-screen HTTP probe is consulted for live mount state
 * with a 2s timeout so the function never blocks the dispatcher.
 */
export async function snapshot(
  opts: SnapshotOpts = {},
): Promise<{ contextPanel: ContextPanelPayload }> {
  const base = opts.headScreenUrl ?? HEAD_SCREEN_BASE;
  const status = opts.offline ? null : await fetchBundleStatus(base);

  const mounted = status?.mounted === true && status?.ejected !== true;
  const bundleName =
    (status?.meta && status.meta.name) ||
    (status?.root ? status.root.replace(/^.*\//, "") : null);
  const bundleLabel = mounted
    ? `snappy-os bundle (${bundleName ?? "mounted"})`
    : "snappy-os bundle";
  const bundleStatusToken: ContextPanelStatus = mounted ? "on" : "off";

  const dispatch = readDispatchConfigBackend();
  const dispatchLabel = dispatch.backend
    ? `chat backend (${dispatch.backend}${dispatch.model ? " / " + dispatch.model : ""})`
    : "chat backend";
  const dispatchStatus: ContextPanelStatus = dispatch.backend ? "on" : "off";

  const credsStatus: ContextPanelStatus = readEnvCachePresence() ? "on" : "off";

  const connectors: ContextPanelConnector[] = [
    {
      id: "bundle",
      label: bundleLabel,
      status: bundleStatusToken,
      icon: "bundle",
    },
    {
      id: "head-screen",
      label: "head-screen server (127.0.0.1:3147)",
      status: status === null ? "off" : "on",
      icon: "server",
    },
    {
      id: "dispatch",
      label: dispatchLabel,
      status: dispatchStatus,
      icon: "dispatch",
    },
    {
      id: "credentials",
      label: "credentials (.env.cache)",
      status: credsStatus,
      icon: "key",
    },
    {
      id: "web",
      label: "Web search",
      status: "off",
      icon: "web",
    },
    {
      id: "browser",
      label: "Claude in Chrome",
      status: "off",
      icon: "browser",
    },
  ];

  return { contextPanel: { connectors } };
}

// CLI smoke-test path: `npx tsx state/lib/bundle-snapshot.ts`
const isMain = (() => {
  try {
    const argv1 = process.argv[1];
    if (!argv1) return false;
    return import.meta.url === new URL(`file://${argv1}`).href
      || import.meta.url.endsWith(argv1);
  } catch { return false; }
})();
if (isMain) {
  snapshot().then(out => {
    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
  }).catch(err => {
    console.error(`bundle-snapshot: ${err}`);
    process.exit(1);
  });
}

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 3 runs

rubric shape schema-shape check (no inline rubric)
recent mean 1.00 · 3 runs actor/auditor: unverifiable
deps none declared
timestamp verb score primary_issue artifact
2026-04-29 04:31Z - 1.00 - -
2026-04-29 04:31Z - 1.00 - -
2026-04-29 04:31Z - 1.00 - -