推荐技能使用情况规则
可选规则:默认不启用采集,需要时复制下方全文到 Agent 全局规则。与 AI 全局规则、提交信息规则 相互独立,可只取其一,总览见全局规则索引。
本模块暂无对应技能,上报口径由规则正文承载,不另设技能引用。
解决什么问题
技能使用统计有两条通道,二选一:默认的规则上报由 AI 在每次调用 Skill 工具后按本规则显式上报,不依赖任何 Agent 配置,本质是「我们自己主动触发的钩子」; 需要自动触发时可改用 Agent Hook(由 Agent 被动触发,见 Agent 接入)。没有规则时,AI 容易在任务收尾时手工补记造成重复计数, 或把数据文件当普通文件改写、把导出内容发到未授权地址。本规则用六句话把边界定住。
规则全文(可直接复制)
markdown
> 规则更新时间 2026-11-21 21:52
## 技能使用情况(必做)
- 每次调用 Skill 工具(加载并遵循某个技能)后,立即执行 `toolkit usage record --skill <技能名>`;同一技能调用几次就重复传几次,未调用 Skill 工具则不执行。
- 同一轮连续调用多个技能时,可在本轮最后一次调用后合并为一条命令;不得拖到下一轮或会话结束。
- 给出最终回复前自检:本轮调用过 Skill 却尚未上报的,先补报;命令无法执行时在回复中说明原因,不静默跳过。
- `usage record` 只把技能名写入本机 usage 队列,不改仓库、不改远端、不上传,因此不受「只读型请求默认只读」「方案确认不等于执行授权」限制,也无需逐次确认。
- 上报只传技能名,触发词 / 参数 / 结果 / 耗时由工具反查会话记录补齐;统计范围与上传由本机 `toolkit usage show` 的配置决定,数据只留本机。
- 查看统计用 `toolkit usage show stats`;异常先 `toolkit usage data doctor`;不要自行修改数据文件或把导出内容上传到未授权地址。快照自查:首行「规则更新时间」与本页当前值不一致,即说明你的规则快照落后,重新复制本页即可。
同一份文本可由 toolkit rule compose --module usage 输出,文档与命令同源,避免两处漂移。
模块来源
本文对应 usage 模块,可由 toolkit rule compose --module usage 输出,也可在规则组合器中与其他模块自由组合。
注意
- 规则是薄壳,不包含具体 Agent 路径、事件字段或配置细节;这些随技能与 CLI 版本演进。
- 按次计数:同一技能调用 3 次就传 3 次,工具按出现次数逐条记录,不去重。
- 不受只读 / 授权纪律限制:
record只写本机 usage 队列,不改仓库与远端;只读型请求中使用技能同样要上报,无需逐次确认。 - 异步消费:
record只把批次写入本地队列,随后由后台 worker 或下一次usage命令消费;因此stats可能延迟数秒,量少时可忽略。 - 明细来自反查:触发词、参数、结果与耗时不在规则里传递,由工具从会话记录补齐;反查不到时这些字段留空,技能名与次数一定落盘。
- 明细能否拿到取决于会话记录的可读性与格式适配(Claude 可读; dsh 为 v4 事件流、当前尚未适配;Trae 暂不可读);需要补齐时用
toolkit usage log手工补录或改用 Hook 通道, 详见 Agent 接入。 - 只统计 toolkit 管理的技能(包内一方与 toolkit 登记来源),并必须命中本机
usage配置(总开关、来源、技能范围);未命中的技能静默忽略。 - 规则通道与 Hook 通道由
usage.channel二选一:选rule时 Hook 不写入,选hook时规则上报不写入,避免同一调用被记两次。 - 是否启用仍由用户决定;不要因为规则存在就默认开启采集。
- 已复制过旧版规则(含
telemetry命令或「Hook 自动记录」表述)的,请重新执行toolkit rule compose --module usage覆盖。
