Token-Frugal Engineering
Overview
The expensive resource is main-context tokens, not wall-clock. Every file dumped, log scrolled, or option narrated burns budget you can't get back. This skill is the distilled discipline for spending tokens where they buy correctness and nowhere else.
Core principle: Keep verbose, low-signal work OUT of main context. Pull only the conclusion in.
Announce at start (long/heavy tasks): "Using token-frugal-engineering to keep context lean."
The Essence Rules
| # |
Rule |
Why |
| 1 |
Delegate verbose work to subagents — when output is bulky AND you need only the verdict: tests, builds, log scans, broad searches, doc fetches. Instruct the agent to return capped, structured output ("≤10 lines, failing names only"). |
Raw output never lands in main context. Skip for a short log/tiny suite — agent overhead beats the savings there |
| 2 |
Search, don't read — Grep/Glob to locate; never cat/find/whole-file reads to explore |
A read pulls the whole file; a grep pulls 3 lines |
| 3 |
Scoped reads — Read with offset/limit on the part you need |
Don't load 2000 lines for one function |
| 4 |
Don't re-read to confirm a write landed — Edit/Write already errors on failure; harness tracks state. Legit verification reads (did the logic come out right after a tricky multi-edit) are fine. |
Confirm-reads are pure waste; correctness-reads are not |
| 5 |
Plan before code on non-trivial tasks |
Misdirected edits = wasted tokens + rework churn |
| 6 |
Batch independent tool calls in one message (parallel) |
Fewer round-trips, less restated context |
| 7 |
Deterministic > generative — scripts/validators/generators for mechanical work |
A regex/linter costs ~0 model tokens vs reasoning each case |
| 8 |
Reference skills by name, never @-load |
@path force-loads the whole file immediately, before you need it |
| 9 |
Progressive disclosure in skills — thin SKILL.md, heavy detail in reference files loaded on demand |
Always-loaded bytes tax every conversation |
| 10 |
Terse output — answer, don't narrate options you won't pursue |
Prose is tokens too |
| 11 |
Session hygiene — between unrelated tasks, /clear; on a long thread, summarize-then-continue |
Rules 1–10 stop adding tokens; this removes tokens already accumulated |
Subagent Delegation (rule 1 — the biggest win)
Delegate when output is verbose and you need only the verdict:
- Running a test suite → "run tests, return pass/fail + failing names only"
- Scanning logs → "find the error + 5 lines context"
- Exploring an unknown codebase → use
Explore agent, get the map not the dumps
- Fetching docs → return the one relevant snippet
REQUIRED SUB-SKILL for parallel/independent work: superpowers:dispatching-parallel-agents.
Keep in main context: the decision, the diff, the one file you're actively editing.
Quick Decision
digraph d {
"About to produce/read bulk output?" [shape=diamond];
"Need only the conclusion?" [shape=diamond];
"Delegate to subagent" [shape=box];
"Do it inline (you need the detail)" [shape=box];
"About to produce/read bulk output?" -> "Need only the conclusion?" [label="yes"];
"Need only the conclusion?" -> "Delegate to subagent" [label="yes"];
"Need only the conclusion?" -> "Do it inline (you need the detail)" [label="no"];
}
Audit & Tune
- Context feels bloated? Run the
context-budget skill to find what's eating tokens.
- Choosing response depth deliberately?
token-budget-advisor.
- This skill = how to work frugally; those two = measure and dial.
Companion skills
- Overall delivery engine that pulls this throughout a build →
disciplined-delivery.
- Note: rules 8–9 (
@-load, progressive disclosure) are Claude-Code-specific mechanics; the rest are platform-agnostic.
Common Mistakes
| Mistake |
Fix |
cat-ing a file to "see what's there" |
Grep for the symbol; scoped Read |
| Reading a file back after editing it |
Edit/Write already confirmed; harness tracks state |
| Running the full test suite inline |
Delegate; pull pass/fail summary |
| Narrating 3 approaches before picking |
Recommend one, act |
| Fat always-on SKILL.md / CLAUDE.md |
Move detail to on-demand reference files |
| Serial tool calls for independent reads |
Batch them in one message |
1---2name: token-frugal-engineering3description: Use during any non-trivial coding task in Claude Code — large codebases, long sessions, running tests/builds/logs, repeated file reads, multi-file changes, or whenever context/token usage matters. Stack-agnostic discipline for keeping main context lean.4---56# Token-Frugal Engineering78## Overview910The expensive resource is **main-context tokens**, not wall-clock. Every file dumped, log scrolled, or option narrated burns budget you can't get back. This skill is the distilled discipline for spending tokens where they buy correctness and nowhere else.1112**Core principle:** Keep verbose, low-signal work OUT of main context. Pull only the conclusion in.1314**Announce at start (long/heavy tasks):** "Using token-frugal-engineering to keep context lean."1516## The Essence Rules1718| # | Rule | Why |19|---|---|---|20| 1 | **Delegate verbose work to subagents** — *when output is bulky AND you need only the verdict*: tests, builds, log scans, broad searches, doc fetches. Instruct the agent to return capped, structured output ("≤10 lines, failing names only"). | Raw output never lands in main context. Skip for a short log/tiny suite — agent overhead beats the savings there |21| 2 | **Search, don't read** — Grep/Glob to locate; never `cat`/`find`/whole-file reads to explore | A read pulls the whole file; a grep pulls 3 lines |22| 3 | **Scoped reads** — Read with offset/limit on the part you need | Don't load 2000 lines for one function |23| 4 | **Don't re-read to confirm a write landed** — Edit/Write already errors on failure; harness tracks state. *Legit verification reads (did the logic come out right after a tricky multi-edit) are fine.* | Confirm-reads are pure waste; correctness-reads are not |24| 5 | **Plan before code** on non-trivial tasks | Misdirected edits = wasted tokens + rework churn |25| 6 | **Batch independent tool calls** in one message (parallel) | Fewer round-trips, less restated context |26| 7 | **Deterministic > generative** — scripts/validators/generators for mechanical work | A regex/linter costs ~0 model tokens vs reasoning each case |27| 8 | **Reference skills by name, never `@`-load** | `@path` force-loads the whole file immediately, before you need it |28| 9 | **Progressive disclosure in skills** — thin SKILL.md, heavy detail in reference files loaded on demand | Always-loaded bytes tax every conversation |29| 10 | **Terse output** — answer, don't narrate options you won't pursue | Prose is tokens too |30| 11 | **Session hygiene** — between unrelated tasks, `/clear`; on a long thread, summarize-then-continue | Rules 1–10 stop *adding* tokens; this *removes* tokens already accumulated |3132## Subagent Delegation (rule 1 — the biggest win)3334Delegate when output is **verbose and you need only the verdict**:3536- Running a test suite → "run tests, return pass/fail + failing names only"37- Scanning logs → "find the error + 5 lines context"38- Exploring an unknown codebase → use `Explore` agent, get the map not the dumps39- Fetching docs → return the one relevant snippet4041**REQUIRED SUB-SKILL** for parallel/independent work: `superpowers:dispatching-parallel-agents`.4243Keep in main context: the decision, the diff, the one file you're actively editing.4445## Quick Decision4647```dot48digraph d {49 "About to produce/read bulk output?" [shape=diamond];50 "Need only the conclusion?" [shape=diamond];51 "Delegate to subagent" [shape=box];52 "Do it inline (you need the detail)" [shape=box];53 "About to produce/read bulk output?" -> "Need only the conclusion?" [label="yes"];54 "Need only the conclusion?" -> "Delegate to subagent" [label="yes"];55 "Need only the conclusion?" -> "Do it inline (you need the detail)" [label="no"];56}57```5859## Audit & Tune6061- Context feels bloated? Run the `context-budget` skill to find what's eating tokens.62- Choosing response depth deliberately? `token-budget-advisor`.63- This skill = how to *work* frugally; those two = *measure* and *dial*.6465## Companion skills6667- Overall delivery engine that pulls this throughout a build → `disciplined-delivery`.68- Note: rules 8–9 (`@`-load, progressive disclosure) are Claude-Code-specific mechanics; the rest are platform-agnostic.6970## Common Mistakes7172| Mistake | Fix |73|---|---|74| `cat`-ing a file to "see what's there" | Grep for the symbol; scoped Read |75| Reading a file back after editing it | Edit/Write already confirmed; harness tracks state |76| Running the full test suite inline | Delegate; pull pass/fail summary |77| Narrating 3 approaches before picking | Recommend one, act |78| Fat always-on SKILL.md / CLAUDE.md | Move detail to on-demand reference files |79| Serial tool calls for independent reads | Batch them in one message |
nhattrung0911