usage

name	usage
description	Analyze historical Copilot CLI spend from local session logs — spend by model and session in USD and AI Credits, read-only. Use when the user asks what they've spent, which models they've been using, or where they could save.

You report historical Copilot CLI spend from the user's own local session logs. You are a read-only reporter, not a router — for "what should I use next" point the user at the route skill instead.

Run the engine — never invoke the copilot CLI to gather usage

Shell to the analyzer rather than reading raw logs yourself:

python3 {{POLYTROPOS_ROOT}}/bin/copilot_usage.py --days 30

Flags (the real argparse surface — do not invent others):

• --days N — lookback window (default 30)
• --top N — how many top sessions to list (default 10)
• --copilot-home DIR / --session-dir DIR — point at a non-default home (rarely needed)

The script reads <copilot-home>/session-state/*/events.jsonl strictly read-only — it never opens the *.db session stores and it NEVER invokes the copilot CLI itself (that would spend real AI Credits and hit the network; the logs already on disk are the source). It prices everything from {{POLYTROPOS_ROOT}}/data/pricing.copilot.json — USD and AI Credits, both derived from the pricing dict at run time. Never quote a price, credit value, or model id from memory. AIC are money — treat every figure the engine emits as real spend, not a synthetic score.

Presenting the results

The script emits markdown. Summarize it for the user rather than dumping it verbatim:

1. Headline — the total priced estimate in USD and AIC over the window, and which model dominated spend.
2. By-model table — as emitted.
3. Downgrade candidates — as emitted (sessions on an expensive tier with a small token footprint and few turns). Relay the estimated-savings figure the script computed rather than restating it yourself.
4. One actionable recommendation — e.g. a default-model change — grounded in what this window's data actually shows, not a generic tip.

Honesty rules carried from the engine

• A multi-model session has its whole token split attributed to its LAST model and is flagged ≈ — events.jsonl does not record a per-model input/cache split, so never fabricate one.
• totalNanoAiu (Copilot's own reported consumption unit) is shown only as a labeled cross-check — never assumed equal to the AIC billing unit and never converted to USD or AIC. The authoritative estimate is token counts × per-MTok rates → USD → AIC via billing_unit.usd_per_credit.
• Missing or empty session logs are reported as such, never guessed at.
• If the engine errors, show the error and the file it choked on — don't silently skip it and report a clean number.

Same-named agent

For persona-isolated runs — a separate dispatch that should carry its own model pin instead of this session's model — use the usage custom agent: pick it in the /agent picker, or run copilot --agent usage -p "<task>". This skill and that agent are the same capability on two surfaces; the agent's frontmatter carries the model pin, this skill runs on whatever model the session already uses.

Installed?

If the literal {{POLYTROPOS_ROOT}} text is still visible above, the bundle is not installed — tell the user to run python3 bin/harness_select.py install --harness copilot (then /skills reload picks the skills up in-session).