用途
Token Coach 是一个围绕用户 token 消耗去向展开的教练式对话技能，所有结论都基于在用户本机实测得到的数字。它的交付物是一份简短、按优先级排序、且用户认可的行动计划。如果用户需要一份会直接修改其配置的完整审计，则应转交给 token-optimizer。
Token Optimizer 自身的技能（token-optimizer、token-coach、token-dashboard、fleet-auditor、resume-checkpoint）属于测量层，因此无论它们运行频率多低，都不应出现在任何“未使用技能”“归档”或“合并”建议中。
主要能力
1. 收集数据
首先运行指定的脚本，用于定位最新安装的副本，避免过期的插件缓存给出错误答案。脚本会判断运行时（claude、opencode 或 codex），并在多个安装路径中查找最新版本的 measure.py。
随后按需收集以下数据，失败的命令可跳过（旧版本可能缺少部分命令）：
python3 "$MEASURE_PY" coach --json：快照、模式、历史、问题python3 "$MEASURE_PY" quality current --json：当前会话的质量评分与问题python3 "$MEASURE_PY" subagent-cache status --json：Claude Code 的子代理缓存生命周期及其收益python3 "$MEASURE_PY" compact-advice --json：Claude Code 更早的压缩窗口是否划算python3 "$MEASURE_PY" recommendations --json：Claude Code 每日用量建议记录- 当运行时为 codex 时：
python3 "$MEASURE_PY" codex-doctor --project "$PWD" --json
coach JSON 包含：snapshot（当前开销）、patterns_good 与 patterns_bad（带详情和修复建议的命名模式）、history（7 天对比更早时期：质量、会话长度、缓存命中率、评分分布、每会话成本、短会话对比长会话、压缩差距、切换模型的会话占比）、deterministic_candidates（用户重复执行、可由脚本完成的工作），以及 Claude Code 上的 usage_recommendations（每日实测记录：压缩窗口和子代理缓存生命周期各一项，以及用户采纳早前建议后数字变化带来的 wins）。字段含义与可引用的数字见 references/quick-reference.md。
所引用的每个数字都必须来自这些输出或快速参考。当数据不足或命令无返回时，应如实说明，并基于用户提供的信息进行教练；编造数字会损害用户对所有真实数字的信任。
2. 询问用户目标
先问一个问题并等待回答，再展示发现：
今天的目标是什么？ a) 构建新东西，希望从一开始就 token 高效 b) 现有配置感觉慢，或上下文填满太快 c) 设计多智能体系统 d) 快速健康检查 e) 审查工作流或自动化：哪些步骤真正需要模型
如果请求本身已能回答该问题，则跳过提问。
3. 加载目标所需内容
- 目标 a、b：读取 references/coach-patterns.md、快速参考；示例 examples/coaching-session-new-project.md（a）、examples/coaching-session-heavy-setup.md（b）
- 目标 c：读取 references/agentic-systems.md、快速参考；示例 examples/coaching-session-agentic.md
- 目标 d：仅快速参考，保持快速
- 目标 e：读取 references/deterministic-stages.md
对于 a、b、c，还需读取 references/coaching-scripts.md 了解对话通常如何展开。所有路径均位于 $COACH_DIR 下。示例展示语气和节奏，内容由用户数据决定。
4. 教练过程
这是一场对话。先给一两个发现，然后提问，由用户引导后续。
优先指出最痛的问题。会话质量评分低于 70 时优先处理（例如“质量是 100 分中的 58 分，过期的工具结果占用了 40K token”）。否则，恶化的趋势比静态数字更重要：质量下降、会话长度增长、缓存命中率下降。
使用用户的数字并点出模式名称。例如“47 个技能每次启动约消耗 4,700 token，这就是 50-Skill Trap”，比“技能消耗 token”更有说服力。
用一句话解释机制，使建议能适用于本技能未列出的情况。例如：会话中途切换模型会丢弃提示缓存，因此应在开始时选定模型；子代理内使用更便宜的模型没问题，因为它有自己的上下文。
子代理缓存：即使订阅用户，子代理也只有 5 分钟缓存。Token Optimizer 会测量 1 小时缓存对该用户转录是否划算并给出建议（它不会替用户设置密钥）；报告 subagent-cache status 的测量结果及其 advice 行，包括收益为负的情况。同一结论也存在于每日 usage_recommendations 记录中，供仪表盘的“From your own usage”部分读取。
压缩窗口：将 compact-advice 呈现为基于其自身历史的估算，成本与质量并列，并给出它打印的命令。更早压缩可在后续每一轮节省缓存读取 token，但有丢失早期指令的风险，由用户决定。每日 usage_recommendations 记录也包含提炼后的 recommend/keep 结论。
用量建议：当 usage_recommendations 带有 recommend 项时，优先展示它——这是今日实测答案，且已通过足够数据的门槛。当 wins 非空时，指出“自你更改后”的实测变化并引用两个数字；切勿声称是该更改导致。
目标 e，或任何 deterministic_candidates 非空时：逐步梳理工作流，按 deterministic-stages 参考将每一步归为“输入决定输出，用普通代码”或“需要判断，用模型”。
Codex 用户只听到 Codex 术语：AGENTS.md、Codex memories、平衡的 Codex hooks、推理强度和模型选择器、压缩提示指导。Claude 模型名和 CLAUDE.md 对他们没有意义。
语气像一位懂行的朋友。通常两到四轮交流；跟随用户的问题而非脚本。
5. 商定行动计划
以三到五个按影响排序的行动收尾。每个行动包含加粗名称、一行说明做什么、预估节省及其估算来源，以及是快速见效还是较深层的改动。适用时包括：
- Claude Code 上质量低于 70：
python3 "$MEASURE_PY" setup-smart-compact。Codex 上：TOKEN_OPTIMIZER_RUNTIME=codex python3 "$MEASURE_PY" codex-install --project . - 质量低于 50：在继续工作前执行 /compact 或 /clear。
- 从模型迁移到脚本的步骤，每步附机制（hook、脚本、定时任务）。
然后对照数据检查计划：每个数字都可追溯到命令输出或快速参考，且没有任何行动触及 Token Optimizer 自身的技能。发送前修复不合格处并再次检查。
当用户希望代为执行更改时，提供 /token-optimizer；当用户希望观察趋势时，提供仪表盘（python3 "$MEASURE_PY" dashboard；在 Codex 上引用它打印的 Dashboard: 行，切勿使用记忆中的路径）。
Keep-Warm（Claude Code，仅询问一次）
在计划之后，运行 python3 "$MEASURE_PY" keepwarm-consent-status。仅当 should_ask 为 true 时，严格遵循 references/keepwarm-consent.md：它会花费用户的钱，因此措辞和命令顺序是固定的。
适用场景
- 规划新项目，希望从一开始就 token 高效
- 现有配置缓慢或上下文填满过快
- 设计多智能体系统
- 快速健康检查
- 审查工作流或自动化，判断哪些步骤真正需要模型
限制
- 所有数字必须来自实测输出或快速参考，数据不足时需如实说明
- 不会替用户设置子代理缓存密钥
- 压缩窗口由用户自行决定
- 不会声称某项更改导致了 wins 中的变化
- 不涉及 Token Optimizer 自身技能的归档或合并建议
- 该技能针对 Claude Opus 5.5、Sonnet 5.5 以及 Codex 上的 GPT-5.6 编写和验证