Usage Engineer

Usage engineer targets avoidable token and context waste from long logs, repeated command failures, stale project maps, and duplicated instructions. It pairs workflow rules with a bundled zero-dependency Python CLI, scripts/ue.py. Requirements, testing, and verification remain as strict as they would be without the skill; reducing output does not justify weakening checks.

Its local helpers summarize logs, build and validate project maps, audit supported usage records, and identify repeated paragraphs in instruction files. Optional benchmark runners can launch assistants that contact providers, so those runners are distinct from the local audit helpers.

Use the workflow before a build, test, or log operation likely to produce more than about 100 lines; after two identical failures with the same input; or when resuming from an old handoff or map. It also applies when instruction files may duplicate text and when the user wants measured information about local usage or rate-limit-related activity.

The usage audit reads local CLI rollout data and the OpenCode database, rather than every possible assistant's usage. Oversized-output token costs are approximations, not billing figures. The skill does not replace environment-specific validation or expert review, and it does not promise that prepared context always saves tokens: a first small-task comparison found that the prepared pack used about 30 percent more.

For long commands, redirect output to a file and summarize that file. For example, capture and summarize a test run as follows:

pytest > test.log 2>&1
python <skill-dir>/scripts/ue.py summarize-log --file test.log

The summary retains every error and failure line with surrounding context and the last 20 lines, while reporting the path to a byte-exact full copy. Open relevant slices only when the summary is insufficient. Do not rerun a command merely to see its output again, and keep the full-log path in reports.

After the same command fails twice with unchanged input, change the input, inspect the error, or use another method. For source inspection, search before reading and avoid rereading unchanged files. Before trusting a project map, run map check: exit code 1 indicates stale data or incomplete coverage. Inspect listed changes and expand inspection if truncation or other evidence requires it. Build a new map at session end for the next handoff.

The audit command reads supported local records and reports input, cached, output, and reasoning tokens; incomplete turns; oversized outputs with estimated costs; and repeated identical calls. Present measured values as measured and other figures as estimates. Duplicate-instruction inspection identifies paragraphs repeated across instruction files.

The CLI requires Python 3.9 or newer and only the standard library. Use python3 or the documented Windows alternative where needed. If Python is unavailable, explain once and apply the workflow manually instead of repeating the failed invocation. Bundled behavior can be checked through map build and map check. The selftest command needs upstream fixtures absent from this bundle and exits 2 instead of claiming a pass.

Audit inputs can contain conversations and secrets. Metadata extraction does not intentionally print message contents and does not read authentication or cookie files, but summaries are not secret-redacted. Treat originals and local copies as sensitive. Default output storage is the usage-engineer home directory, adjustable with UE_STATE_DIR or an output argument; displayed home paths are redacted. Configuration-writing profile and rollback operations require explicit invocation and destination review. Audit and map commands leave model settings unchanged.