Master Context Engineering for AI Agents

This skill covers 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 - and understanding its anatomy is prerequisite to effective context engineering.

It breaks down the anatomy of context into five components. System prompts establish the agent's core identity, constraints, and behavioral guidelines, loaded once at session start; they should sit at the right "altitude," balancing brittle hardcoded logic against vague high-level guidance that gives no concrete signal, and are best organized into distinct sections (background, instructions, tool guidance, output description) via XML tags or Markdown headers. Tool definitions specify available actions with name/description/parameters/return format; poor descriptions force agents to guess, and the consolidation principle holds that if a human engineer can't say which tool applies in a situation, an agent can't either. Retrieved documents provide domain knowledge via retrieval-augmented generation, ideally loaded just-in-time using lightweight identifiers (file paths, queries, links) rather than pre-loading everything, mirroring how humans use external indexing rather than memorizing entire corpuses. Message history holds the conversation and serves as scratchpad memory for tracking progress and reasoning across turns, and can dominate context usage in long-running tasks. Tool outputs - file contents, search results, command output, API responses - typically comprise the majority of tokens in agent trajectories, with research showing they can reach 83.9% of total context usage, creating pressure for strategies like observation masking, compaction, and selective retention.

It explains attention mechanics: language models compute pairwise relationships across all n tokens (n-squared relationships), so as context grows, the model's ability to capture those relationships stretches thin - an "attention budget" that depletes as context grows, worsened by the fact that training data skews toward shorter sequences, giving models less specialized capacity for context-wide dependencies. Position encoding interpolation lets models handle longer sequences than they were trained on, but introduces degradation in token-position understanding, reducing precision for retrieval and long-range reasoning at longer contexts even when the window technically supports more tokens.

It describes progressive disclosure - loading only skill names/descriptions at startup and full content only when a skill activates - as the core technique for managing the attention budget, applicable at the level of skill selection, document loading, and tool result retrieval. It argues the assumption that larger context windows solve memory problems has been empirically debunked: context engineering means finding the smallest set of high-signal tokens that maximizes desired outcomes, since processing cost grows disproportionately with context length and model performance degrades beyond certain lengths regardless of the window's technical capacity - the guiding principle is informativity over exhaustiveness.

Its practical guidance covers file-system-based access (storing reference materials externally and loading only when needed, using file size/naming/timestamps as natural signals of complexity and relevance), hybrid strategies (pre-loading stable context like CLAUDE.md for speed while allowing autonomous exploration for dynamic or specific information), and context budgeting (knowing the effective context limit for the model and task, monitoring usage during development, implementing compaction triggers at 70-80% utilization, and placing critical information at attention-favored positions - the beginning and end of context receive more attention than the middle).

<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>

Use 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, or reviewing context-related design decisions.

This skill is foundational and should be studied before the related context-degradation, context-optimization, multi-agent-patterns, and tool-design skills in the same collection.

Inputs: an agent system design or an existing agent's context usage to review or debug.

Outputs: a curated context design - organized system prompts, just-in-time retrieval strategy, progressive disclosure plan, and a context budget with compaction triggers - favoring the smallest high-signal token set over exhaustive pre-loading.

Related skills in the same collection: context-degradation, context-optimization, multi-agent-patterns, tool-design.

Agent-system engineers who need foundational context engineering concepts - the anatomy of context, attention budget constraints, and progressive disclosure - before designing or debugging context-heavy agent systems.