snappy-hello

The hello-world skill. Read this to see the minimum shape of a snappy-os skill before you write your own. Every section below is the minimum; yours can grow.

When to use

• First run after npx snappy-os init. Confirms the loop works end-to-end.
• Smoke test for new installs - one round-trip through dispatch → eval → log.

Commands

snappy-os run snappy-hello            # real run; writes one row to evals.ndjson
snappy-os run snappy-hello --dry-run  # scope-only; greeting → stderr, apply:false

Self-test

snappy-os run snappy-hello
tail -1 state/log/evals.ndjson | jq '.actor_session_id != .auditor_session_id'
# → true

Eval

Actor prints the greeting to stdout and writes a pending row with actor_session_id set. An auditor child-process re-reads stdout, grades the greeting shape, writes auditor_session_id back onto the same row. Actor ≠ auditor holds because the auditor runs in a separate subprocess.

Rubric

criteria:
  - name: greeting_sent_to_stdout
    kind: deterministic
    check: "The command 'snappy-os run snappy-hello' prints a greeting to stdout."
  - name: eval_row_written
    kind: deterministic
    check: "A new row is appended to 'state/log/evals.ndjson' after 'snappy-os run snappy-hello' completes."
  - name: actor_id_in_eval_row
    kind: deterministic
    check: "The new eval row in 'state/log/evals.ndjson' contains an 'actor_session_id' field."
  - name: auditor_updates_eval_row
    kind: deterministic
    check: "The same eval row is subsequently updated to include an 'auditor_session_id' field."
  - name: actor_auditor_ids_differ
    kind: deterministic
    check: "The 'actor_session_id' and 'auditor_session_id' in the eval row are different, as verified by 'tail -1 state/log/evals.ndjson | jq '.actor_session_id != .auditor_session_id''."

snappy-hello - per-turn loader

UI Resources

• state/skills/snappy-hello/resources/ui.openui

The hello-world skill. Proves the loop works end-to-end on a fresh install.

Command index

Invariants

• Exit 0 on success. Non-zero exit is a bug; fix, don't retry.
• Real run: greeting to stdout, eval row apply: true.
• Dry-run: greeting to stderr, eval row apply: false. No side effects.
• actor_session_id ≠ auditor_session_id on every row (actor is this process;

auditor is a child process the actor spawns after greeting to grade stdout).

Gotchas

• .env.cache is optional for this skill - env("USER", false) falls back to

$USER from the process environment. Skills that need real credentials document that on their own .md page.

• The greeting format is load-bearing: the auditor subprocess checks it starts

with hello, and contains the snappy-os version. Don't "improve" the phrasing without updating the auditor.

<!-- 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)] snappy-hello: <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.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/snappy-hello/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.