jiantw83
aeb3f467e2
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
45 lines
3.6 KiB
Markdown
45 lines
3.6 KiB
Markdown
---
|
|
name: stats
|
|
description: Report usage counts of every jsc skill and every skill call chain, aggregated by tools/usage-stats.sh from $JSC_HOME/usage/*.jsonl recorded by jsc-hooks. Supports --cli filtering. Use when the user asks how often skills or chains are used; not for token or time stats (see worklog).
|
|
---
|
|
|
|
# stats — skill and call-chain usage counts
|
|
|
|
Data is recorded continuously by `jsc-hooks/hooks/skill-usage.sh` under `$JSC_HOME/usage/` (default `~/.jsc/usage/`).
|
|
|
|
## Operations
|
|
|
|
| Count | Command | Output |
|
|
| --- | --- | --- |
|
|
| Uses per skill | `tools/usage-stats.sh skills` | `count<TAB>skill`, descending |
|
|
| Uses per call chain | `tools/usage-stats.sh chains` | `count<TAB>from -> to`, descending |
|
|
| Filter by CLI | Append `--cli claude` (or codex / copilot / antigravity / kiro) | Same as above |
|
|
|
|
## Reporting
|
|
|
|
1. Run the tool directly and branch on its exit code — never read the printed lines without it.
|
|
|
|
| Exit | Do |
|
|
| --- | --- |
|
|
| 0 | Present every printed line as one table row. No line printed is still exit 0: the data file under `$JSC_HOME/usage/` does not exist yet, which is a count of zero, not a failure — say the counts are zero and that `jsc-hooks` has to be installed and wired via `jsc-hooks:hooks-install` before anything is recorded, and show no table |
|
|
| 2 | The subcommand or the `--cli` argument was rejected — the subcommand is neither `skills` nor `chains`, or `--cli` came with no value. Fix the argument and rerun. Never rerun the same command unchanged, and never report the counts as zero: nothing was read |
|
|
|
|
Done when the exit code was read and the branch it names was taken.
|
|
2. Record how the run ended, as the very last thing this skill does:
|
|
|
|
`jsc-hooks/tools/report-status.sh skill-end jsc-log:stats {status} {exit} "{detail}"`
|
|
|
|
Resolve that path the way this file already names `jsc-hooks/hooks/skill-usage.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands.** The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. This skill only reads counts; it must never fail because a count of its own could not be written.
|
|
|
|
| status | This skill's case |
|
|
| --- | --- |
|
|
| `ok` | The tool exited 0 and every printed line reached the report. A run that printed no line is `ok` as well — the count really is zero, so say `count=0` in `{detail}` rather than dressing an empty data file up as a problem |
|
|
| `blocked` | `tools/usage-stats.sh` is not on this machine, which is a partial plugin install rather than a zero count. No number was ever read, so none is reported |
|
|
| `degraded` | The caller asked for both counts and only one sub-command answered, so the report covers half of what was asked. Name the half that is missing in `{detail}` |
|
|
| `failed` | Exit 2 — the sub-command or the `--cli` value was rejected, so nothing was read. This is the one case that must never be reported as a count of zero, and recording it as `failed` is what keeps the two apart in the event stream too |
|
|
| `aborted` | The user stopped the run, or the request turned out to be about elapsed time or token usage, which belong to `jsc-log:worklog`; this skill then stops before it counts anything |
|
|
|
|
`{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: the sub-command plus counts and exit codes, never branch names or personal data.
|
|
|
|
Done when the command has run, or the script was absent and this step was skipped.
|