ai-context-engineer

---
name: ai-context-engineer
description: |
  Guides context engineering for LLM systems—assembling prompts, budgeting tokens, prioritizing
  sources, compressing history, caching, structured context blocks, and debugging context-related
  failures (lost instructions, overflow, distraction).
  Use when designing what enters the model context each turn, optimizing cost/latency via context
  strategy, building context pipelines for agents, implementing summarization or compaction, or
  fixing "model ignored X" issues—not for persistent memory store design (ai-memory-developer),
  full RAG index pipelines (ai-engineer), or AI org operations (ai-lead-ops). For a structured
  token/cost improvement roadmap with phased initiatives and KPIs, use
  ai-token-improvement-plan-engineer. For commercial/enterprise AI solution architecture (RAG, copilots,
  platform selection), use applied-ai-architect-commercial-enterprise. Token research and
  compression ablations: research-engineer-scientist-tokens.
---

# AI Context Engineer

## When to Use

- Designing what enters the model context each turn
- Optimizing cost/latency via context strategy and token budgeting
- Building context pipelines for agents (prefix, retrieval, history, user input)
- Implementing summarization, compaction, or rolling history
- Debugging context-related failures (lost instructions, overflow, distraction, ignored constraints)
- Choosing delimiters, XML blocks, or structured context formats

## When NOT to Use

- Persistent memory store design or long-term recall architecture → `ai-memory-developer`
- Full RAG ingest/chunk/embed/index pipelines → `ai-engineer`
- AI org operations, release governance, or SLOs → `ai-lead-ops`
- Structured token/cost improvement roadmaps with phased KPIs → `ai-token-improvement-plan-engineer`
- Commercial/enterprise AI solution architecture → `applied-ai-architect-commercial-enterprise`

## Related skills

| Need | Skill |
|---|---|
| Memory stores and long-term recall | `ai-memory-developer` |
| RAG ingest/chunk/embed | `ai-engineer` |
| System and tool prompts | `prompt-engineer` |
| Red-team injection via context | `ai-redteam` |
| Cost and production SLAs | `ai-lead-ops` |
| Token reduction program and roadmap | `ai-token-improvement-plan-engineer` |
| Commercial/enterprise AI architecture | `applied-ai-architect-commercial-enterprise` |
| Token efficiency research and ablations | `research-engineer-scientist-tokens` |

## Core Workflows

### 1. Context budget and layout

**Allocate tokens (example 128k window):**

| Block | Budget % | Priority |
|---|---|---|
| System policy + tools | 15–25% | Fixed, never truncated |
| Retrieved docs / memory | 30–45% | High, reranked |
| Conversation history | 25–40% | Compress oldest first |
| User current message | 5–10% | Never drop |

Use explicit XML/markdown sections: `<policy>`, `<tools>`, `<context>`, `<history>`, `<user>`.

**See `references/context_layout.md` for templates and delimiter rules.**

### 2. History management

| Strategy | When |
|---|---|
| Full recent window | Short chats, high-stakes instructions in last N turns |
| Rolling summary | Long sessions; summarize every K turns |
| Anchor messages | Pin system + key user constraints; summarize middle |
| Structured state | Replace chat with JSON task state for agents |

Preserve: user goals, constraints, unresolved tool errors, pending confirmations.

**See `references/history_compression.md` for summarization prompts and pitfalls.**

### 3. Retrieval into context

1. Query from user message + state summary
2. Retrieve candidates (RAG chunks, memories, tool outputs)
3. Deduplicate overlapping passages
4. Order by relevance; add source labels
5. Truncate with sentence boundaries; show "[truncated]" when cut

**See `references/retrieval_packing.md` for packing algorithms and citation format.**

### 4. Caching and prefetch

- Cache stable prefix (system + tools) where provider supports prompt caching
- Prefetch retrieval while user types (optional)
- Invalidate cache on prompt version change

**See `references/caching_prefetch.md` for provider notes and invalidation.**

### 5. Debug context failures

| Symptom | Likely cause | Fix |
|---|---|---|
| Ignored instruction | Buried in middle / summarized away | Move to system or last user turn |
| Hallucinated doc | Weak retrieval | Raise threshold; require citation |
| Overflow error | No budget enforcement | Pre-flight token count; compress |
| Tool confusion | Ambiguous schemas in context | Separate tool block; shorten descriptions |

Log token counts per block in dev/staging.

**See `references/debugging_context.md` for instrumentation checklist.**

## When to load references

- **Layout and budgets** → `references/context_layout.md`
- **Summarization** → `references/history_compression.md`
- **RAG/memory packing** → `references/retrieval_packing.md`
- **Caching** → `references/caching_prefetch.md`
- **Debugging** → `references/debugging_context.md`

• SKILL.md 5 KB
• references/caching_prefetch.md 1 KB
• references/context_layout.md 1 KB
• references/debugging_context.md 1 KB
• references/history_compression.md 1 KB
• references/retrieval_packing.md 1 KB