Src

---
name: token-goat
description: "Use before reading whole files or grepping wide. token-goat commands (symbol, read, section, semantic, outline, map, refs, bash-output) return narrow slices at low token cost. `/token-goat audit` reviews a session for missed savings."
argument-hint: "[audit] | bare invocation applies the read gate; 'audit' runs a session retrospective and emits a Maintainer Feedback Card"
version: "1.9.3"
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
---
<!-- Generated by token-goat from src/canonical_skill.md; edit it there and run token-goat install, never this file. -->

## When to Use

Always, before a file read — that is the point, and it is why this skill is a gate rather than a technique. There is no threshold to reach and no task size that exempts it: the question "is there a command that returns just what I need" costs nothing to ask and the answer is usually yes.

The exemptions are narrow and listed below rather than left to judgement, because a gate with discretionary exemptions is not a gate. A file under roughly 200 lines that you need whole, a file that was never indexed, and a genuinely opaque binary are the cases where a direct read is the right call.

Where it pays most is iterative work: a loop, a review pass, or a long session re-opens the same files repeatedly, and each re-read is charged again at full price against a budget the task itself needs.

Neighbours that own a case outright:

- **`agent-self-compaction`** — what survives a compaction, rather than what enters context in the first place. The other half of the same budget.
- **`subagent-driven-development`** — a spawned agent starts blank and re-pays for everything its brief omitted, which is a briefing problem before it is a retrieval one.
- **`semantic` (this skill's own command)** — when you are searching for a *concept* rather than a literal string, that is a command here, not a reason to fall back to a wide grep.

## token-goat

**Gate — before every file read, answer one question first: is there a token-goat command that returns just what I need?** If yes, run it. A read tool invoked without answering the gate is a violation, not an oversight. The gate is per file: batched or parallel reads do not exempt it.

This gate decides *whether* to reach for a read tool at all. Claude Code's own Read, Grep, and Glob preference rules only pick the *fallback* once token-goat has been ruled out for this read — they never authorize skipping the gate.

Fallback clauses may name your harness's own native read, search, and edit tools, or its shell helpers. Shell binaries and editor programs are commands invoked through the shell tool, never tool identifiers, and must never appear in an agent's tools frontmatter or an allowed-tools list. This paragraph deliberately names no specific tool or binary: instruction-file loaders harvest such names into a tool allowlist and then warn that every one of them is unknown.

Exemptions (gate passes, read directly): the file is under ~200 lines and you need all of it; it was never indexed (new, untracked, or generated this turn); it is a genuinely opaque binary (not an image); the target has no symbol handle (e.g. a literal mid-function).

Failure shapes to catch yourself in, and the command that replaces each:
- a shell text search with context flags to find a function body → `read "file::symbol"`
- paging one function with view/view_range → `read "file::symbol"`
- reading a symbol plus chasing its callers and containing doc section as separate reads → `brief "file::symbol"`
- reading one heading of a large doc → `section "file::Heading"`
- reading a procedural shell script check or step → `section "script.sh::# Banner"` or `read "script.sh::# Banner"`
- searching for a symbol's callers → `refs file::symbol --callers`
- searching for a *concept* rather than a literal string → `semantic "description"`
- verifying semantic embedding availability before querying → `semantic --preflight` or `semantic --warm`
- re-reading output you already captured → `bash-output`/`web-output`/`mcp-output` by ID
- verifying a terminal command actually wrote fresh output → `bash-output --file <path> --verify-last-write`
- discovering schema for session store or workflow database without guessing → `session-schema [table]` or `describe <target> [table]`
- a directory listing or recursive wildcard walk to orient in an unfamiliar repo → `map --compact`
- pulling one value or subtree out of a JSON/YAML/XML file (manifest, lockfile, spec, config) → `json-query file 'a.b.c'` / `yaml-query file 'a.b.c'` / `xml-query file 'a.b.c'`
- opening an image to check its dimensions, format, or size → `image-meta file`
- opening a screenshot, diagram, or scan to read the text in it → `image-text file`
- opening a PDF or Office document → inspect its format first, then read a narrow slice: PDF `pdf-meta`/`pdf-outline` then `pdf-locate` to find the pages that mention a term and `pdf-extract --pages` only those; Word `docx-outline` then `docx-tables`/`docx-text`; PowerPoint `pptx-outline` then `pptx-slide`/`pptx-notes`; Excel `xlsx-sheets` then `xlsx-columns`/`xlsx-head`/`xlsx-range`/`xlsx-query`

- reading a large SKILL.md/CHANGELOG.md (or re-reading a skill already loaded) → `skill-section <name> '<Heading>'` / `skill-body <name>`
- raw-Reading a Claude Code session JSONL transcript → `session-outline` then `session-slice`
- re-searching cached tool output across the whole session → `recall <query>`
- persisting a small cross-call fact in conversation context → `note set/get/unset/list`
Commands: `symbol NAME`, `read "file::symbol"`, `brief "file::symbol"`, `section "file::Heading"`, `semantic "description"`, `outline file`/`skeleton file`, `map --compact`, `refs file::symbol --callers`, `changed --symbol`, `config-get file KEY`, `json-query file 'a.b.c'`/`yaml-query`/`xml-query`, `json-outline file`/`yaml-outline`/`xml-outline`, `bash-output`/`web-output`/`mcp-output`, `gdrive-sections <file-id>`, `image-meta file`/`image-text file`, `pdf-meta`/`pdf-outline`/`pdf-locate`/`pdf-extract`, `docx-outline`/`docx-tables`/`docx-text`, `pptx-outline`/`pptx-slide`/`pptx-notes`/`pptx-text`, `xlsx-sheets`/`xlsx-columns`/`xlsx-head`/`xlsx-range`/`xlsx-query`, `skill-section`/`skill-body`, `session-outline`/`session-slice`, `recall`, `note set/get/unset/list`.

Sub-agent briefs must carry this gate verbatim: a sub-agent inherits none of this context and its reads spend the same token budget.

`token-goat stats` — self-check. Flat counts during code work mean the gate is being skipped.

## Subcommands

| Invocation | Action |
|---|---|
| `/token-goat`, or any other argument | The gate above applies. There is no separate procedure to run. |
| `/token-goat audit` | Session retrospective and Maintainer Feedback Card — below. |

### audit — session retrospective

Reviews the session it is invoked in for token-goat optimisation opportunities and reports to the maintainer, with no proprietary data or PII.

**Gather evidence by command, not by recollection.** The transcript is the wrong thing to read: `session-outline` on a long session runs to tens of megabytes, so reading one to write a report about wasteful whole-file reads would cost more than every read it criticises. Run these and quote what they return.

| Question | Command |
|---|---|
| What did this session spend, per tool and per file? | `waste --top 10` |
| Which files were read once and never used again? | the `Read once, never touched again` block of the same output |
| Did hints fire and get ignored? | `hint-stats` |
| What has token-goat saved, and on what basis? | `stats`, then `stats --methodology` |
| Is the install healthy? | `doctor` |
| Billed versus estimated tokens across the corpus | `session-audit` |
| A specific moment worth quoting | `session-outline` piped to a pattern search for the turn number, then `session-slice --range N-M` |
| Output already captured this session | `bash-output`/`web-output`/`mcp-output` by ID, or `recall <query>` |

Never run `hint-stats --reset` or `doctor --repair` during an audit. Both change state, and an audit reports.

**Partition pre-audit work from audit execution.** The primary subject of the retrospective is what the session was doing *before* the audit was called (the user's task, searches, code changes, builds, and test runs). Never let findings on the audit's own tool calls substitute for the session's work.

Then answer in order:

1. **Missed surgical reads in the pre-audit session.** Where a whole file or large section was read during the task that `symbol`, `read`, or `section` would have covered, and where finding something took too long when a command would have found it faster. `waste` gives the per-file cost and the read-once list; name the files. If the pre-audit session had zero missed reads, state that explicitly.
2. **Hook friction and hints.** Hints that fired during the session and were ignored, and denials that caused friction or confusion. `hint-stats` reports emitted against acted-on per category; read its footnote before quoting an efficacy figure, because the starred rows are scored on an absence and do not mean what the unstarred ones mean.
3. **Large command outputs.** Logs, diffs, or terminal output in the pre-audit session that `compress` could have shrunk, or shrunk further. The top-expensive-calls block of `waste` ranks them.
4. **Performance and bugs.** Commands that failed, hung, misparsed, or returned less than they could have. Quote the invocation and its output.
5. **Audit execution findings (isolated).** If running the audit itself encountered friction, missing flags, or unexpected tool overhead, record it here separately from the pre-audit session work.
6. **Adversarial pass before concluding.** Every claim needs command output behind it; drop the ones that do not have it rather than softening them into hedges. If the session was clean, say so plainly — "nothing to improve here in the session" is a real result, and padding it is worse than sending it.
7. **Health check.** If `doctor` has not run recently, run it and pass on the actions it recommends.
8. **Savings estimate, with its basis stated.** Prefer a measured figure — `stats` for what token-goat recorded, `waste` for this session's spend — and give the window and method alongside the number: `stats` defaults to 30 days across every project rather than this session, and `stats --methodology` says in its own words that these are local estimates, not billing data. Convert to development time only if you can name the rate you used. If a number cannot be sourced, say so instead of inventing one.

**Then emit the card**, under 150 words, a hard cap on the card rather than on the analysis behind it:

- **Task Summary** — one sentence on what the session did before the audit was invoked.
- **Friction & Missed Savings** — two to four bullets:
  - Bullets for pre-audit session findings (or explicitly: "• Pre-audit session: No missed surgical reads or friction detected; gate adhered to cleanly"). When fixed MCP tool definition overhead is an issue, quantify the exact waste per MCP server (server name, tool count, estimated tokens per turn, and cumulative re-sent tokens across session turns).
  - If the audit itself encountered friction or tool defects, record it in a separate, dedicated bullet labelled "• Audit Execution: ...".
- **Recommended Fix** — at least one concrete change or feature, with the excerpt or example needed to act on it.

Paths go in relative to the working directory; `waste` prints absolute ones, so trim them. Keep excerpts to the few lines carrying the point, and scrub anything identifying.

## Anti-Patterns

- **Answering the gate with "probably not" instead of a command.** The gate is a question with a checkable answer, not a disposition. If you cannot name which command would have worked, you have not answered it -- and `token-goat stats` will show the flat counts that prove it.
- **Treating a batch as one gate.** Five reads issued in one message are five gates, not one. Batching is a latency optimisation; it does not pool the token cost.
- **Using `symbol` as a grep.** `symbol NAME` resolves a definition. When you want every *use*, that is `refs file::symbol --callers`; when you want a concept rather than a literal string, that is `semantic`. Reaching for the wrong one and then falling back to a wide search spends the cost of both.
- **Slicing a file that was never indexed.** A file created, generated, or left untracked this turn has no index entry, so a slice command returns nothing and reads as "not there" rather than "not indexed". That case is an explicit exemption -- read it directly and move on instead of retrying the slice.
- **Re-running a command to see output you already have.** Captured output is addressable by ID via `bash-output`/`web-output`/`mcp-output`, and anything cached this session is reachable with `recall`. Re-running is the most expensive way to scroll up.
- **Writing tool or binary names into an agent's `tools`/`allowed-tools` frontmatter.** Shell binaries and editor programs are invoked *through* the shell tool; they are not tool identifiers. Instruction-file loaders harvest such names into an allowlist and then warn that every one is unknown -- which is why the gate text above deliberately names none.
- **Dropping the gate from a sub-agent brief.** A sub-agent inherits none of this context and spends the same budget, so a brief without the gate verbatim is where the savings quietly leak back out.

## Related Skills

- **superman**: points to the shared CLI stack (`engineering-foundations/snippets/cli_stack.md`) in its CLI Tool Override section and is the most common caller of it -- the gate is what keeps a bounded engineering task from opening with a wide read.
- **agent-self-compaction**: the other half of the token-budget story; this skill governs what enters context, that one governs what survives compaction.
- **subagent-driven-development**: the sub-agent brief requirement above is its concern in practice -- every spawned agent starts blank and re-pays for anything the brief omits.
- **improve**: iterative passes over a file are where re-reading compounds fastest, so the gate matters more per turn there than in one-shot work.
- **routing-agent-memory**: decides which store a fact belongs in (`note`, `mem`, STATE file); this skill owns the `note` mechanics and the read gate