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

kpis-snapshot

Shows your key business metrics in one quick snapshot.
description: "Triggers on prompt mention of 'kpis-snapshot', 'snappy-os pulse', 'system pulse', 'health snapshot', 'skills count', 'how many skills'."
personal 2 files
Export

What it does for you

Shows your key business metrics in one quick snapshot.

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

actorRoute handler at GET /kpis-snapshot plus the prose
auditorIndependent shape
eval modeauto-shape

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/kpis-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/kpis-snapshot.ts present
code the skill can run
Reusable code this skill can call when it needs to.
Scripts
state/bin/kpis-snapshot/ not present
helper scripts
Optional. Added when a skill has a few commands to run.
Loader
state/skills/kpis-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 runs - the shared frame every skill uses 4/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
Route handler at GET /kpis-snapshot plus the prose an AI model
Does the actual work. Whatever it produces is what gets checked next.
checks the work The reviewer
present
Independent shape the checker
A separate checker grades the work, so the part that made it can't approve its own work.
frame
learns Self-correction
not present

This skill doesn't fix its own gaps yet.

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 auto-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
  1. WRONG (hardcoded value): kpi1 = StatCard("275 Skills Registered", "large")
  2. WRONG (CanvasFrame/CanvasPanel are invalid primitives AND hardcoded): root = CanvasFrame([CanvasPanel("snappy-os Pulse", ..., [Card([CardHeader("73", "skills alive")])])])
  3. RIGHT: data = Query("get_kpis", {}, {skillsAlive: 0, scheduled: 0, dispatches: 0}, 60) then kpi1 = StatCard("Skills", "" + data.skillsAlive)
  4. CanvasFrame and CanvasPanel are NOT valid OpenUI primitives. Never use them.

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 Route handler at GET /kpis-snapshot plus the prose
auditor Independent shape

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

kpis-snapshot

Producer skill that closes the catalog-to-cockpit drift gap for the KPIBlock shape: when the cockpit asks "give me a snappy-os pulse" or "what's the health of the system", the dispatcher used to fall back to plain text because no skill emitted a KPIBlock. kpis-snapshot reads three on-disk signals - distinct slugs in state/log/evals.ndjson over the last 7 days, scheduled agents in state/agents/*.json, and total chat dispatch rows in state/log/dispatch-chat.ndjson - and emits one inline marker:

[[TOOL:KPIBlock]]{"title":"snappy-os pulse","value":"<N> skills","delta":"<M> scheduled","deltaTone":"info","subtitle":"<D> dispatches"}[[/TOOL]]

The server lifts the marker into a TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple; snappy-os renders the KPIBlock card via web/src/genui-library.tsx → KPIBlockComponent.

The route handler at GET /kpis-snapshot (in state/bin/head-screen/server.ts) returns the same JSON shape so the LLM has a deterministic example it can mimic when it chooses to emit a KPIBlock during an SSE chat stream.

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

Steps

  1. Read state/log/evals.ndjson. Count distinct skill field values whose

ts is within the last 7 days (rolling). That count is value - render it as "<N> skills".

  1. Read every JSON file in state/agents/*.json. Count those whose

status is "running" or "scheduled". That count is delta - render it as "<M> scheduled". Tone stays "info" regardless; this shape is informational, not pass/fail.

  1. Read state/log/dispatch-chat.ndjson. Count non-empty rows. That count

is subtitle - render it as "<D> dispatches".

  1. Build the JSON object `{title:"snappy-os pulse", value, delta,

deltaTone:"info", subtitle} and emit a single [[TOOL:KPIBlock]]{...}[[/TOOL]]` marker on its own line in the assistant text stream. The server's marker-lifter does the rest.

Trigger phrases the dispatcher should recognize: "snappy-os pulse", "system pulse", "kpi snapshot", "health snapshot", "skills count", "how many skills".

Route handler

GET /kpis-snapshot on 127.0.0.1:3147 returns:

{
  "ok": true,
  "marker": "[[TOOL:KPIBlock]]{\"title\":\"snappy-os pulse\",\"value\":\"157 skills\",\"delta\":\"10 scheduled\",\"deltaTone\":\"info\",\"subtitle\":\"42 dispatches\"}[[/TOOL]]",
  "kpis": { "skills": 157, "scheduled": 10, "dispatches": 42 }
}

The kpis field carries the raw integers so callers (other skills, the brain layer) can read the same numbers without re-parsing the marker. The marker string is the canonical inline form the LLM mimics.

Eval

Actor: the route handler at GET /kpis-snapshot plus the prose Steps above (the agent walks the three reads and emits one marker). Auditor: independent shape check - the emitted marker MUST match the KPIBlockComponent Zod schema in snappy-chat/web/src/genui-library.tsx (positional order: title, value, delta, deltaTone, subtitle; deltaTone ∈ {ok, warn, info}).

OutcomeScore
Marker emitted with all five fields, deltaTone in enum, all three integers >= 01.0
Marker emitted but a count is wrong (e.g. agents miscounted)0.5
Plain text fallback or marker malformed0.0

Eval Criteria

criteria:
  - name: marker_valid_and_emitted
    kind: deterministic
    check: "Marker is emitted (not text fallback); has {title, value, delta, deltaTone, subtitle}; deltaTone ∈ {ok,warn,info}; all values are non-null strings."
  - name: skill_count_nonzero
    kind: deterministic
    check: "skills count (distinct evals.ndjson slugs, last 7d) ≥ 1 (not zero). Counts at least one skill ran recently."
  - name: numbers_accurate_vs_disk
    kind: deterministic
    check: "skills = count(distinct skill in evals last 7d). scheduled = count(agents with status ∈ {running,scheduled}). dispatches = line_count(dispatch-chat.ndjson)."
  - name: dispatcher_not_fallback
    kind: deterministic
    check: "Eval verb is NOT 'text-fallback'; TOOL_CALL_* events emit (not plain prose). If intent didn't match, score is 0.0."

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

kpis-snapshot - loader

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

Critical Rules

  1. NEVER hardcode KPI values as literals. Numbers like "73 skills alive" or "14 scheduled" are stale the moment you emit them. ALL numbers MUST come from Query("get_kpis", ...). There are no exceptions.
  • WRONG (hardcoded value): kpi1 = StatCard("275 Skills Registered", "large")
  • WRONG (CanvasFrame/CanvasPanel are invalid primitives AND hardcoded): root = CanvasFrame([CanvasPanel("snappy-os Pulse", ..., [Card([CardHeader("73", "skills alive")])])])
  • RIGHT: data = Query("get_kpis", {}, {skillsAlive: 0, scheduled: 0, dispatches: 0}, 60) then kpi1 = StatCard("Skills", "" + data.skillsAlive)
  • CanvasFrame and CanvasPanel are NOT valid OpenUI primitives. Never use them.
  1. Pure read. NEVER writes. Scope-only by snappy-os convention; no probe is allowed to mutate state. If asked to "refresh" or "rebuild" the pulse, re-read the three signals - do not write a derived cache.
  2. deltaTone enum is ok|warn|info - exactly. The KPIBlockComponent Zod schema in snappy-chat/web/src/genui-library.tsx validates this; any off-enum value renders nothing or trips the fallback. For pulse snapshots default to info.
  3. Single emit per turn. Exactly one [[TOOL:KPIBlock]] marker per response. The dispatcher MUST NOT re-emit if llmEmittedNames already contains KPIBlock.
  4. Three numbers come from Query("get_kpis", ...), not from Bash disk reads. DO NOT use Bash to read state/log/evals.ndjson, state/agents/*.json, or state/log/dispatch-chat.ndjson and embed the counts as literals. Use Query("get_kpis", {}, {skillsAlive: 0, scheduled: 0, pending: 0}, 60) in compose_inline; the runtime fetches live counts. Response field paths: data.skillsAlive, data.scheduled, data.pending.
  5. Marker stays on its own line. The server's marker-lifter scans the assistant text stream; markers split across tokens are tolerated, but a marker buried mid-prose can collide with surrounding punctuation.
  6. Positional-key order matters. The marker JSON shape is fixed: {title, value, delta, deltaTone, subtitle}. The renderer reads by name (Zod), but the SKILL.md contract documents the order - keep emitter and eval contract in lockstep.

Commands

| ui model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact |

stepcommand
invoke (LLM emit)emit [[TOOL:KPIBlock]]{"title":"snappy-os pulse","value":"<N> skills","delta":"<M> scheduled","deltaTone":"info","subtitle":"<D> dispatches"}[[/TOOL]] on its own line
invoke (compose_inline)see Lang example below - DO NOT read disk files in Bash and embed counts as literals

Lang surface example

data = Query("get_kpis", {}, {skillsAlive: 0, scheduled: 0, dispatches: 0}, 60)
root = Stack([
  StatCard("Skills", "" + data.skillsAlive),
  StatCard("Scheduled", "" + data.scheduled),
  StatCard("Dispatches", "" + data.dispatches)
], "row")

Response fields: data.skillsAlive, data.scheduled, data.dispatches Keep it simple - 4 components total (Query + Stack + 3 StatCards). No buttons, no controls unless specifically requested. | route (deterministic) | GET http://127.0.0.1:3147/kpis-snapshot → {ok, marker, kpis:{skills, scheduled, pending}} | | trigger phrases | "snappy-os pulse" \| "system pulse" \| "kpi snapshot" \| "health snapshot" \| "skills count" \| "how many skills" | | score | shape ok + tone in enum + 3 ints ≥0 → 1.0 ; shape ok but a count wrong → 0.5 ; plain text fallback or marker malformed → 0.0 | | eval log | state/log/evals.ndjson (skill: kpis-snapshot, eval_mode: auto-shape) | | reference | state/skills/kpis-snapshot/SKILL.md |

Known Pitfalls

  • KPIBlockComponent accepts value as string OR number. The route renders "<N> skills" (string) by convention; a bare number renders but loses the unit.
  • On a fresh clone with empty evals.ndjson, value is "0 skills". That's honest, not a bug. Do not pad.
  • Adding a fourth signal (e.g. open PRs) requires lockstep changes in BOTH state/bin/head-screen/server.ts (route handler) AND state/skills/kpis-snapshot/SKILL.md eval contract.
  • The marker MUST land on its own line in the SSE text stream. Mid-prose embedding is tolerated by the lifter but increases false-negative rate against punctuation neighbours.
  • Distinct-slug count is a 7-day ROLLING window, not "this week". Off-by-one bugs come from interpreting "this week" as calendar-week.

Self-Test

An agent reading this should correctly:

  1. [ ] Know this is a prose-only producer skill backed by GET /kpis-snapshot in state/bin/head-screen/server.ts (no separate state/lib/kpis-snapshot.ts)?
  2. [ ] Pick deltaTone from {ok, warn, info} only, defaulting to info for pulse snapshots?
  3. [ ] Refuse to emit a KPIBlock if llmEmittedNames already contains it (single-emit-per-turn)?
  4. [ ] Use Query("get_kpis", ...) in compose_inline rather than reading on-disk signals directly?
  5. [ ] Append the run to state/log/evals.ndjson with skill "kpis-snapshot" and eval_mode: auto-shape from the SKILL.md frontmatter?

Found a gap? Edit this file. <!-- footer-injection-point -->

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-kpis-snapshot/api.ts — emit KPIBlock marker for snappy-os health.
 */
import { score, dispatchRunId, normalizeEvalRow } from './eval.ts';
import { readFileSync, readdirSync } from 'fs';

// Step 1: Count distinct skills in evals.ndjson from last 7 days
const evalsData = readFileSync('./state/log/evals.ndjson', 'utf8')
  .split('\n')
  .filter((l) => l.trim());
const now = new Date();
const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);

const skills = new Set<string>();
for (const line of evalsData) {
  try {
    const parsed = JSON.parse(line);
    const row = normalizeEvalRow(parsed); // Normalize verb → skill for backward compatibility
    // The `ts` column is appended by postRow() but is not part of EvalRow's
    // canonical shape. Read it through a narrowed view.
    const tsRaw = (row as { ts?: string }).ts;
    if (typeof tsRaw !== "string") continue;
    const ts = new Date(tsRaw);
    if (ts > sevenDaysAgo) {
      // skill is now guaranteed (normalizeEvalRow migrates verb → skill)
      const skillName = row.skill;
      if (skillName) skills.add(skillName);
    }
  } catch {
    // skip parse errors
  }
}
const skillsCount = skills.size;

// Step 2: Count running/scheduled agents
let scheduledCount = 0;
try {
  const agentFiles = readdirSync('./state/agents').filter((f) => f.endsWith('.json'));
  for (const file of agentFiles) {
    try {
      const agent = JSON.parse(readFileSync(`./state/agents/${file}`, 'utf8'));
      if (agent.status === 'running' || agent.status === 'scheduled') {
        scheduledCount++;
      }
    } catch {
      // skip parse errors
    }
  }
} catch {
  // skip if directory doesn't exist
}

// Step 3: Count chat dispatches
let dispatchCount = 0;
try {
  const content = readFileSync('./state/log/dispatch-chat.ndjson', 'utf8');
  dispatchCount = content.split('\n').filter((l) => l.trim().length > 0).length;
} catch {
  // skip missing file
}

// Step 4: Build and emit marker
const marker = `[[TOOL:KPIBlock]]{"title":"snappy-os pulse","value":"${skillsCount} skills","delta":"${scheduledCount} scheduled","deltaTone":"info","subtitle":"${dispatchCount} dispatches"}[[/TOOL]]`;
console.log(marker);

// Score: all fields present, deltaTone in enum, all ints >= 0
const isValid =
  skillsCount >= 0 && scheduledCount >= 0 && dispatchCount >= 0;

const runId = dispatchRunId() || 'kpis-' + Date.now().toString(36);
score('kpis-snapshot', runId, {
  score: isValid ? 1.0 : 0.5,
  primary_issue: isValid ? null : 'shape-validation-failed',
  skills: skillsCount,
  scheduled: scheduledCount,
  dispatches: dispatchCount,
});

scripts- helper scripts it can run

prose-only skill - 3 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

rubric auto-shape no rubric declared
recent no runs actor/auditor: unverifiable
deps none declared

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