/skill-usage-report

skill-usage-report

Engine half of the skill-usage telemetry loop (owner spec 2026-07-19: *"show when the skill is last used, and how many times… recommend disable, or user would disable themself"*). Cloud half: AU#93 (`skill_usage` rollup + `POST /api/skills/usage` + last-used in the assignments GET).

Two pieces, both offline-first and fail-open:

1. **`hooks/log-usage.py`** — a `PostToolUse` hook on the `Skill` tool. Appends `{"slug","ts"}` to `<workspace>/state/skill-usage-log.jsonl` on every skill invocation. Never blocks, never fails the invocation. Registered in the core's `settings.json` with `"async": true` — this is a fire-and-forget usage logger, so it must run off the Skill critical path (async keeps interpreter startup + file I/O out of every skill invocation's latency):

Resolve that settings file through the path helper rather than a literal home-relative path — the core config dir is configurable per clone, and on a packaged install it is not under `$HOME` at all:

   SETTINGS="$(bash scripts/sutando-config.sh claude-sutando-config-dir)/settings.json"

   {"PostToolUse": [{"matcher": "Skill", "hooks": [{"type": "command",
     "async": true,
     "command": "python3 '<repo>/skills/skill-usage-report/hooks/log-usage.py'"}]}]}

2. **`scripts/report-usage.py`** — drains the log, aggregates per slug, and POSTs one batched report (`{agentId, events:[{slug,count,lastUsedAt}]}`).

• `agentId` = `$AGENT_MXID` (the ag2space identity — same key the

EquipPanel and assignments API use).

• Bearer from vault key `AG2_CLOUD_TOKEN`.
• Cloud origin is **declared in `manifest.json`'s `config` block** (the

config-only manifest convention — see `skills/MANIFEST.md`), not invented as an env-only setting. Resolution order is `$AG2_CLOUD_ORIGIN override > manifest default > CLOUD_FALLBACK`. The shipped manifest declares the key empty, so the default is this install's DotSpace cloud (`dotspace.default_cloud_origin()`), never a fixed server; set a value there only to pin one.

• Rename-before-POST so events arriving mid-report are never lost;

fold-back on failure so nothing is dropped. Always exits 0.

Run on a gated sub-daily cron (crons.json):

The cron needs `AGENT_MXID` in the environment. Read it from the channel env under the **resolved** core config dir — never a home-relative literal, which is wrong on any clone that configures the config dir elsewhere:

   {"name": "skill-usage-report", "cron": "*/30 * * * *",
    "prompt": "Run: bash scripts/cron-gate.sh skill-usage-report env $(grep AGENT_MXID \"$(bash scripts/sutando-config.sh claude-sutando-config-dir)/channels/ag2space/.env\" 2>/dev/null) python3 skills/skill-usage-report/scripts/report-usage.py — drains the local skill-usage log to AU (AU#93). Deferred when owner tasks are queued."}

Expected behavior before equips exist

The cloud endpoint only accepts usage for skills **currently equipped** to this agent (`skill_assignments` row for (user, agent, skill)) — everything else counts as `skipped` in the response. Until the owner equips skills to this agent's mxid, reports will be all-skipped; the local log still drains. This is by design (unequipped usage is meaningless for the prune-unused feature and would accumulate junk rows).

Iteration log

• v0.1.0 — 2026-07-19 — initial ship alongside AU#93. Slug is taken from the

Skill tool's input (`skill` param), bare-name-normalized (strips `plugin:`/path-scope prefixes). Local log is the offline-first buffer; the reporter is idempotent-safe to re-run (server folds counts additively and uses GREATEST on timestamps, so a duplicated batch inflates counts but can never move last-used backwards; the rename-claim makes duplicates unlikely).

• v0.1.1 — 2026-07-19 — review fixes (PR #2180 blocking findings): (1)

pending-only recovery — a crash between the rename-claim and fold-back left `.reporting` with no active log; the next run then crashed on `log.open`. Recovery now renames pending back when the active log is absent. (2) >100 distinct slugs were silently dropped (aggregate sliced to MAX_EVENTS but the claimed file was deleted whole). Reports now send in chunks of 100; on mid-run failure the unsent remainder is folded back into the active log as count-carrying records (`{"slug","ts","count"}` — the aggregator honors `count`), so nothing is ever lost.