Context Engineering
When to Use
Trigger phrases:
"context engineering"
"Design and manage the context window for AI coding agents"
When setting up AI agent instructions for a project
When optimizing agent performance on large codebases
When managing context window limits for complex tasks
When designing multi-agent systems with shared context
When NOT to Use
- For simple one-off prompts
- When the codebase fits entirely in context
Overview
Context Engineering is the practice of designing what information an AI agent sees and in what order. The right context produces correct output; the wrong context produces hallucinations.
Workflow
- Map information needs - What does the agent need to know?
- Prioritize - Critical context first, nice-to-have last
- Structure - AGENTS.md, .cursor/rules/, system prompts
- Manage loading - Progressive disclosure, lazy loading
- Optimize tokens - Compress, deduplicate, summarize
- Test - Does the agent produce correct output with this context?
Anti-Rationalization Table
| Rationalization |
Reality |
| "More context is always better" |
Context window has limits. Noise degrades signal. Prioritize ruthlessly. |
| "The agent will figure it out" |
Without explicit context, agents hallucinate patterns and APIs |
| "README is enough" |
Agents need different context than humans - code structure, conventions, gotchas |
Context Architecture
# AGENTS.md (loaded first, always)
- Project overview (2-3 sentences)
- Key commands (test, build, lint)
- File structure map
- Coding conventions
- Known gotchas
# System prompt (agent-specific)
- Role definition
- Quality gates
- Anti-rationalization rules
Process
- Prepare — Gather requirements, verify prerequisites, set up environment
- Execute — Run context engineering workflow with configured parameters
- Verify — Validate output meets requirements, document results
Verification
Code Examples
Python — Token Counting
import tiktoken
def count_tokens(text: str, model: str = "gpt-4") -> int:
"""Count tokens for a given text and model."""
try:
encoding = tiktoken.encoding_for_model(model)
except KeyError:
encoding = tiktoken.get_encoding("cl100k_base")
return len(encoding.encode(text))
def truncate_to_limit(text: str, max_tokens: int, model: str = "gpt-4") -> str:
"""Truncate text to fit within token limit, preserving complete tokens."""
encoding = tiktoken.encoding_for_model(model)
tokens = encoding.encode(text)
if len(tokens) <= max_tokens:
return text
return encoding.decode(tokens[:max_tokens])
# Usage
prompt = "You are a senior engineer. Follow these rules..."
print(count_tokens(prompt)) # ~11 tokens
truncated = truncate_to_limit(prompt * 50, 200)
Python — Context Window Manager with Priority Eviction
class ContextManager:
"""Manages context window with priority-based eviction.
Highest-priority content survives when the total exceeds max_tokens.
"""
def __init__(self, max_tokens: int = 8000, model: str = "gpt-4"):
self.max_tokens = max_tokens
self.sections: list[dict] = []
self._encoding = tiktoken.get_encoding("cl100k_base")
def add(self, content: str, priority: int = 5):
tokens = len(self._encoding.encode(content))
self.sections.append({
"content": content,
"priority": priority,
"tokens": tokens,
})
self._evict()
def _evict(self):
total = sum(s["tokens"] for s in self.sections)
if total <= self.max_tokens:
return
self.sections.sort(key=lambda s: s["priority"])
while total > self.max_tokens and self.sections:
removed = self.sections.pop(0)
total -= removed["tokens"]
def build(self) -> str:
"""Assemble context string, highest priority first."""
ordered = sorted(self.sections, key=lambda s: (-s["priority"], s["tokens"]))
return "\n\n---\n\n".join(s["content"] for s in ordered)
# Usage
ctx = ContextManager(max_tokens=4000)
ctx.add("Project overview and architecture decisions", priority=10)
ctx.add("Full API reference with all endpoints", priority=5)
ctx.add("Historical changelog and edge cases", priority=1)
agent_prompt = ctx.build()
Node.js — Token Counting
import { encoding_for_model } from "tiktoken";
function countTokens(text, model = "gpt-4") {
const enc = encoding_for_model(model);
const count = enc.encode(text).length;
enc.free(); // tiktoken requires explicit free
return count;
}
function truncateToLimit(text, maxTokens, model = "gpt-4") {
const enc = encoding_for_model(model);
const tokens = enc.encode(text);
if (tokens.length <= maxTokens) {
enc.free();
return text;
}
const result = enc.decode(tokens.slice(0, maxTokens));
enc.free();
return result;
}
Node.js — Progressive Context Loader
import { readFileSync } from "fs";
import { encoding_for_model } from "tiktoken";
class ProgressiveContext {
constructor(maxTokens = 8000, model = "gpt-4") {
this.maxTokens = maxTokens;
this.enc = encoding_for_model(model);
this.sections = [];
}
add(name, content, priority = 5) {
const tokens = this.enc.encode(content).length;
this.sections.push({ name, content, priority, tokens });
this.sections.sort((a, b) => b.priority - a.priority);
}
/** Build prompt fitting within maxTokens, highest priority first */
compile(separator = "\n\n---\n\n") {
let result = "";
for (const s of this.sections) {
const candidate = result ? result + separator + s.content : s.content;
if (this.enc.encode(candidate).length > this.maxTokens) break;
result = candidate;
}
return result;
}
cleanup() {
this.enc.free();
}
}
// Usage
const ctx = new ProgressiveContext(6000);
ctx.add("rules", readFileSync("AGENTS.md", "utf-8"), 10);
ctx.add("types", readFileSync("types.d.ts", "utf-8"), 7);
ctx.add("docs", readFileSync("README.md", "utf-8"), 3);
const prompt = ctx.compile();
ctx.cleanup();
Setup & Configuration
# Python — install tokenizer
pip install tiktoken
# Node.js — install tokenizer
npm install tiktoken
# lighter alternative with no WASM dependency
npm install gpt-tokenizer
# Verify installation works
python -c "import tiktoken; print(tiktoken.get_encoding('cl100k_base').encode('hello'))"
Common Issues & Troubleshooting
| Problem |
Solution |
| Context window exceeded mid-task |
Break task into subtasks; use progressive disclosure; summarize intermediate results before continuing |
| Agent ignores instructions at end of prompt |
Place critical instructions first (primacy effect); use AGENTS.md loaded at session start |
| Token count differs between environments |
Use the same tokenizer library (tiktoken) everywhere; always specify the exact model name |
| File loading order affects output quality |
Load critical-path files first; use dependency ordering, not alphabetical |
| Multi-turn context drift over long sessions |
Re-inject core instructions every N turns (summary + system prompt re-insertion pattern) |
| Agent hallucinates file paths or APIs |
Include an explicit file tree map and API surface summary in the context block |
Monetization
- Context audit consulting — Charge $500-2000 per engagement to audit and optimize context setups for teams using AI coding agents. Identify wasted tokens, structural gaps, and priority misalignments across their AGENTS.md, rules files, and system prompts.
- Template marketplace — Sell project-specific context templates ($20-100 each) for popular stacks (Next.js, Django, FastAPI, Rails, Spring Boot) with pre-optimized token budgets, priority ordering, and file structure maps.
- Training workshops — Run 2-day remote workshops ($3000-8000) covering token economics, progressive disclosure design, multi-agent context sharing, CI-based context validation, and debugging session drift.
- CI context validation SaaS — Build a service that checks PRs for context health: token budgets, stale references, duplicate sections, priority inversions, and missing critical paths. $10-50/month per repo.
- Internal tooling development — Build custom context management tooling for enterprise teams: token budget dashboards, auto-summarization pipelines that compress verbose docs into agent-optimal chunks, and collaborative context editors with diff/review workflows.
1---2name: context-engineering3description: Use when design and manage the context window for AI coding agents. Structure4 prompts, manage file loading, and optimize token usage for maximum agent effectiveness.5 Use when designing and manage the context window for ai coding agents.6domain: development7author: oyi778license: Apache-2.09subdomain: software-development10tags:11- engineering12- context13- prompts14- ai-agents15- token-optimization16version: 1.0.017category: development18metadata:19 source: https://skillmd.com/skills/oyi77/context-engineering20---212223# Context Engineering2425## When to Use26**Trigger phrases:**27- "context engineering"28- "Design and manage the context window for AI coding agents"293031- When setting up AI agent instructions for a project32- When optimizing agent performance on large codebases33- When managing context window limits for complex tasks34- When designing multi-agent systems with shared context3536## When NOT to Use3738- For simple one-off prompts39- When the codebase fits entirely in context4041## Overview4243Context Engineering is the practice of designing what information an AI agent sees and in what order. The right context produces correct output; the wrong context produces hallucinations.4445## Workflow46471. **Map information needs** - What does the agent need to know?482. **Prioritize** - Critical context first, nice-to-have last493. **Structure** - AGENTS.md, .cursor/rules/, system prompts504. **Manage loading** - Progressive disclosure, lazy loading515. **Optimize tokens** - Compress, deduplicate, summarize526. **Test** - Does the agent produce correct output with this context?5354## Anti-Rationalization Table5556| Rationalization | Reality |57|---|---|58| "More context is always better" | Context window has limits. Noise degrades signal. Prioritize ruthlessly. |59| "The agent will figure it out" | Without explicit context, agents hallucinate patterns and APIs |60| "README is enough" | Agents need different context than humans - code structure, conventions, gotchas |6162## Context Architecture6364```markdown65# AGENTS.md (loaded first, always)66- Project overview (2-3 sentences)67- Key commands (test, build, lint)68- File structure map69- Coding conventions70- Known gotchas7172# System prompt (agent-specific)73- Role definition74- Quality gates75- Anti-rationalization rules76```777879## Process80811. **Prepare** — Gather requirements, verify prerequisites, set up environment821. **Execute** — Run context engineering workflow with configured parameters831. **Verify** — Validate output meets requirements, document results8485## Verification8687- [ ] AGENTS.md is under 500 lines88- [ ] Key commands are copy-pasteable89- [ ] File structure map is accurate90- [ ] No redundant information across context files91- [ ] Agent produces correct output with this context9293## Code Examples9495### Python — Token Counting9697```python98import tiktoken99100def count_tokens(text: str, model: str = "gpt-4") -> int:101 """Count tokens for a given text and model."""102 try:103 encoding = tiktoken.encoding_for_model(model)104 except KeyError:105 encoding = tiktoken.get_encoding("cl100k_base")106 return len(encoding.encode(text))107108109def truncate_to_limit(text: str, max_tokens: int, model: str = "gpt-4") -> str:110 """Truncate text to fit within token limit, preserving complete tokens."""111 encoding = tiktoken.encoding_for_model(model)112 tokens = encoding.encode(text)113 if len(tokens) <= max_tokens:114 return text115 return encoding.decode(tokens[:max_tokens])116117118# Usage119prompt = "You are a senior engineer. Follow these rules..."120print(count_tokens(prompt)) # ~11 tokens121truncated = truncate_to_limit(prompt * 50, 200)122```123124### Python — Context Window Manager with Priority Eviction125126```python127class ContextManager:128 """Manages context window with priority-based eviction.129 130 Highest-priority content survives when the total exceeds max_tokens.131 """132 133 def __init__(self, max_tokens: int = 8000, model: str = "gpt-4"):134 self.max_tokens = max_tokens135 self.sections: list[dict] = []136 self._encoding = tiktoken.get_encoding("cl100k_base")137 138 def add(self, content: str, priority: int = 5):139 tokens = len(self._encoding.encode(content))140 self.sections.append({141 "content": content,142 "priority": priority,143 "tokens": tokens,144 })145 self._evict()146 147 def _evict(self):148 total = sum(s["tokens"] for s in self.sections)149 if total <= self.max_tokens:150 return151 self.sections.sort(key=lambda s: s["priority"])152 while total > self.max_tokens and self.sections:153 removed = self.sections.pop(0)154 total -= removed["tokens"]155 156 def build(self) -> str:157 """Assemble context string, highest priority first."""158 ordered = sorted(self.sections, key=lambda s: (-s["priority"], s["tokens"]))159 return "\n\n---\n\n".join(s["content"] for s in ordered)160161162# Usage163ctx = ContextManager(max_tokens=4000)164ctx.add("Project overview and architecture decisions", priority=10)165ctx.add("Full API reference with all endpoints", priority=5)166ctx.add("Historical changelog and edge cases", priority=1)167agent_prompt = ctx.build()168```169170### Node.js — Token Counting171172```javascript173import { encoding_for_model } from "tiktoken";174175function countTokens(text, model = "gpt-4") {176 const enc = encoding_for_model(model);177 const count = enc.encode(text).length;178 enc.free(); // tiktoken requires explicit free179 return count;180}181182function truncateToLimit(text, maxTokens, model = "gpt-4") {183 const enc = encoding_for_model(model);184 const tokens = enc.encode(text);185 if (tokens.length <= maxTokens) {186 enc.free();187 return text;188 }189 const result = enc.decode(tokens.slice(0, maxTokens));190 enc.free();191 return result;192}193```194195### Node.js — Progressive Context Loader196197```javascript198import { readFileSync } from "fs";199import { encoding_for_model } from "tiktoken";200201class ProgressiveContext {202 constructor(maxTokens = 8000, model = "gpt-4") {203 this.maxTokens = maxTokens;204 this.enc = encoding_for_model(model);205 this.sections = [];206 }207208 add(name, content, priority = 5) {209 const tokens = this.enc.encode(content).length;210 this.sections.push({ name, content, priority, tokens });211 this.sections.sort((a, b) => b.priority - a.priority);212 }213214 /** Build prompt fitting within maxTokens, highest priority first */215 compile(separator = "\n\n---\n\n") {216 let result = "";217 for (const s of this.sections) {218 const candidate = result ? result + separator + s.content : s.content;219 if (this.enc.encode(candidate).length > this.maxTokens) break;220 result = candidate;221 }222 return result;223 }224225 cleanup() {226 this.enc.free();227 }228}229230// Usage231const ctx = new ProgressiveContext(6000);232ctx.add("rules", readFileSync("AGENTS.md", "utf-8"), 10);233ctx.add("types", readFileSync("types.d.ts", "utf-8"), 7);234ctx.add("docs", readFileSync("README.md", "utf-8"), 3);235const prompt = ctx.compile();236ctx.cleanup();237```238239## Setup & Configuration240241```bash242# Python — install tokenizer243pip install tiktoken244245# Node.js — install tokenizer246npm install tiktoken247# lighter alternative with no WASM dependency248npm install gpt-tokenizer249250# Verify installation works251python -c "import tiktoken; print(tiktoken.get_encoding('cl100k_base').encode('hello'))"252```253254## Common Issues & Troubleshooting255256| Problem | Solution |257|---|---|258| Context window exceeded mid-task | Break task into subtasks; use progressive disclosure; summarize intermediate results before continuing |259| Agent ignores instructions at end of prompt | Place critical instructions first (primacy effect); use AGENTS.md loaded at session start |260| Token count differs between environments | Use the same tokenizer library (tiktoken) everywhere; always specify the exact model name |261| File loading order affects output quality | Load critical-path files first; use dependency ordering, not alphabetical |262| Multi-turn context drift over long sessions | Re-inject core instructions every N turns (summary + system prompt re-insertion pattern) |263| Agent hallucinates file paths or APIs | Include an explicit file tree map and API surface summary in the context block |264265## Monetization266267- **Context audit consulting** — Charge $500-2000 per engagement to audit and optimize context setups for teams using AI coding agents. Identify wasted tokens, structural gaps, and priority misalignments across their AGENTS.md, rules files, and system prompts.268- **Template marketplace** — Sell project-specific context templates ($20-100 each) for popular stacks (Next.js, Django, FastAPI, Rails, Spring Boot) with pre-optimized token budgets, priority ordering, and file structure maps.269- **Training workshops** — Run 2-day remote workshops ($3000-8000) covering token economics, progressive disclosure design, multi-agent context sharing, CI-based context validation, and debugging session drift.270- **CI context validation SaaS** — Build a service that checks PRs for context health: token budgets, stale references, duplicate sections, priority inversions, and missing critical paths. $10-50/month per repo.271- **Internal tooling development** — Build custom context management tooling for enterprise teams: token budget dashboards, auto-summarization pipelines that compress verbose docs into agent-optimal chunks, and collaborative context editors with diff/review workflows.272