Context Optimization

1---
2name: context-optimization
3description: This skill should be used when the user asks to "optimize context", "reduce token costs", "improve context efficiency", "implement KV-cache optimization", "partition context", or mentions context limits, observation masking, context budgeting, or extending effective context capacity.
4---
5 
6# Context Optimization Techniques
7 
8Context optimization extends the effective capacity of limited context windows through strategic compression, masking, caching, and partitioning. The goal is not to magically increase context windows but to make better use of available capacity. Effective optimization can double or triple effective context capacity without requiring larger models or longer contexts.
9 
10## When to Activate
11 
12Activate this skill when:
13- Context limits constrain task complexity
14- Optimizing for cost reduction (fewer tokens = lower costs)
15- Reducing latency for long conversations
16- Implementing long-running agent systems
17- Needing to handle larger documents or conversations
18- Building production systems at scale
19 
20## Core Concepts
21 
22Context optimization extends effective capacity through four primary strategies: compaction (summarizing context near limits), observation masking (replacing verbose outputs with references), KV-cache optimization (reusing cached computations), and context partitioning (splitting work across isolated contexts).
23 
24The key insight is that context quality matters more than quantity. Optimization preserves signal while reducing noise. The art lies in selecting what to keep versus what to discard, and when to apply each technique.
25 
26## Detailed Topics
27 
28### Compaction Strategies
29 
30**What is Compaction**
31Compaction is the practice of summarizing context contents when approaching limits, then reinitializing a new context window with the summary. This distills the contents of a context window in a high-fidelity manner, enabling the agent to continue with minimal performance degradation.
32 
33Compaction typically serves as the first lever in context optimization. The art lies in selecting what to keep versus what to discard.
34 
35**Compaction Implementation**
36Compaction works by identifying sections that can be compressed, generating summaries that capture essential points, and replacing full content with summaries. Priority for compression goes to tool outputs (replace with summaries), old turns (summarize early conversation), retrieved docs (summarize if recent versions exist), and never compress system prompt.
37 
38**Summary Generation**
39Effective summaries preserve different elements depending on message type:
40 
41Tool outputs: Preserve key findings, metrics, and conclusions. Remove verbose raw output.
42 
43Conversational turns: Preserve key decisions, commitments, and context shifts. Remove filler and back-and-forth.
44 
45Retrieved documents: Preserve key facts and claims. Remove supporting evidence and elaboration.
46 
47### Observation Masking
48 
49**The Observation Problem**
50Tool outputs can comprise 80%+ of token usage in agent trajectories. Much of this is verbose output that has already served its purpose. Once an agent has used a tool output to make a decision, keeping the full output provides diminishing value while consuming significant context.
51 
52Observation masking replaces verbose tool outputs with compact references. The information remains accessible if needed but does not consume context continuously.
53 
54**Masking Strategy Selection**
55Not all observations should be masked equally:
56 
57Never mask: Observations critical to current task, observations from the most recent turn, observations used in active reasoning.
58 
59Consider masking: Observations from 3+ turns ago, verbose outputs with key points extractable, observations whose purpose has been served.
60 
61Always mask: Repeated outputs, boilerplate headers/footers, outputs already summarized in conversation.
62 
63### KV-Cache Optimization
64 
65**Understanding KV-Cache**
66The KV-cache stores Key and Value tensors computed during inference, growing linearly with sequence length. Caching the KV-cache across requests sharing identical prefixes avoids recomputation.
67 
68Prefix caching reuses KV blocks across requests with identical prefixes using hash-based block matching. This dramatically reduces cost and latency for requests with common prefixes like system prompts.
69 
70**Cache Optimization Patterns**
71Optimize for caching by reordering context elements to maximize cache hits. Place stable elements first (system prompt, tool definitions), then frequently reused elements, then unique elements last.
72 
73Design prompts to maximize cache stability: avoid dynamic content like timestamps, use consistent formatting, keep structure stable across sessions.
74 
75### Context Partitioning
76 
77**Sub-Agent Partitioning**
78The most aggressive form of context optimization is partitioning work across sub-agents with isolated contexts. Each sub-agent operates in a clean context focused on its subtask without carrying accumulated context from other subtasks.
79 
80This approach achieves separation of concerns—the detailed search context remains isolated within sub-agents while the coordinator focuses on synthesis and analysis.
81 
82**Result Aggregation**
83Aggregate results from partitioned subtasks by validating all partitions completed, merging compatible results, and summarizing if still too large.
84 
85### Budget Management
86 
87**Context Budget Allocation**
88Design explicit context budgets. Allocate tokens to categories: system prompt, tool definitions, retrieved docs, message history, and reserved buffer. Monitor usage against budget and trigger optimization when approaching limits.
89 
90**Trigger-Based Optimization**
91Monitor signals for optimization triggers: token utilization above 80%, degradation indicators, and performance drops. Apply appropriate optimization techniques based on context composition.
92 
93## Practical Guidance
94 
95### Optimization Decision Framework
96 
97When to optimize:
98- Context utilization exceeds 70%
99- Response quality degrades as conversations extend
100- Costs increase due to long contexts
101- Latency increases with conversation length
102 
103What to apply:
104- Tool outputs dominate: observation masking
105- Retrieved documents dominate: summarization or partitioning
106- Message history dominates: compaction with summarization
107- Multiple components: combine strategies
108 
109### Performance Considerations
110 
111Compaction should achieve 50-70% token reduction with less than 5% quality degradation. Masking should achieve 60-80% reduction in masked observations. Cache optimization should achieve 70%+ hit rate for stable workloads.
112 
113Monitor and iterate on optimization strategies based on measured effectiveness.
114 
115## Examples
116 
117**Example 1: Compaction Trigger**
118```python
119if context_tokens / context_limit > 0.8:
120    context = compact_context(context)
121```
122 
123**Example 2: Observation Masking**
124```python
125if len(observation) > max_length:
126    ref_id = store_observation(observation)
127    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"
128```
129 
130**Example 3: Cache-Friendly Ordering**
131```python
132# Stable content first
133context = [system_prompt, tool_definitions]  # Cacheable
134context += [reused_templates]  # Reusable
135context += [unique_content]  # Unique
136```
137 
138## Guidelines
139 
1401. Measure before optimizing—know your current state
1412. Apply compaction before masking when possible
1423. Design for cache stability with consistent prompts
1434. Partition before context becomes problematic
1445. Monitor optimization effectiveness over time
1456. Balance token savings against quality preservation
1467. Test optimization at production scale
1478. Implement graceful degradation for edge cases
148 
149## Integration
150 
151This skill builds on context-fundamentals and context-degradation. It connects to:
152 
153- multi-agent-patterns - Partitioning as isolation
154- evaluation - Measuring optimization effectiveness
155- memory-systems - Offloading context to memory
156 
157## References
158 
159Internal reference:
160- [Optimization Techniques Reference](./references/optimization_techniques.md) - Detailed technical reference
161 
162Related skills in this collection:
163- context-fundamentals - Context basics
164- context-degradation - Understanding when to optimize
165- evaluation - Measuring optimization
166 
167External resources:
168- Research on context window limitations
169- KV-cache optimization techniques
170- Production engineering guides
171 
172---
173 
174## Skill Metadata
175 
176**Created**: 2025-12-20
177**Last Updated**: 2025-12-20
178**Author**: Agent Skills for Context Engineering Contributors
179**Version**: 1.0.0
180