feat(using-system-snapshot): new skill v0.1.0
Thin read-only skill wrapping the single meta_system_snapshot MCP call (poller status + local docker + cached cross-project task summary). Replaces the scatter of tasklist / docker ps / manual meta_status. Core rule: no claim about poller / local-docker / task-load state without calling the tool in the current turn. Output = three lines, one per section (docker lists only problem containers; tasks gives Sigma active/blocked + busiest 2-3 projects). Liveness split documented (poller+docker live, tasks from cache). Scope boundaries: deep single- container diagnosis -> using-vds-ops / docker logs; precise per-task work -> using-projects-meta. Read-only, no per-session grant. Output shape verified by a live snapshot call 2026-06-09. Wiki: concepts/using-system-snapshot-design.md + index + log. TDD N/A (markdown policy artifact); behavioral smoke-test = paired skill-using-system-snapshot-review task. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
77
skills/using-system-snapshot/SKILL.md
Normal file
77
skills/using-system-snapshot/SKILL.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: using-system-snapshot
|
||||
version: 0.1.0
|
||||
description: "Use at the start of an ops-context session, and ALWAYS before asserting anything about the agent poller, local docker containers, or cross-project task load — call `mcp__projects-meta__meta_system_snapshot` instead of running `tasklist` / `docker ps` / `meta_status` by hand. Triggers on «что запущено», «что сейчас крутится», «состояние системы», «состояние машины», «поллер работает?», «поллер живой?», «что с докером», «сводка по задачам», «what's running», «system status», «system snapshot», «is the poller up», «is the runner alive», «what containers are up». Read-only — no per-session grant needed. Skip for deep single-container docker diagnosis (that's using-vds-ops for the VDS / docker logs locally) and for mutating or precise per-task work (that's using-projects-meta)."
|
||||
---
|
||||
|
||||
# using-system-snapshot
|
||||
|
||||
## Overview
|
||||
|
||||
One call — `mcp__projects-meta__meta_system_snapshot` — returns a whole-machine ops snapshot: agent **poller** status, local **docker** containers, and a cross-project **task** summary (active / blocked counts) from the projects-meta cache. It replaces the old scatter of `tasklist`, `docker ps`, and a manual `meta_status` read with a single round-trip.
|
||||
|
||||
**Core rule: never assert the state of the poller, local containers, or task load without calling this tool first.** Memory and "it was running earlier" are not evidence.
|
||||
|
||||
## When to use
|
||||
|
||||
- Session start in an **ops context** — orienting before doing infra / runner / task-board work.
|
||||
- The user asks what's alive: «что запущено», «состояние системы», «поллер работает?», «что с докером», «what's running», «is the poller up».
|
||||
- **Before any claim** about whether the poller is running, which projects it scans, whether a container is up/healthy, or how many tasks are active/blocked.
|
||||
- A quick cross-project task-load glance ("where's the work concentrated right now").
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- Deep diagnosis of **one** container (logs, inspect, stats, restart-loops) — that's `using-vds-ops` for the Rusonyx VDS, or `docker logs` locally. The snapshot only gives name + status.
|
||||
- **Mutating** task state, or reading the **full** board / a precise per-task body — that's `using-projects-meta` (and local `.tasks/` disk for the current project).
|
||||
- Library docs, code search, single-file questions — unrelated.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Requires the tool `mcp__projects-meta__meta_system_snapshot` (shipped by the `projects-meta-mcp` server; the `meta-system-snapshot` capability lives in `OpeItcLoc03/common`). If the tool is missing from the session, the server isn't registered — trigger **`setup-projects-meta`** to install and register it, then retry.
|
||||
|
||||
## The call
|
||||
|
||||
`mcp__projects-meta__meta_system_snapshot` takes **no arguments**. Read-only — call it directly, no preview / confirm, no per-session grant.
|
||||
|
||||
It returns three keys:
|
||||
|
||||
| Key | Shape | Liveness |
|
||||
|---|---|---|
|
||||
| `poller` | `{ running: bool, projects: "<owner/repo …>" }` | **live** at call time |
|
||||
| `docker` | `[{ name, status }]` — local containers | **live** at call time |
|
||||
| `tasks` | `{ "<owner>/<repo>": { active, blocked }, … }` | **from the projects-meta cache** — may be stale |
|
||||
|
||||
`docker` is the **local** machine's containers (includes `agents-task-runner-*`), NOT the VDS. `tasks` counts mirror the cache, so treat them as approximate; for accurate task state run the `using-projects-meta` Step 0 freshness gate or read local `.tasks/` on disk.
|
||||
|
||||
## Output format — one line per section
|
||||
|
||||
Compress the JSON into **three lines**. Don't dump the raw object.
|
||||
|
||||
```
|
||||
🟢 Poller running — OpeItcLoc03/claude-skills (🔴 if running:false)
|
||||
🟢 Docker — 8/8 up (else list only the bad ones)
|
||||
📋 Tasks — 23 active / 41 blocked, 17 projects (name the busiest 2–3)
|
||||
```
|
||||
|
||||
Rules per line:
|
||||
|
||||
- **Poller** — 🟢/🔴 + running flag + the `projects` string. If stopped, say so plainly — that's the headline.
|
||||
- **Docker** — if every status starts with `Up` (incl. `Up … (healthy)`), report `N/N up`. Otherwise list **only** the problem containers by name + status (`Restarting`, `Exited`, `(unhealthy)`, `Created`, `Paused`). Don't enumerate healthy ones.
|
||||
- **Tasks** — totals (Σ active / Σ blocked across all projects) + the 2–3 projects with the most active work. Full per-project breakdown only if asked.
|
||||
|
||||
## What NOT to do
|
||||
|
||||
- **Do NOT** state "the poller is running" / "all containers are up" / "you have N active tasks" from memory or a prior snapshot. Call the tool in the current turn first. A snapshot from earlier in the session is already stale for liveness claims.
|
||||
- **Do NOT** fall back to `tasklist` / `docker ps` / a manual `meta_status` to answer these questions — that's the scatter this skill exists to replace. (Drop to raw `docker logs` only for the deep single-container diagnosis this skill explicitly defers.)
|
||||
- **Do NOT** paste the raw JSON. Three lines, one per section.
|
||||
- **Do NOT** present `tasks` counts as exact — they come from the cache. Flag staleness if precision matters, and point at `using-projects-meta`.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| "Poller's still up" without calling the tool this turn | Call `meta_system_snapshot` first — liveness claims need current evidence. |
|
||||
| Running `docker ps` / `tasklist` instead | Use the single snapshot call; that's the point. |
|
||||
| Reading the snapshot's `docker` as the VDS fleet | It's the **local** machine. VDS containers → `using-vds-ops`. |
|
||||
| Treating `tasks` counts as authoritative | They're cached. For exact state use `using-projects-meta` Step 0 or local `.tasks/`. |
|
||||
| Dumping the raw JSON object | Collapse to three lines (poller / docker / tasks). |
|
||||
Reference in New Issue
Block a user