agentleFS
nhattrung0911nhattrung0911/shipwright/skills/token-frugal-engineering/SKILL.md

token-frugal-engineering

Skill0 starsChanged 5 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Core principle: Keep verbose, low-signal work OUT of main context.

    line 12
  2. Distinctive:

    Keep in main context: the decision, the diff, the one file you're actively editing.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

#RuleWhy
1Delegate 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
2Search, don't read — Grep/Glob to locate; never cat/find/whole-file reads to exploreA read pulls the whole file; a grep pulls 3 lines
3Scoped reads — Read with offset/limit on the part you needDon't load 2000 lines for one function
4Don'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
5Plan before code on non-trivial tasksMisdirected edits = wasted tokens + rework churn
6Batch independent tool calls in one message (parallel)Fewer round-trips, less restated context
7Deterministic > generative — scripts/validators/generators for mechanical workA regex/linter costs ~0 model tokens vs reasoning each case
8Reference skills by name, never @-load@path force-loads the whole file immediately, before you need it
9Progressive disclosure in skills — thin SKILL.md, heavy detail in reference files loaded on demandAlways-loaded bytes tax every conversation
10Terse output — answer, don't narrate options you won't pursueProse is tokens too
11Session hygiene — between unrelated tasks, /clear; on a long thread, summarize-then-continueRules 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

MistakeFix
cat-ing a file to "see what's there"Grep for the symbol; scoped Read
Reading a file back after editing itEdit/Write already confirmed; harness tracks state
Running the full test suite inlineDelegate; pull pass/fail summary
Narrating 3 approaches before pickingRecommend one, act
Fat always-on SKILL.md / CLAUDE.mdMove detail to on-demand reference files
Serial tool calls for independent readsBatch them in one message

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.