Token Budget

Standing rules for the rest of this session. Apply them silently — do not narrate that you are applying them.

The mechanic that drives all of it: every turn resends the entire conversation. Today's output is tomorrow's input, billed again on every subsequent turn. So the cheapest token is the one that never enters context. Optimise for what you refuse to load, not for shorter prompts.

Script paths below use ${CLAUDE_SKILL_DIR}. On agents that do not substitute it, use the path to this skill folder.

0. When NOT to apply this

These rules trade depth for economy. That is the wrong trade whenever the output itself is the value being paid for. Do not apply them — and say so plainly — in sessions like:

• Long-form writing where voice matters: narrative, storytelling, anything with a style to hold
• Knowledge-base or briefing prep, where having the whole source in context is the entire point
• High-stakes documents (resumes, proposals, client deliverables) where missing one line of the source is the failure mode
• Any session where the user has said quality beats cost

If a session looks like one of these, state in one line that token discipline is off for it and work normally. Economy is not free — it is bought with depth. Spend it on mechanical work, not on the work someone is paying for.

1. Before loading anything

• Never read a whole file to find part of it. Grep first, then read only the matching window: node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs "<pattern>" <path> --window 20
• Size it before you ingest it: node ${CLAUDE_SKILL_DIR}/scripts/budget.mjs <path|glob>. Over ~2,000 tokens and you need less than a fifth of it → scan, don't read.
• Never re-read a file already read this session. It is still in context. Refer to it.
• Convert before ingesting. PDF, DOCX, HTML, screenshot of text → node ${CLAUDE_SKILL_DIR}/scripts/slim.mjs <file>. Send the text, not the container. An image of a table costs many times the table.
• Take the user's pointer over your own search. If they name a file, function, or line range, go straight there.

2. While working

• Turn exact work into code. Counting, parsing, diffing, sorting, renaming, arithmetic, schema checks — write a small script, run it, keep it. Reasoning through mechanical work burns tokens on every retry; a script costs once.
• Two strikes, then stop. After two failed attempts at the same approach, stop and report what failed with the specific error. Do not loop — each retry resends the whole transcript.
• Answer at the size asked. No restating the plan, no echoing file contents back, no summary of what you just did unless asked. Default to a diff plus ≤5 lines. If the user asked for JSON, five bullets, or one paragraph, give exactly that.
• Batch. If you need three things from the user, ask for all three in one turn.

3. At stage boundaries — the largest single win

When a stage completes (research done, approach agreed, root cause found, feature shipped), do not continue in the same thread.

1. Write a handoff from ${CLAUDE_SKILL_DIR}/assets/handoff-template.md to .claude/handoff/<task>.md.
2. Tell the user: "Stage done. Handoff at .claude/handoff/<task>.md — /clear and start the next stage from it."

Carry the result forward, never the argument. Drafts you rejected, options you discarded, stack traces you already fixed, and your own reasoning do not go in the handoff.

If the task genuinely cannot be restarted mid-flight, compact instead — and say explicitly what was dropped, because compaction hands you an approximation of the earlier turns, not the originals.

4. Environment hygiene — do once per project, then report

• Audit loaded tools. Every connected MCP server ships its tool definitions as input on every turn, before any work happens. A handful of servers can cost tens of thousands of tokens per turn. List what is connected, name which ones this project never calls, recommend disabling them.
• Right-size the model. For mechanical work, name the smallest model that will finish it and say so. Never switch silently.
• Keep accepted answers retrievable. Append settled decisions to .claude/decisions.md, one line each. Check that file before recomputing anything you may have already answered.

5. Every permanent edit goes inside the markers

When you add a standing token-saving instruction to CLAUDE.md, AGENTS.md, or any always-loaded file, put it inside the managed block:

<!-- token-budget:start — managed block, do not edit by hand -->
   … everything token-budget owns lives here …
<!-- token-budget:end -->

Never write a token-budget instruction outside these markers, and never split it across two places. This is what keeps uninstall exact: the block can grow to fifty lines over months and removal stays a single deterministic operation. If the markers are missing, run node ${CLAUDE_SKILL_DIR}/scripts/install.mjs before adding anything.

6. Invocation modes

Reference file

• references/platform-notes.md — Claude Code, Codex, and raw-API levers: prompt caching, context editing, compaction, hard limits, and the ranked order of impact. Read when the user is tuning a specific runtime or working against the API.