Context Engineering
Context engineering is the discipline of systematically selecting, structuring, and delivering the smallest possible set of high-signal tokens that make a task plausibly solvable for an LLM — reliably, safely, and cost-effectively.
This skill provides actionable patterns, checklists, and templates for the full context pipeline — from first principles through production readiness.
When to Use
- Designing context pipelines for AI agents (what enters the LLM context window, in what order)
- Reviewing context quality and token efficiency of existing systems
- Building RAG systems (retrieval pipeline, chunking, packing, grounding)
- Implementing memory (session, working, long-term, organizational, tool-output)
- Designing agent harness (init/continuation prompts, state management, token budgets, caching)
- Multi-agent orchestration (context boundaries, payload schemas, fan-out merge)
- Production readiness assessment for AI systems (8-checklist gate)
- Privacy and compliance for AI features (multi-tenant isolation, consent, data residency)
When NOT to Use
- Prompt technique selection and template patterns → use
prompt-engineering skill
- Security audit of individual prompts → use
prompt-engineering skill → security-checklist.md
- Non-AI software engineering tasks → use
Agent(software-engineer) + stack-specific role
- Infrastructure and deployment → use
Agent(devops-engineer)
Context Engineering vs Prompt Engineering
These are complementary disciplines:
- Prompt engineering = designing the instruction text (technique selection, template patterns, formatting, few-shot)
- Context engineering = designing the full context PIPELINE (what enters the window, in what order, how it's managed across turns, how it degrades gracefully)
Context engineering is the system; prompt engineering is one layer within it.
Key Concepts
First Principles
- Attention is finite — curate, don't stuff. "More context" is not monotonically better
- Position effects — critical info at beginning and end ("lost-in-the-middle"). Models use tokens near the start and end more effectively than those buried in the middle
- High-signal tokens > high-volume tokens — compact, discriminative context beats verbose dumps
- Separation of concerns — policy, knowledge, examples, output contract in distinct layers. Enables independent swap, A/B testing, failure analysis
- Context is a pipeline — produced by a system (retrieval, ranking, summarization, memory, policy filters, schema enforcement), not concatenated strings
The Context Stack (8-Layer Architecture)
Ordered layers, top = highest priority. Higher layers override lower on conflict.
| Layer |
What Goes Here |
Design Notes |
| 1. System policy & safety |
Non-negotiable constraints, content policies, refusal rules |
First in window — highest attention. Cacheable |
| 2. Developer instructions |
Role definitions, hard rules, reasoning protocols, conventions |
Maps to: Claude Code rules ((auto-loaded), (agent)) |
| 3. Tool contracts |
Schemas, descriptions, permissions, failure modes, retry policies |
Tool descriptions ARE prompts — optimize them |
| 4. Runtime state |
Current project context, CLAUDE.md, active file, task state, structured state blob |
Maps to: Claude Code CLAUDE.md files |
| 5. Knowledge context (RAG) |
Retrieved documents, search results, file contents |
Must be wrapped as untrusted data with grounding envelopes |
| 6. Memory |
Session, working, long-term, organizational, tool-output |
Must be scoped, filtered, and conflict-resolved |
| 7. Examples (few-shot) |
Minimal, high-leverage exemplars aligned to output contract |
Dynamic selection preferred; skip if schema suffices |
| 8. Output contract |
JSON Schema, format instructions, constraints, error handling |
End of context — recency bias helps compliance |
Rule: keep policy/instructions (Layers 1-2) separate from knowledge (Layer 5). Mixing them is a root cause of prompt injection and "obedience confusion."
→ Full reference: context-stack-model.md
Cacheable Prefix Design
Layers 1-3 rarely change → group all static content at the beginning of the prompt to enable KV cache reuse. Append dynamic content (Layer 4-8) at the end. Never interleave static and dynamic blocks.
Track cache_prefix_ratio = cached_tokens / total_input_tokens (target > 0.3).
Token Budget Allocation
Treat context window as a finite resource with explicit budget per layer:
| Allocation |
Suggested % |
Notes |
| System + rules + tools (L1-3) |
15-25% |
Stable, cacheable prefix |
| Runtime state (L4) |
5-10% |
Structured state blob |
| Knowledge / RAG (L5) |
30-40% |
Dynamic, highest signal variance |
| Memory (L6) |
10-15% |
Filtered, relevance-ranked |
| Examples (L7) |
0-10% |
Only when needed |
| Output contract (L8) |
5-10% |
Schema + error handling |
Overflow strategy: truncate lowest-priority layers first (L7 → L6 → L5).
Resource Files
| File |
Contents |
Guide §§ |
context-stack-model.md |
8-layer architecture, layer design patterns, position effects, mapping to Claude Code assets |
§3 |
memory-engineering.md |
Memory taxonomy, CRUD lifecycle, conflict handling, compression strategies |
§6 |
agent-harness-patterns.md |
Init/continuation, state blobs, token budgets, caching, failure modes, streaming |
§7 |
rag-engineering.md |
Pipeline blueprint (7 stages), chunking, packing, degradation signals |
§5 |
multi-agent-patterns.md |
Context boundaries, payload schemas, return contracts, fan-out, contamination |
§7.6, §14 |
production-checklists.md |
All 8 production readiness checklists |
§11 |
reference-templates.md |
Grounding envelope, untrusted wrapper, structured output, tool error envelope |
§12 |
privacy-compliance-ai.md |
Multi-tenant isolation, data controls, consent, regional compliance |
§9 |
Integration
- Follows rules:
Agent(prompt-engineer) (prompt-level techniques, security, eval-first quality)
- Used by workflows:
/plugin-doctor (context-engineering checks during plugin self-diagnostic), /develop and /feature-dev (AI/LLM features), /feature-design (Wave-2 review for AI/LLM systems), /plan (AI work packages), /code-review (context quality review)
- Companion skill:
prompt-engineering skill (technique selection, template patterns, eval, security checklist)
- Collaborates with roles:
Agent(solution-architect) (AI system design), Agent(product-manager) (agent contracts), Agent(sre-engineer) (context observability), Agent(software-engineer) (implementation)
1---2name: context-engineering3description: Use this skill when designing AI agent systems or RAG pipelines that need a principled approach to selecting, structuring, and delivering context to LLMs — the context engineering knowledge base covering the context stack model, RAG pipeline design, memory engineering, and multi-agent context coordination.4---56# Context Engineering78Context engineering is the discipline of **systematically selecting, structuring, and delivering the smallest possible set of high-signal tokens** that make a task plausibly solvable for an LLM — reliably, safely, and cost-effectively.910This skill provides actionable patterns, checklists, and templates for the full context pipeline — from first principles through production readiness.1112## When to Use1314- Designing context pipelines for AI agents (what enters the LLM context window, in what order)15- Reviewing context quality and token efficiency of existing systems16- Building RAG systems (retrieval pipeline, chunking, packing, grounding)17- Implementing memory (session, working, long-term, organizational, tool-output)18- Designing agent harness (init/continuation prompts, state management, token budgets, caching)19- Multi-agent orchestration (context boundaries, payload schemas, fan-out merge)20- Production readiness assessment for AI systems (8-checklist gate)21- Privacy and compliance for AI features (multi-tenant isolation, consent, data residency)2223## When NOT to Use2425- Prompt technique selection and template patterns → use `prompt-engineering` skill26- Security audit of individual prompts → use `prompt-engineering` skill → `security-checklist.md`27- Non-AI software engineering tasks → use `Agent(software-engineer)` + stack-specific role28- Infrastructure and deployment → use `Agent(devops-engineer)`2930## Context Engineering vs Prompt Engineering3132These are **complementary** disciplines:3334- **Prompt engineering** = designing the instruction text (technique selection, template patterns, formatting, few-shot)35- **Context engineering** = designing the full context PIPELINE (what enters the window, in what order, how it's managed across turns, how it degrades gracefully)3637Context engineering is the **system**; prompt engineering is one **layer** within it.3839## Key Concepts4041### First Principles42431. **Attention is finite** — curate, don't stuff. "More context" is not monotonically better442. **Position effects** — critical info at beginning and end ("lost-in-the-middle"). Models use tokens near the start and end more effectively than those buried in the middle453. **High-signal tokens > high-volume tokens** — compact, discriminative context beats verbose dumps464. **Separation of concerns** — policy, knowledge, examples, output contract in distinct layers. Enables independent swap, A/B testing, failure analysis475. **Context is a pipeline** — produced by a system (retrieval, ranking, summarization, memory, policy filters, schema enforcement), not concatenated strings4849### The Context Stack (8-Layer Architecture)5051Ordered layers, top = highest priority. Higher layers override lower on conflict.5253| Layer | What Goes Here | Design Notes |54|---|---|---|55| 1. System policy & safety | Non-negotiable constraints, content policies, refusal rules | First in window — highest attention. Cacheable |56| 2. Developer instructions | Role definitions, hard rules, reasoning protocols, conventions | Maps to: Claude Code rules ((auto-loaded), (agent)) |57| 3. Tool contracts | Schemas, descriptions, permissions, failure modes, retry policies | Tool descriptions ARE prompts — optimize them |58| 4. Runtime state | Current project context, CLAUDE.md, active file, task state, structured state blob | Maps to: Claude Code CLAUDE.md files |59| 5. Knowledge context (RAG) | Retrieved documents, search results, file contents | Must be wrapped as untrusted data with grounding envelopes |60| 6. Memory | Session, working, long-term, organizational, tool-output | Must be scoped, filtered, and conflict-resolved |61| 7. Examples (few-shot) | Minimal, high-leverage exemplars aligned to output contract | Dynamic selection preferred; skip if schema suffices |62| 8. Output contract | JSON Schema, format instructions, constraints, error handling | End of context — recency bias helps compliance |6364**Rule**: keep **policy/instructions** (Layers 1-2) separate from **knowledge** (Layer 5). Mixing them is a root cause of prompt injection and "obedience confusion."6566→ Full reference: `context-stack-model.md`6768### Cacheable Prefix Design6970Layers 1-3 rarely change → group all static content at the beginning of the prompt to enable KV cache reuse. Append dynamic content (Layer 4-8) at the end. Never interleave static and dynamic blocks.7172Track `cache_prefix_ratio = cached_tokens / total_input_tokens` (target > 0.3).7374### Token Budget Allocation7576Treat context window as a finite resource with explicit budget per layer:7778| Allocation | Suggested % | Notes |79|---|---|---|80| System + rules + tools (L1-3) | 15-25% | Stable, cacheable prefix |81| Runtime state (L4) | 5-10% | Structured state blob |82| Knowledge / RAG (L5) | 30-40% | Dynamic, highest signal variance |83| Memory (L6) | 10-15% | Filtered, relevance-ranked |84| Examples (L7) | 0-10% | Only when needed |85| Output contract (L8) | 5-10% | Schema + error handling |8687Overflow strategy: truncate lowest-priority layers first (L7 → L6 → L5).8889## Resource Files9091| File | Contents | Guide §§ |92|---|---|---|93| `context-stack-model.md` | 8-layer architecture, layer design patterns, position effects, mapping to Claude Code assets | §3 |94| `memory-engineering.md` | Memory taxonomy, CRUD lifecycle, conflict handling, compression strategies | §6 |95| `agent-harness-patterns.md` | Init/continuation, state blobs, token budgets, caching, failure modes, streaming | §7 |96| `rag-engineering.md` | Pipeline blueprint (7 stages), chunking, packing, degradation signals | §5 |97| `multi-agent-patterns.md` | Context boundaries, payload schemas, return contracts, fan-out, contamination | §7.6, §14 |98| `production-checklists.md` | All 8 production readiness checklists | §11 |99| `reference-templates.md` | Grounding envelope, untrusted wrapper, structured output, tool error envelope | §12 |100| `privacy-compliance-ai.md` | Multi-tenant isolation, data controls, consent, regional compliance | §9 |101102## Integration103104- **Follows rules**: `Agent(prompt-engineer)` (prompt-level techniques, security, eval-first quality)105- **Used by workflows**: `/plugin-doctor` (context-engineering checks during plugin self-diagnostic), `/develop` and `/feature-dev` (AI/LLM features), `/feature-design` (Wave-2 review for AI/LLM systems), `/plan` (AI work packages), `/code-review` (context quality review)106- **Companion skill**: `prompt-engineering` skill (technique selection, template patterns, eval, security checklist)107- **Collaborates with roles**: `Agent(solution-architect)` (AI system design), `Agent(product-manager)` (agent contracts), `Agent(sre-engineer)` (context observability), `Agent(software-engineer)` (implementation)
avav25