claude-skills/.wiki/concepts/using-system-snapshot-design.md

---
title: using-system-snapshot skill design
type: concept
updated: 2026-06-09
---

# using-system-snapshot skill design

New policy+technique skill (v0.1.0) wrapping the single MCP call
`mcp__projects-meta__meta_system_snapshot`. Replaces the old scatter of
`tasklist` + `docker ps` + a manual `meta_status` read with one round-trip for
session-start ops orientation.

## Why a skill

The failure mode it guards: an agent asserts "the poller is running" / "all
containers are up" / "you have N active tasks" from memory or a stale earlier
snapshot, without re-checking. The skill makes the rule explicit — **no claim
about poller / local-docker / task-load state without calling the tool in the
current turn**. Mirrors the read-only, no-grant posture of [[using-vds-ops]].

## Tool output shape (verified live 2026-06-09)

Three keys:

- `poller`: `{ running: bool, projects: "<owner/repo …>" }` — **live**.
- `docker`: `[{ name, status }]` — **local** machine containers (includes
  `agents-task-runner-*`), NOT the VDS. Status strings like `Up 4 hours`,
  `Up 26 hours (healthy)`; problems show as `Restarting` / `Exited` /
  `(unhealthy)` / `Created` / `Paused`. **live**.
- `tasks`: `{ "<owner>/<repo>": { active, blocked } }` — **from the
  projects-meta cache**, so approximate.

## Design decisions

- **Output = three lines, one per section** (per task spec). Docker line reports
  `N/N up` when all healthy, else lists only the bad containers; tasks line gives
  Σ active / Σ blocked + the busiest 2–3 projects. Never dump raw JSON.
- **Liveness split made explicit.** Poller + docker are read at call time; task
  counts come from the cache. The skill tells the agent to flag task-count
  staleness and defer precise per-task work to [[projects-meta-skills]]
  (`using-projects-meta` Step 0 freshness gate, or local `.tasks/` on disk).
- **Scope boundaries.** Deep single-container diagnosis (logs/inspect/stats) is
  explicitly out — that's [[using-vds-ops]] for the VDS or `docker logs`
  locally. The snapshot only carries name + status.
- **Read-only, no per-session grant** — same as [[using-vds-ops]]. The tool
  takes no args; no preview/confirm dance (unlike the projects-meta mutations).

## Prerequisites

Needs `mcp__projects-meta__meta_system_snapshot` (shipped by `projects-meta-mcp`;
the `meta-system-snapshot` capability lives in `OpeItcLoc03/common`). If the tool
is absent, the server isn't registered → `setup-projects-meta`.

## TDD note

Markdown policy artifact — no code/test surface (consistent with sibling skill
tasks). Behavioral trigger smoke-test is the paired `skill-using-system-snapshot-review`
task, not this implementation task.

## Review outcome (2026-06-09, `skill-using-system-snapshot-review`)

**Verdict: PASS** on all three acceptance criteria. Reviewer was a non-implementer
session.

- **Tool contract verified live** — a real `meta_system_snapshot` call returned
  exactly the documented shape (`poller {running, projects}`, `docker [{name,
  status}]` incl. `agents-task-runner-*` with `Up … (healthy)` strings, `tasks
  {owner/repo: {active, blocked}}`). The "The call" table and this page are accurate.
- **Trigger phrases cover real scenarios** ✅ — 9 fresh-context subagents, each
  given a simulated skill registry (real descriptions + `using-vds-ops` /
  `using-projects-meta` / `using-tasks` competitors) and one trigger phrase, no
  hint of the expected answer. 4/4 positives → `using-system-snapshot`; VDS-logs →
  `using-vds-ops`; mutate/full-board → `using-projects-meta`; `docker-compose.yml`
  edit → `none` (no false-positive on the "docker" keyword).
- **No-claim-without-snapshot rule explicit** ✅ — stated in 4 places (Overview
  core rule, "When to use", "What NOT to do", Common-mistakes table).
- **Output format brief** ✅ — three-line block, per-line rules, "no raw JSON";
  confirmed achievable against the live payload.

**Informational findings (none blocking):**

1. **Task-count overlap with `using-projects-meta`.** «сколько активных задач по
   всем проектам» routed to `using-projects-meta`, not the snapshot. By-design —
   the skill defers *precise* per-task work and the `tasks` line is a bonus of the
   combined ops view, not its headline — so no fix. Quick «сводка по задачам …»
   glances still route here correctly.
2. **Local-container deep diagnosis is unowned.** «локальный контейнер … почему
   рестартует» routed to `using-vds-ops` (its incident-phrase triggers grabbed a
   *local* container, which its VDS-only tools can't reach). Not this skill's
   defect — the snapshot correctly does not claim deep "why". Candidate
   `using-vds-ops` scoping follow-up if it recurs.
3. **Deployment scaffold missing.** The skill is committed (`skills/…`, v0.1.0)
   but is **not** installed to `~/.claude/skills/`, **not** in
   `hermes/mapping.yaml`, and has no `-install` / `-hermes-mapping` /
   `-test-trigger` baseline tasks (unlike `meta-host-routing` / `delegate-task`).
   Recommended follow-ups before it reaches live sessions; hermes mode could be
   `auto` since the skill is read-only (owner's call).