usage-engineer Skill
在不降低质量的前提下,减少编码 Agent 会话中浪费的 token。当命令输出很长的日志或测试结果、同一命令反复失败、从旧的项目地图或交接文档恢复工作、AGENTS.md 等指令文件可能重复,或用户问 Codex、Claude Code、OpenCode 的用量去哪了、为什么触发限流、怎么让 Agent 更省钱时使用。本地运行内置的零依赖 Python CLI;不联网、绝不读取凭据。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
usage-engineer
Every token an agent spends on a 5,000-line log, a retried command or a stale map is paid for again
on every later turn. This skill removes that waste. It never lowers the bar: requirements, tests and
verification stay exactly as strict as without it.
The CLI
All commands run the bundled script, which has no dependencies and makes no network calls:
python <skill-dir>/scripts/ue.py <command>
is the folder this SKILL.md is in. If ue is on PATH (installed with pipx), ue
is the same thing. Use python3 where python is not Python 3, and py -3 on Windows if neither is
found. If no Python is reachable (the Codex sandbox on Windows can hide a per-user install), say so
once and still follow the rules below by hand; do not retry the same command.
Rules
- Long output goes to a file, not the conversation. When a build, test run or log will print more
than about 100 lines, redirect it to a file and summarize it:
<command> > build.log 2>&1
python <skill-dir>/scripts/ue.py summarize-log --file build.log
The summary keeps every error and failure line with context plus the last 20 lines, and prints the
path of a byte-exact copy of the full log. Read slices of that copy only when the summary is not
enough. Never rerun a command just to see its output again.
- Two identical failures means change approach. If the same command fails twice with the same
input, do not run it a third time. Read the error, change the input, or try a different method.
- Check a map before trusting it. Before resuming from an older session, handoff or project map,
check whether the files changed:
python <skill-dir>/scripts/ue.py map check --project . --map <map.json>
Exit code 1 means STALE and lists the changed files: re-read those, and only those. Build a map
at the end of a work session so the next one can check it:
python <skill-dir>/scripts/ue.py map build --project .
- Read narrowly. Search first (
rg,grep) and read the matching range instead of whole files.
Do not re-read a file that has not changed.
- Report what actually ran. Never describe a check as passing unless it ran in this session.
Keep the path to the full failure output in the report so nothing is lost by summarizing.
Measuring usage
When the user asks where their usage went, why they hit a limit, or whether a change helped, measure
before advising:
python <skill-dir>/scripts/ue.py audit --days 7
It reads local Codex CLI rollout files ($CODEX_HOME/sessions), Claude Code transcripts
(~/.claude/projects) and the OpenCode database, read-only,
with home paths redacted. It reports input, cached, output and reasoning tokens, incomplete turns,
and two waste signals: oversized tool outputs (with an estimate of the tokens they cost) and
repeated identical tool calls. It never reads auth.json, cookies, tokens or
chat text. Report its numbers as measured; label anything else as an estimate.
Other commands
| Command | Use it when |
|---|---|
| prepare-context --project . --task "" --verify "" | starting a non-trivial task: writes a small pack with the request, constraints, git state and the checks to run. It narrows the start, not correctness: widen whenever evidence requires it. |
| instructions duplicates --project . | AGENTS.md, CLAUDE.md or similar files may repeat the same paragraphs, which are then paid for on every turn. |
| doctor | something does not work: prints versions, paths and the state folder. |
Printed paths start with %HOME%, which stands for the user's home directory (redaction keeps it
out of logs and reports); expand it before opening the file.
Nothing above changes the model, reasoning effort or agent settings. Output files go to
~/.usage-engineer (override with UE_STATE_DIR) unless --out is given.
Honest limits
Saving claims are cheap. In the project's own first A/B run, handing the agent a prepared context pack
used about 30% more tokens on small tasks, so do not promise savings from prepare-context. The rules
above that avoid re-sending output (1, 2 and 4) are the reliable wins. Full benchmark harness and
results: https://github.com/noamshorts22-prog/usage-engineer