snappy-list

One job: answer "what background agents do I have running right now, on this machine?" The byline stacks up to 3 🤖 rows and then overflows to 🤖 +N more · → /snappy-list. This skill is where the full list lives.

Usage

/snappy-list

No argument. Reads state/agents/*.json and prints one line per agent.

Steps

1. Run:

   bash ~/projects/snappy-os/state/bin/agents/list.sh

1. Parse the JSON on stdout. For each agent, show:

• id (e.g. default, content-miner)
• status (running / paused / stopped / done)
• ticks/max_ticks
• last_tick_at as relative age (e.g. 4m ago, —)
• the first 60 chars of prompt

1. If none are running, say so in one line and exit - don't offer to

invent work.

1. If any agent is running, optionally call AskUserQuestion with one

question per agent offering Pause / Resume / Stop / Leave running. Apply the picks via ctl.ts pause|resume|stop <id>. Skip the picker if the user's message was purely informational.

1. The invoking agent (not list.sh - it's a thin wrapper) appends one

eval row via score() with {skill:"snappy-list", verb:"list", score: 1 if list-printed else 0}, supplying its own actor_session_id and a separate auditor_session_id (CONSTITUTION invariant #4 + #3).

Why

state/directive.json was one file → one agent. After Commit 4 the system runs N named agents from state/agents/<id>.json. The byline can show three before it overflows; this skill is the full inventory view.

Also the one place where the user can see which agent corresponds to which byline 🤖 row, and pause/stop individual ones without guessing at paths.

Eval

Shape-gate:

• state/agents/ was scanned (or "no agents running" was reported).
• Every agent row that was present on disk appeared in the output.
• An eval row was appended.

Score = 1 if shape passes else 0.

Gotchas

• Agents are scoped to this machine. An agent started on the Mac Mini

does NOT appear in /snappy-list on the MBP (and vice versa). The Ops view (TUI, press 4) is the cross-machine inventory; this skill is the local one.

• status: stopped agents are deleted immediately; they won't show in

the list. Use state/log/agents.ndjson for history.

• normalizeId() strips any character outside [a-z0-9-]. If a caller

passed Content Miner!, the on-disk id is content-miner.

Rubric

criteria:
  - name: script_execution_success
    kind: deterministic
    check: "The command 'bash ~/projects/snappy-os/state/bin/agents/list.sh' executes without error."
  - name: all_agents_listed_or_none
    kind: judge
    check: "The skill output either explicitly states 'no agents running' or lists every agent found in 'state/agents/*.json'."
  - name: output_format_and_content
    kind: judge
    check: "For each listed agent, the output displays 'id', 'status', 'ticks/max_ticks', 'last_tick_at', and the first 60 characters of 'prompt' accurately."
  - name: eval_row_appended
    kind: deterministic
    check: "An eval row with 'skill:\"snappy-list\"' and 'verb:\"list\"' is appended to 'state/log/evals.ndjson'."

snappy-list - loader

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

Critical Rules

• /snappy-list lists running BACKGROUND AGENTS, not skills. If the user is asking for the skill catalog, route to state/index.md (or find-skills for fuzzy lookup). The agent inventory is state/agents/*.json; the skill catalog is state/skills/*/. (writeback 2026-04-28T22:33:27Z - loader did not match user intent who asked for skills.)
• **Agents are scoped to this machine.** An agent started on the Mac mini does NOT appear in /snappy-list on the MBP and vice versa. The cross-machine inventory is the Ops view (TUI, press 4); this skill is the local view only.
• status: stopped agents are deleted immediately - they will not appear in the list. Use state/log/agents.ndjson for history.
• normalizeId() strips any character outside [a-z0-9-]. Caller passing Content Miner! ends up at on-disk id content-miner. Cite the canonical id in any pause/resume/stop command.
• The invoking agent (NOT list.sh - it's a thin wrapper) appends one eval row via score() with actor_session_id ≠ auditor_session_id (CONSTITUTION invariants #3 + #4).

Commands

| ui dashboard | state/skills/snappy-list/resources/ui.openui | |invoke: bash ~/projects/snappy-os/state/bin/agents/list.sh (prints JSON; one row per agent) |control after listing: npx tsx state/bin/agents/ctl.ts {pause|resume|stop} <id> (id = normalized slug) |history (cross-machine): state/log/agents.ndjson |catalog of SKILLS (different surface): state/index.md or npx skills find <kw> |eval log: state/log/evals.ndjson (skill: "snappy-list", eval_mode: auto-shape; shape gate: list printed OR "no agents running" line)

Self-Test

An agent reading this should correctly:

1. [ ] Distinguish "list agents" (this skill, reads state/agents/) from "list skills" (route to state/index.md)
2. [ ] Treat state/agents/ as machine-local - never claim cross-machine inventory
3. [ ] Use normalizeId()'s canonical slug when piping to ctl.ts pause/resume/stop
4. [ ] Append exactly one eval row per invocation with actor ≠ auditor

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] snappy-list: <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)] snappy-list: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> 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-list/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.