token-optimization

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: token-optimization
description: >-
  Token Optimization is the systematic reduction of token expenditure across agent operations without sacrificing output quality.
---

# Token Optimization

Part of [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills) by [googleadsagent.ai™](https://googleadsagent.ai)

## Description

Token Optimization is the systematic reduction of token expenditure across agent operations without sacrificing output quality. In production AI systems, tokens are the fundamental unit of both cost and latency — every unnecessary token increases API bills and slows response times. This skill codifies the optimization techniques used in the Everything Claude Code ecosystem (150k+ stars) and the [googleadsagent.ai™](https://googleadsagent.ai) production platform, where Buddy™ processes thousands of Google Ads analyses daily within strict cost budgets.

The optimization surface spans four dimensions: model selection (matching task complexity to model capability and cost), prompt compression (removing redundant tokens while preserving instruction fidelity), background processing (offloading expensive operations to async workflows), and caching (avoiding redundant computation for identical or similar inputs). Production systems that implement all four dimensions typically achieve 60-80% token cost reduction compared to naive implementations.

Token optimization is not about being cheap — it is about being efficient. An agent that wastes tokens on verbose system prompts or redundant tool outputs is not only expensive; it fills its context window faster, leaving less room for actual reasoning. Optimization improves both economics and quality simultaneously.

## Use When

- Monthly API costs exceed budget targets for AI agent operations
- Response latency is above acceptable thresholds for user-facing agents
- Context windows are filling up before complex tasks can complete
- Multiple model tiers are available and you need intelligent routing
- Batch processing workloads generate high token volumes
- You need to scale agent usage without proportional cost increases

## How It Works

```mermaid
graph TD
    A[Incoming Task] --> B[Complexity Classifier]
    B -->|Simple| C[Fast Model<br/>Haiku/Flash]
    B -->|Medium| D[Balanced Model<br/>Sonnet/GPT-4o]
    B -->|Complex| E[Premium Model<br/>Opus/o1]
    C --> F[Prompt Compressor]
    D --> F
    E --> F
    F --> G{Cache Hit?}
    G -->|Yes| H[Return Cached Result]
    G -->|No| I[Execute with Budget]
    I --> J[Cache Result]
    J --> K[Response]
    H --> K
    I --> L{Background Eligible?}
    L -->|Yes| M[Async Queue]
    M --> I
    L -->|No| I
```

Tasks enter through a complexity classifier that routes to the appropriate model tier. The prompt compressor strips redundant content, shortens verbose instructions, and replaces narrative descriptions with structured formats. A cache layer intercepts repeated or near-duplicate queries. Background-eligible tasks (non-interactive analysis, batch operations) are queued for async processing outside peak hours. Every stage enforces a token budget that hard-limits expenditure per operation.

## Implementation

**Task Complexity Classifier:**

```python
class ComplexityClassifier:
    THRESHOLDS = {
        "simple": {"max_tokens": 500, "patterns": ["summarize", "format", "list", "count"]},
        "medium": {"max_tokens": 2000, "patterns": ["analyze", "compare", "explain", "review"]},
        "complex": {"max_tokens": 8000, "patterns": ["architect", "refactor", "debug", "optimize"]},
    }

    def classify(self, task: str) -> str:
        task_lower = task.lower()
        scores = {}
        for level, config in self.THRESHOLDS.items():
            score = sum(1 for p in config["patterns"] if p in task_lower)
            scores[level] = score

        if scores["complex"] > 0:
            return "complex"
        if scores["medium"] > 0:
            return "medium"
        return "simple"

    d