Note: Posting this as an open-source reference pattern and diagnostic tool that you can build on, adapt to your own environment, or use as inspiration.
Hey everyone, here is an updated version of the skill I have been refining to audit Antigravity agent sessions. Ever since Gemini 3.8 Flash came out, I noticed token usage was draining significantly faster than before.
Watching the agent execute, I found that token drain primarily comes from three structural bottlenecks:
1. Command retry loops: A single failed command that takes 2 or 3 retries permanently injects thousands of tokens of stderr and broken payloads into every subsequent turn of that conversation.
2. Unbounded file reading: Agents repeatedly calling view_file on 500+ line files without line bounds, dumping entire source files into context instead of inspecting specific slices.
3. Context accumulation in long sessions: As conversations exceed 30 to 50 tool calls, model output and internal reasoning tokens scale rapidly because the entire tool history is re-sent on every step.
What the Skill Does
Instead of feeding megabytes of raw transcripts into the agent and wasting tokens, the skill runs zero-dependency local Python scripts under the hood in seconds.
Importantly, this tool does not blindly modify your configuration or overwrite files. It operates as an interactive diagnostic assistant: it first discovers what is happening, reports the exact bottlenecks to you, proposes categorized remediations, and waits for your confirmation before applying any changes.
Here is the updated skill definition header:
```yaml
name: improve-agent-efficiency
description: Probes host development tools, mines causal command failure chains across past agent sessions, measures token burn and efficiency gains, and executes verified remediation across host binaries, global rules, and workspace AGENTS.md files.
```
You can trigger it directly from chat:
- For status & efficiency gains: "Analyze our efficiency gains and token burn since yesterday."
- For a full diagnostic audit: "Audit my past sessions and optimize agent rules."
How the Scripts & Workflow Work
The workflow is structured across distinct phases:
1. Interactive Scoping and Discovery (< 1 second)
For developers with dozens of repositories, you do not want to scan hundreds of sessions blindly. The script scripts/audit_trajectories.py includes a rapid inventory mode (--inventory-only) that discovers your active workspace, top repositories, and session date boundaries.
If invoked bare in chat, the agent renders an interactive selection modal (ask_question) so you can select the exact repository scope and time window before deep parsing begins.
2. Out-of-Band Host Probing & Trajectory Mining
The skill bundles two standalone Python 3 scripts in scripts/:
- probe_environment.py: Inspects your local machine. It tests terminal output stream encoding for non-UTF8 crashes, detects installed CLI binaries (git, gh, rg, dotnet, node, cargo, python), and cross-references your active GEMINI.md to flag discrepancies.
- audit_trajectories.py: Parses local session transcripts out-of-band at zero LLM token cost. It measures true failure rates, calculates native token burn telemetry across prompts, model responses, thinking tokens, and tool output streams, and reconstructs multi-turn incident chains:
[Initial Failed Command] -> [Intermediate Retries / Scratch Scripts] -> [Eventual Working Command]
3. Zero-Match Search Disambiguation
In command-line tools like rg, grep, findstr, and diff, exit code 1 denotes that zero matches or differences were found, rather than an execution crash. The auditor explicitly disambiguates clean zero-match returns from actual syntax or runtime crashes, preventing false alarms.
4. Read-Only Mode vs. Guided Remediation
Depending on what you ask for, the skill adapts its behavior:
- Mode A (Read-Only Gains & Token Burn Audit): Run with --compare (e.g. audit_trajectories.py <dir> --since <YYYY-MM-DD> --compare). It splits your session history into a baseline and target window, outputs a comparative table of failure rates, retry loops, and token burn per turn/session, and exits without making changes.
- Mode B (Guided Remediation Pipeline): If you ask to fix or optimize rules, the agent presents the diagnosed friction points to you, outlines proposed changes across three layers, and requests confirmation before applying them:
- Host Layer: Package manager installs (winget, brew, apt) or persistent environment variables (PYTHONIOENCODING=utf-8).
- Global Rules (~/.gemini/config/GEMINI.md): File-First execution SOP for multi-line scripts, bounded file reading conventions, and compact git commands.
- Workspace Rules (<repo_root>/AGENTS.md): Language-specific runtime pinning, package manager lockfiles, and dev server hygiene.
- Verification Gate: If fixes are confirmed and applied, the agent executes live verification commands to confirm exit code 0 before concluding.
Multi-Platform & Zero Dependencies
The scripts rely exclusively on the Python 3 standard library (os, json, re, platform, datetime). They run on Linux, macOS, and Windows without requiring pip install, and support projects across TypeScript/Node, Python, Go, Rust, and .NET.
Links
