snappy-list

One job: answer "what background agents do I have running right now, on this machine?" This skill is the full runtime agent inventory.

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, verify-loop)
• 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. This skill is the full inventory view.

Also the one place where the user can pause/stop individual agents 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 Verify Loop!, the on-disk id is verify-loop.

Rubric

criteria:
  - name: agent_count_nonzero_or_none
    kind: deterministic
    check: "Either state/agents/*.json has ≥ 1 agent (at least one file exists) OR script reports 'no agents running'. Not silently empty."
  - name: all_agents_in_output
    kind: deterministic
    check: "Every agent file on disk appears in output as a row. If 3 agents exist in state/agents/, all 3 are listed (not truncated)."
  - name: agent_metadata_accurate
    kind: deterministic
    check: "Per-agent row shows id, status (running|paused|stopped|done), ticks/max_ticks, last_tick_at, first 60 chars of prompt. Values match on-disk JSON."
  - name: eval_row_written
    kind: deterministic
    check: "state/log/evals.ndjson receives row with skill='snappy-list', verb='list', score=1 if all agents listed, score=0 if empty/incomplete."

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 Verify Loop! ends up at on-disk id verify-loop. 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 model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact | |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

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