token-optimization

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: token-optimization
description: >
  Use when you need to reduce token usage, lower API cost, fit work within a
  context window, or speed up an expensive/slow agent loop. Triggers on
  phrases like "optimize tokens", "reduce token usage", "save on cost",
  "fit in context", "context too long", "running out of tokens", "prompt
  caching", "compact the context", "agent is too expensive", "shrink the
  prompt", "cheaper model", "tokens-per-task". Provides a layered tactic
  catalog — measurement (heuristic counting and budget allocation),
  prompt-side levers (caching, system-prompt diet, tool-definition pruning),
  context management (compression, observation masking, file-system
  offload), agent-loop patterns (parallel tool calls, batch operations,
  model routing by complexity), and output-side controls (depth tiers, stop
  sequences, structured output). Project-agnostic and provider-agnostic;
  works across Claude Code, Codex CLI, Cursor, Gemini CLI, and Copilot.

extensions:
  claude: {}
  copilot: {}
  cursor: {}
  gemini: {}
  codex: {}

version: "1.8.3"

forge:
  status: reviewed
  forged: 2026-05-07
  reviewed: 2026-05-11
---

# Token Optimization

## Overview

Reducing token usage is rarely a single trick — it's a stack of small wins
applied at the right layer. This skill is a triage map: it diagnoses *where*
the tokens are going (system prompt, conversation history, tool results,
agent loops, output verbosity), then points to the matching tactic. The
correct optimization target is **tokens-per-task**, not tokens-per-request:
a one-shot 12k-token prompt that solves the problem beats a 2k-token loop
that takes 30 turns. Apply tactics in order: measure first, then cache,
then compress, then route, then trim output.

## When to activate

- ✅ User says they're hitting context limits, billing surprises, or slow loops
- ✅ User asks how to use prompt caching, compaction, or extended thinking budgets
- ✅ User wants to choose a cheaper model or split work across models
- ✅ Agent itself notices a long-running session crossing roughly 70% context-window utilization (rule-of-thumb trigger; use exact counts when available, heuristic estimate otherwise — trigger earlier on long-running sessions where headroom matters more, later on short tasks)
- ✅ Reviewing a system prompt, CLAUDE.md, or memory file that "feels heavy"

**Do NOT activate when:**
- The topic is a specific tokenizer library (use a `tokenization-*` skill)
- "Token" refers to auth/JWT/payment tokens, or UI design tokens
- The user only wants pricing math (point at provider pricing pages)

## Workflow

Apply the tactics in the order below. Each layer is cheap to try and
independent of the next, so stop as soon as the cost/context goal is met.

### Step 1 — Measure where the tokens go

Before optimizing, locate the cost. For a single request, mentally split
the prompt into five buckets and estimate each:

| Bucket | What it contains | Typical % of total |
|---|---|---|
| System / role | static system prompt, CLAUDE.md, AGENTS.md, memory files | 5 – 40% |
| Tool definitions | tool schemas injected per turn | 5 – 30% |
| Conversation history | prior user/assistant turns | 10 – 50% |
| Tool results | file reads, search output, command stdout | 20 – 70% |
| Current user message + output | this turn's request and reply | 5 – 20% |

Heuristic estimation (no real tokenizer needed):

- English prose: `tokens ≈ words × 1.3`
- Code or mixed: `tokens ≈ chars / 4`
- CJK / multi-byte: `tokens ≈ chars / 2`

Accuracy is roughly ±15%. For exact counts in a Claude / Anthropic SDK
context, use the SDK's `count_tokens` endpoint before the real call. For
detailed budget math (output multipliers, depth tiers), see
[`references/measurement-and-budgets.md`](references/measurement-and-budgets.md).

Output: state which 1–2 buckets dominate. The bucket dictates which step
below to focus on.

### Step 2 — Make the static prefix cacheable

The single biggest win for repeated calls is **pro