@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/context-degradation.md

@@ -0,0 +1,208 @@
+---
+name: context-degradation
+description: This skill should be used when the user asks to "diagnose context problems", "fix lost-in-middle issues", "debug agent failures", "understand context poisoning", or mentions context degradation, attention patterns, context clash, context confusion, or agent performance degradation. A core context engineering skill — also activates when the user mentions "context engineering" or "context-engineering" in the context of diagnosing and mitigating context failures.
+metadata:
+  provider: atomic
+---
+
+# Context Degradation Patterns
+
+Diagnose and fix context failures before they cascade. Context degradation is not binary — it is a continuum that manifests through five distinct, predictable patterns: lost-in-middle, poisoning, distraction, confusion, and clash. Each pattern has specific detection signals and mitigation strategies. Treat degradation as an engineering problem with measurable thresholds, not an unpredictable failure mode.
+
+## When to Activate
+
+Activate this skill when:
+- Agent performance degrades unexpectedly during long conversations
+- Debugging cases where agents produce incorrect or irrelevant outputs
+- Designing systems that must handle large contexts reliably
+- Evaluating context engineering choices for production systems
+- Investigating "lost in middle" phenomena in agent outputs
+- Analyzing context-related failures in agent behavior
+
+## Core Concepts
+
+Structure context placement around the attention U-curve: beginning and end positions receive reliable attention, while middle positions suffer 10-40% reduced recall accuracy (Liu et al., 2023). This is not a model bug but a consequence of attention mechanics — the first token (often BOS) acts as an "attention sink" that absorbs disproportionate attention budget, leaving middle tokens under-attended as context grows.
+
+Treat context poisoning as a circuit breaker problem. Once a hallucination, tool error, or incorrect retrieved fact enters context, it compounds through repeated self-reference. A poisoned goals section causes every downstream decision to reinforce incorrect assumptions. Detection requires tracking claim provenance; recovery requires truncating to before the poisoning point or restarting with verified-only context.
+
+Filter aggressively before loading context — even a single irrelevant document measurably degrades performance on relevant tasks. Models cannot "skip" irrelevant context; they must attend to everything provided, creating attention competition between relevant and irrelevant content. Move information that might be needed but is not immediately relevant behind tool calls instead of pre-loading it.
+
+Isolate task contexts to prevent confusion. When context contains multiple task types or switches between objectives, models incorporate constraints from the wrong task, call tools appropriate for a different context, or blend requirements from multiple sources. Explicit task segmentation with separate context windows eliminates cross-contamination.
+
+Resolve context clash through priority rules, not accumulation. When multiple correct-but-contradictory sources appear in context (version conflicts, perspective conflicts, multi-source retrieval), models cannot determine which applies. Mark contradictions explicitly, establish source precedence, and filter outdated versions before they enter context.
+
+## Detailed Topics
+
+### Lost-in-Middle: Detection and Placement Strategy
+
+Place critical information at the beginning and end of context, never in the middle. The U-shaped attention curve means middle-positioned information suffers 10-40% reduced recall accuracy. For contexts over 4K tokens, this effect becomes significant.
+
+Use summary structures that surface key findings at attention-favored positions. Add explicit section headers and structural markers — these help models navigate long contexts by creating attention anchors. When a document must be included in full, prepend a summary of its key points and append the critical conclusions.
+
+Monitor for lost-in-middle symptoms: correct information exists in context but the model ignores it, responses contradict provided data, or the model "forgets" instructions given earlier in a long prompt.
+
+### Context Poisoning: Prevention and Recovery
+
+Validate all external inputs before they enter context. Tool outputs, retrieved documents, and model-generated summaries are the three primary poisoning vectors. Each introduces unverified claims that subsequent reasoning treats as ground truth.
+
+Detect poisoning through these signals: degraded output quality on previously-successful tasks, tool misalignment (wrong tools or parameters), and hallucinations that persist despite explicit correction. When these cluster, suspect poisoning rather than model capability issues.
+
+Recover by removing poisoned content, not by adding corrections on top. Truncate to before the poisoning point, restart with clean context preserving only verified information, or explicitly mark the poisoned section and request re-evaluation from scratch. Layering corrections over poisoned context rarely works — the original errors retain attention weight.
+
+### Context Distraction: Curation Over Accumulation
+
+Curate what enters context rather than relying on models to ignore irrelevant content. Research shows even a single distractor document triggers measurable performance degradation — the effect follows a step function, not a linear curve. Multiple distractors compound the problem.
+
+Apply relevance filtering before loading retrieved documents. Use namespacing and structural organization to make section boundaries clear. Prefer tool-call-based access over pre-loading: store reference material behind retrieval tools so it enters context only when directly relevant to the current reasoning step.
+
+### Context Confusion: Task Isolation
+
+Segment different tasks into separate context windows. Context confusion is distinct from distraction — it concerns the model applying wrong-context constraints to the current task, not just attention dilution. Signs include responses addressing the wrong aspect of a query, tool calls appropriate for a different task, and outputs mixing requirements from multiple sources.
+
+Implement clear transitions between task contexts. Use state management that isolates objectives, constraints, and tool definitions per task. When task-switching within a single session is unavoidable, use explicit "context reset" markers that signal which constraints apply to the current segment.
+
+### Context Clash: Conflict Resolution Protocols
+
+Establish source priority rules before conflicts arise. Context clash differs from poisoning — multiple pieces of information are individually correct but mutually contradictory (version conflicts, perspective differences, multi-source retrieval with divergent facts).
+
+Implement version filtering to exclude outdated information before it enters context. When contradictions are unavoidable, mark them explicitly with structured conflict annotations: state what conflicts, which source each claim comes from, and which source takes precedence. Without explicit priority rules, models resolve contradictions unpredictably.
+
+### Empirical Benchmarks and Thresholds
+
+Use these benchmarks to set design constraints — not as universal truths. The RULER benchmark found only 50% of models claiming 32K+ context maintain satisfactory performance at that length. Near-perfect needle-in-haystack scores do not predict real-world long-context performance.
+
+**Model-Specific Degradation Thresholds**
+
+Degradation onset varies significantly by model family and task type. As a general rule, expect degradation to begin at 60-70% of the advertised context window for complex retrieval tasks (RULER benchmark found only 50% of models claiming 32K+ context maintain satisfactory performance at that length). Key patterns:
+
+- **Models with extended thinking** reduce hallucination through step-by-step verification but at higher latency and token cost
+- **Models optimized for agents/coding** tend to have better attention management for tool-output-heavy contexts
+- **Models with very large context windows (1M+)** handle more raw context but still follow U-shaped degradation curves — bigger windows do not eliminate the problem, they delay it
+
+Always benchmark degradation thresholds with your specific workload rather than relying on published benchmarks. Model-specific thresholds go stale with each model update (see Gotcha 2).
+
+### Counterintuitive Findings
+
+Account for these research-backed surprises when designing context strategies:
+
+**Shuffled context can outperform coherent context.** Studies found incoherent (shuffled) haystacks produce better retrieval performance than logically ordered ones. Coherent context creates false associations that confuse retrieval; incoherent context forces exact matching. Do not assume that better-organized context always yields better results — test both arrangements.
+
+**Single distractors have outsized impact.** The performance hit from one irrelevant document is disproportionately large compared to adding more distractors after the first. Treat distractor prevention as binary: either keep context clean or accept significant degradation.
+
+**Low needle-question similarity accelerates degradation.** Tasks requiring inference across dissimilar content degrade faster with context length than tasks with high surface-level similarity. Design retrieval to maximize semantic overlap between queries and retrieved content.
+
+### When Larger Contexts Hurt
+
+Do not assume larger context windows improve performance. Performance remains stable up to a model-specific threshold, then degrades rapidly — the curve is non-linear with a cliff edge, not a gentle slope. For many models, meaningful degradation begins at 8K-16K tokens even when windows support much larger sizes.
+
+Factor in cost: processing a 400K token context costs exponentially more than 200K in both time and compute, not linearly more. For many applications, this makes large-context processing economically impractical.
+
+Recognize the cognitive bottleneck: even with infinite context, asking a single model to maintain quality across dozens of independent tasks creates degradation that more context cannot solve. Split tasks across sub-agents instead of expanding context.
+
+## Practical Guidance
+
+### The Four-Bucket Mitigation Framework
+
+Apply these four strategies based on which degradation pattern is active:
+
+**Write** — Save context outside the window using scratchpads, file systems, or external storage. Use when context utilization exceeds 70% of the window. This keeps active context lean while preserving information access through tool calls.
+
+**Select** — Pull only relevant context into the window through retrieval, filtering, and prioritization. Use when distraction or confusion symptoms appear. Apply relevance scoring before loading; exclude anything below threshold rather than including everything available.
+
+**Compress** — Reduce tokens while preserving information through summarization, abstraction, and observation masking. Use when context is growing but all content is relevant. Replace verbose tool outputs with compact structured summaries; abstract repeated patterns into single references.
+
+**Isolate** — Split context across sub-agents or sessions to prevent any single context from growing past its degradation threshold. Use when confusion or clash symptoms appear, or when tasks are independent. This is the most aggressive strategy but often the most effective for complex multi-task systems.
+
+### Architectural Patterns for Resilience
+
+Implement just-in-time context loading: retrieve information only when the current reasoning step needs it, not preemptively. Use observation masking to replace verbose tool outputs with compact references after processing. Deploy sub-agent architectures where each agent holds only task-relevant context. Trigger compaction before context exceeds the model-specific degradation onset threshold — not after symptoms appear.
+
+## Examples
+
+**Example 1: Detecting Degradation**
+```yaml
+# Context grows during long conversation
+turn_1: 1000 tokens
+turn_5: 8000 tokens
+turn_10: 25000 tokens
+turn_20: 60000 tokens (degradation begins)
+turn_30: 90000 tokens (significant degradation)
+```
+
+**Example 2: Mitigating Lost-in-Middle**
+```markdown
+# Organize context with critical info at edges
+
+[CURRENT TASK]                      # At start
+- Goal: Generate quarterly report
+- Deadline: End of week
+
+[DETAILED CONTEXT]                  # Middle (less attention)
+- 50 pages of data
+- Multiple analysis sections
+- Supporting evidence
+
+[KEY FINDINGS]                     # At end
+- Revenue up 15%
+- Costs down 8%
+- Growth in Region A
+```
+
+## Guidelines
+
+1. Monitor context length and performance correlation during development
+2. Place critical information at beginning or end of context
+3. Implement compaction triggers before degradation becomes severe
+4. Validate retrieved documents for accuracy before adding to context
+5. Use versioning to prevent outdated information from causing clash
+6. Segment tasks to prevent context confusion across different objectives
+7. Design for graceful degradation rather than assuming perfect conditions
+8. Test with progressively larger contexts to find degradation thresholds
+
+## Gotchas
+
+1. **Normal variance looks like degradation**: Model output quality fluctuates naturally across runs. Do not diagnose degradation from a single drop in quality — establish a baseline over multiple runs and look for sustained, correlated decline tied to context growth. A 5-10% quality dip on one run is noise; the same dip consistently appearing after 40K tokens is signal.
+
+2. **Model-specific thresholds go stale**: The degradation onset values in benchmark tables reflect specific model versions. Provider updates, fine-tuning changes, and infrastructure shifts can move thresholds by 20-50% in either direction. Re-benchmark quarterly and after any major model update rather than treating published thresholds as permanent.
+
+3. **Needle-in-haystack scores create false confidence**: A model scoring 99% on needle-in-haystack does not mean it handles 128K tokens well in production. Needle tests measure single-fact retrieval from passive context — real workloads require multi-fact reasoning, instruction following, and synthesis across the full window. Use task-specific benchmarks that mirror actual workload patterns.
+
+4. **Contradictory retrieved documents poison silently**: When a RAG pipeline retrieves two documents that disagree on a fact, the model may silently pick one without signaling the conflict. This looks like a correct response but is effectively random. Implement contradiction detection in the retrieval layer before documents enter context.
+
+5. **Prompt quality problems masquerade as degradation**: Poor prompt structure (ambiguous instructions, missing constraints, unclear task framing) produces symptoms identical to context degradation — inconsistent outputs, ignored instructions, wrong tool usage. Before diagnosing degradation, verify the same prompt works correctly at low context lengths. If it fails at 2K tokens, the problem is the prompt, not the context.
+
+6. **Degradation is non-linear with a cliff edge**: Performance does not degrade gradually — it holds steady until a model-specific threshold, then drops sharply. Systems designed for "graceful degradation" often miss this pattern because monitoring checks assume linear decline. Set compaction triggers well before the cliff (at 70% of known onset), not at the onset itself.
+
+7. **Over-organizing context can backfire**: Intuitively, well-structured and coherent context should outperform disorganized content. Research shows shuffled haystacks sometimes outperform coherent ones for retrieval tasks because coherent context creates false associations. Test whether heavy structural formatting actually helps for the specific task — do not assume it does.
+
+## Integration
+
+This skill builds on context-fundamentals and should be studied after understanding basic context concepts. It connects to:
+
+- context-optimization - Techniques for mitigating degradation
+- multi-agent-patterns - Using isolation to prevent degradation
+- evaluation - Measuring and detecting degradation in production
+
+## References
+
+Internal reference:
+- [Degradation Patterns Reference](./references/patterns.md) - Read when: debugging a specific degradation pattern and needing implementation-level detection code (attention analysis, poisoning tracking, relevance scoring, recovery procedures)
+
+Related skills in this collection:
+- context-fundamentals - Read when: lacking foundational understanding of context windows, token budgets, or placement mechanics
+- context-optimization - Read when: degradation is diagnosed and specific mitigation techniques (compaction, compression, masking) are needed
+- evaluation - Read when: setting up production monitoring to detect degradation before it impacts users
+
+External resources:
+- Liu et al., 2023 "Lost in the Middle" - Read when: needing primary research backing for U-shaped attention claims or designing position-aware context layouts
+- RULER benchmark documentation - Read when: evaluating model claims about long-context support or comparing models for context-heavy workloads
+- Production engineering guides from AI labs - Read when: implementing context management in production infrastructure
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/context-fundamentals.md

@@ -0,0 +1,203 @@
+---
+name: context-fundamentals
+description: The foundational context engineering skill — start here when exploring the discipline. This skill should be used when the user asks to "understand context", "explain context windows", "design agent architecture", "debug context issues", "optimize context usage", or discusses context components, attention mechanics, progressive disclosure, or context budgeting. Also activates when the user mentions "context engineering" or "context-engineering" for foundational understanding of AI agent context systems.
+metadata:
+  provider: atomic
+---
+
+# Context Engineering Fundamentals
+
+Context is the complete state available to a language model at inference time — system instructions, tool definitions, retrieved documents, message history, and tool outputs. Context engineering is the discipline of curating the smallest high-signal token set that maximizes the likelihood of desired outcomes. Every paragraph below earns its tokens by teaching a non-obvious technique or providing an actionable threshold.
+
+## When to Activate
+
+Activate this skill when:
+- Designing new agent systems or modifying existing architectures
+- Debugging unexpected agent behavior that may relate to context
+- Optimizing context usage to reduce token costs or improve performance
+- Onboarding new team members to context engineering concepts
+- Reviewing context-related design decisions
+
+## Core Concepts
+
+Treat context as a finite attention budget, not a storage bin. Every token added competes for the model's attention and depletes a budget that cannot be refilled mid-inference. The engineering problem is maximizing utility per token against three constraints: the hard token limit, the softer effective-capacity ceiling (typically 60-70% of the advertised window), and the U-shaped attention curve that penalizes information placed in the middle of context.
+
+Apply four principles when assembling context:
+
+1. **Informativity over exhaustiveness** — include only what matters for the current decision; design systems that can retrieve additional information on demand.
+2. **Position-aware placement** — place critical constraints at the beginning and end of context, where recall accuracy runs 85-95%; the middle drops to 76-82% (the "lost-in-the-middle" effect).
+3. **Progressive disclosure** — load skill names and summaries at startup; load full content only when a skill activates for a specific task.
+4. **Iterative curation** — context engineering is not a one-time prompt-writing exercise but an ongoing discipline applied every time content is passed to the model.
+
+## Detailed Topics
+
+### The Anatomy of Context
+
+**System Prompts**
+Organize system prompts into distinct sections using XML tags or Markdown headers (background, instructions, tool guidance, output format). System prompts persist throughout the conversation, so place the most critical constraints at the beginning and end where attention is strongest.
+
+Calibrate instruction altitude to balance two failure modes. Too-low altitude hardcodes brittle logic that breaks when conditions shift. Too-high altitude provides vague guidance that fails to give concrete signals for desired behavior. Aim for heuristic-driven instructions: specific enough to guide behavior, flexible enough to generalize — for example, numbered steps with room for judgment at each step.
+
+Start minimal, then add instructions reactively based on observed failure modes rather than preemptively stuffing edge cases. Curate diverse, canonical few-shot examples that portray expected behavior instead of listing every possible scenario.
+
+**Tool Definitions**
+Write tool descriptions that answer three questions: what the tool does, when to use it, and what it returns. Include usage context, parameter defaults, and error cases — agents cannot disambiguate tools that a human engineer cannot disambiguate either.
+
+Keep the tool set minimal. Consolidate overlapping tools because bloated tool sets create ambiguous decision points and consume disproportionate context after JSON serialization (tool schemas typically inflate 2-3x compared to equivalent plain-text descriptions).
+
+**Retrieved Documents**
+Maintain lightweight identifiers (file paths, stored queries, web links) and load data into context dynamically using just-in-time retrieval. This mirrors human cognition — maintain an index, not a copy. Strong identifiers (e.g., `customer_pricing_rates.json`) let agents locate relevant files even without search tools; weak identifiers (e.g., `data/file1.json`) force unnecessary loads.
+
+When chunking large documents, split at natural semantic boundaries (section headers, paragraph breaks) rather than arbitrary character limits that sever mid-concept.
+
+**Message History**
+Message history serves as the agent's scratchpad memory for tracking progress, maintaining task state, and preserving reasoning across turns. For long-running tasks, it can grow to dominate context usage — monitor and apply compaction before it crowds out active instructions.
+
+Cyclically refine history: once a tool has been called deep in the conversation, the raw result rarely needs to remain verbatim. Replace stale tool outputs with compact summaries or references to reduce low-signal bulk.
+
+**Tool Outputs**
+Tool outputs typically dominate context — research shows observations can reach 83.9% of total tokens in agent trajectories. Apply observation masking: replace verbose outputs with compact references once the agent has processed the result. Retain only the five most recently accessed file contents; compress or evict older ones.
+
+### Context Windows and Attention Mechanics
+
+**The Attention Budget**
+For n tokens, the attention mechanism computes n-squared pairwise relationships. As context grows, the model's ability to maintain these relationships degrades — not as a hard cliff but as a performance gradient. Models trained predominantly on shorter sequences have fewer specialized parameters for context-wide dependencies, creating an effective ceiling well below the nominal window size.
+
+Design for this gradient: assume effective capacity is 60-70% of the advertised window. A 200K-token model starts degrading around 120-140K tokens, and complex retrieval accuracy can drop to as low as 15% at extreme lengths.
+
+**Position Encoding Limits**
+Position encoding interpolation extends sequence handling beyond training lengths but introduces degradation in positional precision. Expect reduced accuracy for information retrieval and long-range reasoning at extended contexts compared to performance on shorter inputs.
+
+**Progressive Disclosure in Practice**
+Implement progressive disclosure at three levels:
+
+1. **Skill selection** — load only names and descriptions at startup; activate full skill content on demand.
+2. **Document loading** — load summaries first; fetch detail sections only when the task requires them.
+3. **Tool result retention** — keep recent results in full; compress or evict older results.
+
+Keep the boundary crisp: if a skill or document is activated, load it fully rather than partially — partial loads create confusing gaps that degrade reasoning quality.
+
+### Context Quality Versus Quantity
+
+Reject the assumption that larger context windows solve memory problems. Processing cost grows disproportionately with context length — not just linear cost scaling, but degraded model performance beyond effective capacity thresholds. Long inputs remain expensive even with prefix caching.
+
+Apply the signal-density test: for each piece of context, ask whether removing it would change the model's output. If not, remove it. Redundant content does not merely waste tokens — it actively dilutes attention from high-signal content.
+
+## Practical Guidance
+
+### File-System-Based Access
+
+Agents with filesystem access implement progressive disclosure naturally. Store reference materials, documentation, and data externally. Load files only when the current task requires them. Leverage the filesystem's own structure as metadata: file sizes suggest complexity, naming conventions hint at purpose, timestamps serve as proxies for relevance.
+
+### Hybrid Context Strategies
+
+Pre-load stable context for speed (CLAUDE.md files, project rules, core instructions) but enable autonomous exploration for dynamic content. The decision boundary depends on content volatility:
+
+- **Low volatility** (project conventions, team standards): pre-load at session start.
+- **High volatility** (code state, external data, user-specific info): retrieve just-in-time to avoid stale context.
+
+For complex multi-hour tasks, maintain a structured notes file (e.g., NOTES.md) that the agent updates as it works. This enables coherence across context resets without keeping everything in the active window.
+
+### Context Budgeting
+
+Allocate explicit budgets per component and monitor during development. Implement compaction triggers at 70-80% utilization — do not wait for the window to fill. Design systems that degrade gracefully: when compaction fires, preserve architectural decisions, unresolved bugs, and implementation details while discarding redundant outputs.
+
+For sub-agent architectures, enforce a compression ratio: a sub-agent may explore using tens of thousands of tokens but must return a condensed summary of 1,000-2,000 tokens. This converts exploration breadth into context-efficient results.
+
+## Examples
+
+**Example 1: Organizing System Prompts**
+```markdown
+<BACKGROUND_INFORMATION>
+You are a Python expert helping a development team.
+Current project: Data processing pipeline in Python 3.9+
+</BACKGROUND_INFORMATION>
+
+<INSTRUCTIONS>
+- Write clean, idiomatic Python code
+- Include type hints for function signatures
+- Add docstrings for public functions
+- Follow PEP 8 style guidelines
+</INSTRUCTIONS>
+
+<TOOL_GUIDANCE>
+Use bash for shell operations, python for code tasks.
+File operations should use pathlib for cross-platform compatibility.
+</TOOL_GUIDANCE>
+
+<OUTPUT_DESCRIPTION>
+Provide code blocks with syntax highlighting.
+Explain non-obvious decisions in comments.
+</OUTPUT_DESCRIPTION>
+```
+
+**Example 2: Progressive Document Loading**
+```markdown
+# Instead of loading all documentation at once:
+
+# Step 1: Load summary
+docs/api_summary.md          # Lightweight overview
+
+# Step 2: Load specific section as needed
+docs/api/endpoints.md        # Only when API calls needed
+docs/api/authentication.md   # Only when auth context needed
+```
+
+## Guidelines
+
+1. Treat context as a finite resource with diminishing returns
+2. Place critical information at attention-favored positions (beginning and end)
+3. Use progressive disclosure to defer loading until needed
+4. Organize system prompts with clear section boundaries
+5. Monitor context usage during development
+6. Implement compaction triggers at 70-80% utilization
+7. Design for context degradation rather than hoping to avoid it
+8. Prefer smaller high-signal context over larger low-signal context
+
+## Gotchas
+
+1. **Nominal window is not effective capacity**: A model advertising 200K tokens begins degrading around 120-140K. Budget for 60-70% of the nominal window as usable capacity. Exceeding this threshold causes sudden accuracy drops, not gradual degradation — test at realistic context sizes, not toy examples.
+
+2. **Character-based token estimates silently drift**: The ~4 characters/token heuristic for English prose breaks down for code (2-3 chars/token), URLs and file paths (each slash, dot, and colon is a separate token), and non-English text (often 1-2 chars/token). Use the provider's actual tokenizer (e.g., tiktoken for OpenAI models, Anthropic's token counting API) for any budget-critical calculation.
+
+3. **Tool schemas inflate 2-3x after JSON serialization**: A tool definition that looks compact in source code expands significantly when serialized — brackets, quotes, colons, and commas each consume tokens. Ten tools with moderate schemas can consume 5,000-8,000 tokens before a single message is sent. Audit serialized tool token counts, not source-code line counts.
+
+4. **Message history balloons silently in agentic loops**: Each tool call adds both the request and the full response to history. After 20-30 iterations, history can consume 70-80% of the window while the agent shows no visible symptoms until reasoning quality collapses. Set a hard token ceiling on history and trigger compaction proactively.
+
+5. **Critical instructions in the middle get lost**: The U-shaped attention curve means the middle of context receives 10-40% less recall accuracy than the beginning and end. Never place safety constraints, output format requirements, or behavioral guardrails in the middle of a long system prompt — anchor them at the top or bottom.
+
+6. **Progressive disclosure that loads too eagerly defeats its purpose**: Loading every "potentially relevant" skill or document at the first hint of relevance recreates the context-stuffing problem. Set strict activation thresholds — a skill should load only when the task explicitly matches its trigger conditions, not when the topic is merely adjacent.
+
+7. **Mixing instruction altitudes causes inconsistent behavior**: Combining hyper-specific rules ("always use exactly 3 bullet points") with vague directives ("be helpful") in the same prompt creates conflicting signals. Group instructions by altitude level and keep each section internally consistent — either heuristic-driven or prescriptive, not both interleaved.
+
+## Integration
+
+This skill provides foundational context that all other skills build upon. It should be studied first before exploring:
+
+- context-degradation - Understanding how context fails
+- context-optimization - Techniques for extending context capacity
+- multi-agent-patterns - How context isolation enables multi-agent systems
+- tool-design - How tool definitions interact with context
+
+## References
+
+Internal reference:
+- [Context Components Reference](./references/context-components.md) - Read when: debugging a specific context component (system prompts, tool definitions, message history, tool outputs) or implementing chunking, observation masking, or budget allocation tables
+
+Related skills in this collection:
+- context-degradation - Read when: agent performance drops as conversations grow or context fills beyond 60% capacity
+- context-optimization - Read when: token costs are too high or compaction/compression strategies are needed
+
+External resources:
+- Anthropic's "Effective Context Engineering for AI Agents" — production patterns for compaction, sub-agents, and hybrid retrieval
+- Research on transformer attention mechanisms and the lost-in-the-middle effect
+- Tokenomics research on agentic software engineering token distribution
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0

package/dist/builtin/workflows/skills/workflow/references/context-engineering/context-optimization.md

@@ -0,0 +1,197 @@
+---
+name: context-optimization
+description: 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. A core context engineering skill — also activates when the user mentions "context engineering" or "context-engineering" in the context of maximizing information density within token constraints.
+metadata:
+  provider: atomic
+---
+
+# Context Optimization Techniques
+
+Context optimization extends the effective capacity of limited context windows through strategic compression, masking, caching, and partitioning. Effective optimization can double or triple effective context capacity without requiring larger models or longer windows — but only when applied with discipline. The techniques below are ordered by impact and risk.
+
+## When to Activate
+
+Activate this skill when:
+- Context limits constrain task complexity
+- Optimizing for cost reduction (fewer tokens = lower costs)
+- Reducing latency for long conversations
+- Implementing long-running agent systems
+- Needing to handle larger documents or conversations
+- Building production systems at scale
+
+## Core Concepts
+
+Apply four primary strategies in this priority order:
+
+1. **KV-cache optimization** — Reorder and stabilize prompt structure so the inference engine reuses cached Key/Value tensors. This is the cheapest optimization: zero quality risk, immediate cost and latency savings. Apply it first and unconditionally.
+
+2. **Observation masking** — Replace verbose tool outputs with compact references once their purpose has been served. Tool outputs consume 80%+ of tokens in typical agent trajectories, so masking them yields the largest capacity gains. The original content remains retrievable if needed downstream.
+
+3. **Compaction** — Summarize accumulated context when utilization exceeds 70%, then reinitialize with the summary. This distills the window's contents while preserving task-critical state. Compaction is lossy — apply it after masking has already removed the low-value bulk.
+
+4. **Context partitioning** — Split work across sub-agents with isolated contexts when a single window cannot hold the full problem. Each sub-agent operates in a clean context focused on its subtask. Reserve this for tasks where estimated context exceeds 60% of the window limit, because coordination overhead is real.
+
+The governing principle: context quality matters more than quantity. Every optimization preserves signal while reducing noise. Measure before optimizing, then measure the optimization's effect.
+
+## Detailed Topics
+
+### Compaction Strategies
+
+Trigger compaction when context utilization exceeds 70%: summarize the current context, then reinitialize with the summary. This distills the window's contents in a high-fidelity manner, enabling continuation with minimal performance degradation. Prioritize compressing tool outputs first (they consume 80%+ of tokens), then old conversation turns, then retrieved documents. Never compress the system prompt — it anchors model behavior and its removal causes unpredictable degradation.
+
+Preserve different elements by message type:
+
+- **Tool outputs**: Extract key findings, metrics, error codes, and conclusions. Strip verbose raw output, stack traces (unless debugging is ongoing), and boilerplate headers.
+- **Conversational turns**: Retain decisions, commitments, user preferences, and context shifts. Remove filler, pleasantries, and exploratory back-and-forth that led to a conclusion already captured.
+- **Retrieved documents**: Keep claims, facts, and data points relevant to the active task. Remove supporting evidence and elaboration that served a one-time reasoning purpose.
+
+Target 50-70% token reduction with less than 5% quality degradation. If compaction exceeds 70% reduction, audit the summary for critical information loss — over-aggressive compaction is the most common failure mode.
+
+### Observation Masking
+
+Mask observations selectively based on recency and ongoing relevance — not uniformly. Apply these rules:
+
+- **Never mask**: Observations critical to the current task, observations from the most recent turn, observations used in active reasoning chains, and error outputs when debugging is in progress.
+- **Mask after 3+ turns**: Verbose outputs whose key points have already been extracted into the conversation flow. Replace with a compact reference: `[Obs:{ref_id} elided. Key: {summary}. Full content retrievable.]`
+- **Always mask immediately**: Repeated/duplicate outputs, boilerplate headers and footers, outputs already summarized earlier in the conversation.
+
+Masking should achieve 60-80% reduction in masked observations with less than 2% quality impact. The key is maintaining retrievability — store the full content externally and keep the reference ID in context so the agent can request the original if needed.
+
+### KV-Cache Optimization
+
+Maximize prefix cache hits by structuring prompts so that stable content occupies the prefix and dynamic content appears at the end. KV-cache stores Key and Value tensors computed during inference; when consecutive requests share an identical prefix, the cached tensors are reused, saving both cost and latency.
+
+Apply this ordering in every prompt:
+1. System prompt (most stable — never changes within a session)
+2. Tool definitions (stable across requests)
+3. Frequently reused templates and few-shot examples
+4. Conversation history (grows but shares prefix with prior turns)
+5. Current query and dynamic content (least stable — always last)
+
+Design prompts for cache stability: remove timestamps, session counters, and request IDs from the system prompt. Move dynamic metadata into a separate user message or tool result where it does not break the prefix. Even a single whitespace change in the prefix invalidates the entire cached block downstream of that change.
+
+Target 70%+ cache hit rate for stable workloads. At scale, this translates to 50%+ cost reduction and 40%+ latency reduction on cached tokens.
+
+### Context Partitioning
+
+Partition work across sub-agents when a single context cannot hold the full problem without triggering aggressive compaction. Each sub-agent operates in a clean, focused context for its subtask, then returns a structured result to a coordinator agent.
+
+Plan partitioning when estimated task context exceeds 60% of the window limit. Decompose the task into independent subtasks, assign each to a sub-agent, and aggregate results. Validate that all partitions completed before merging, merge compatible results, and apply summarization if the aggregated output still exceeds budget.
+
+This approach achieves separation of concerns — detailed search context stays isolated within sub-agents while the coordinator focuses on synthesis. However, coordination has real token cost: the coordinator prompt, result aggregation, and error handling all consume tokens. Only partition when the savings exceed this overhead.
+
+### Budget Management
+
+Allocate explicit token budgets across context categories before the session begins: system prompt, tool definitions, retrieved documents, message history, tool outputs, and a reserved buffer (5-10% of total). Monitor usage against budget continuously and trigger optimization when any category exceeds its allocation or total utilization crosses 70%.
+
+Use trigger-based optimization rather than periodic optimization. Monitor these signals:
+- Token utilization above 80% — trigger compaction
+- Attention degradation indicators (repetition, missed instructions) — trigger masking + compaction
+- Quality score drops below baseline — audit context composition before optimizing
+
+## Practical Guidance
+
+### Optimization Decision Framework
+
+Select the optimization technique based on what dominates the context:
+
+| Context Composition | First Action | Second Action |
+|---|---|---|
+| Tool outputs dominate (>50%) | Observation masking | Compaction of remaining turns |
+| Retrieved documents dominate | Summarization | Partitioning if docs are independent |
+| Message history dominates | Compaction with selective preservation | Partitioning for new subtasks |
+| Multiple components contribute | KV-cache optimization first, then layer masking + compaction |
+| Near-limit with active debugging | Mask resolved tool outputs only — preserve error details |
+
+### Performance Targets
+
+Track these metrics to validate optimization effectiveness:
+
+- **Compaction**: 50-70% token reduction, <5% quality degradation, <10% latency overhead from the compaction step itself
+- **Masking**: 60-80% reduction in masked observations, <2% quality impact, near-zero latency overhead
+- **Cache optimization**: 70%+ hit rate for stable workloads, 50%+ cost reduction, 40%+ latency reduction
+- **Partitioning**: Net token savings after accounting for coordinator overhead; break-even typically requires 3+ subtasks
+
+Iterate on strategies based on measured results. If an optimization technique does not measurably improve the target metric, remove it — optimization machinery itself consumes tokens and adds latency.
+
+## Examples
+
+**Example 1: Compaction Trigger**
+```python
+if context_tokens / context_limit > 0.8:
+    context = compact_context(context)
+```
+
+**Example 2: Observation Masking**
+```python
+if len(observation) > max_length:
+    ref_id = store_observation(observation)
+    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"
+```
+
+**Example 3: Cache-Friendly Ordering**
+```python
+# Stable content first
+context = [system_prompt, tool_definitions]  # Cacheable
+context += [reused_templates]  # Reusable
+context += [unique_content]  # Unique
+```
+
+## Guidelines
+
+1. Measure before optimizing—know your current state
+2. Apply masking before compaction — remove low-value bulk first, then summarize what remains
+3. Design for cache stability with consistent prompts
+4. Partition before context becomes problematic
+5. Monitor optimization effectiveness over time
+6. Balance token savings against quality preservation
+7. Test optimization at production scale
+8. Implement graceful degradation for edge cases
+
+## Gotchas
+
+1. **Whitespace breaks KV-cache**: Even a single whitespace or newline change in the prompt prefix invalidates the entire KV-cache block downstream of that point. Pin system prompts as immutable strings — do not interpolate timestamps, version numbers, or session IDs into them. Diff prompt templates byte-for-byte between deployments.
+
+2. **Timestamps in system prompts destroy cache hit rates**: Including `Current date: {today}` or similar dynamic content in the system prompt forces a full cache miss on every new day (or every request, if using time-of-day). Move dynamic metadata into a user message or a separate tool result appended after the stable prefix.
+
+3. **Compaction under pressure loses critical state**: When the model performing compaction is itself under context pressure (>85% utilization), its summarization quality degrades — it omits task goals, drops user constraints, and flattens nuanced state. Trigger compaction at 70-80%, not 90%+. If compaction must happen late, use a separate model call with a clean context containing only the material to summarize.
+
+4. **Masking error outputs breaks debugging loops**: Over-aggressive masking hides error messages, stack traces, and failure details that the agent needs in subsequent turns to diagnose and fix issues. During active debugging (error in the last 3 turns), suspend masking for all error-related observations until the issue is resolved.
+
+5. **Partitioning overhead can exceed savings**: Each sub-agent requires its own system prompt, tool definitions, and coordination messages. For tasks with fewer than 3 independent subtasks, the coordination overhead often exceeds the context savings. Estimate total tokens (coordinator + all sub-agents) before committing to partitioning.
+
+6. **Cache miss cost spikes after deployment changes**: Reordering tools, rewording the system prompt, or changing few-shot examples between deployments invalidates the entire prefix cache, causing a temporary cost spike of 2-5x until the new cache warms up. Roll out prompt changes gradually and monitor cache hit rate during deployment windows.
+
+7. **Compaction creates false confidence in stale summaries**: Once context is compacted, the summary looks authoritative but may reflect outdated state. If the task has evolved since compaction (new user requirements, corrected assumptions), the summary silently carries forward stale information. After compaction, re-validate the summary against the current task goal before proceeding.
+
+## Integration
+
+This skill builds on context-fundamentals and context-degradation. It connects to:
+
+- multi-agent-patterns - Partitioning as isolation
+- evaluation - Measuring optimization effectiveness
+- memory-systems - Offloading context to memory
+
+## References
+
+Internal reference:
+- [Optimization Techniques Reference](./references/optimization_techniques.md) - Read when: implementing a specific optimization technique and needing detailed code patterns, threshold tables, or integration examples beyond what the skill body provides
+
+Related skills in this collection:
+- context-fundamentals - Read when: unfamiliar with context window mechanics, token counting, or attention distribution basics
+- context-degradation - Read when: diagnosing why agent performance has dropped and needing to identify which degradation pattern is occurring before selecting an optimization
+- evaluation - Read when: setting up metrics and benchmarks to measure whether an optimization technique actually improved outcomes
+
+External resources:
+- Research on context window limitations - Read when: evaluating model-specific context behavior (e.g., lost-in-the-middle effects, attention decay curves)
+- KV-cache optimization techniques - Read when: implementing prefix caching at the inference infrastructure level (vLLM, TGI, or cloud provider APIs)
+- Production engineering guides - Read when: deploying context optimization in a production pipeline and needing operability patterns (monitoring, alerting, rollback)
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0