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

title, type, updated

title	type	updated
using-system-snapshot skill design	concept	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).