Context Engineering

Context Engineering

Based on ETH Zurich research: overly detailed instructions reduce task success by 3%, increase token cost by 20%, and add 2-4 reasoning steps.

When to Use

• Writing SKILL.md, AGENTS.md, or system prompts
• Debugging poor agent performance
• Optimizing token costs
• Designing multi-agent workflows
• Reducing context window pressure

Context Hierarchy (5 Levels)

Most persistent → most transient:

| Level | Content | Persistence | Example | |-------|---------|-------------|---------| | 1. Rules | Project-wide standards | Always loaded | CLAUDE.md, AGENTS.md | | 2. Spec | Feature/session scope | Per feature | PRD, architecture docs | | 3. Source | Per task | Per task | Relevant source files | | 4. Errors | Per iteration | Per attempt | Test failures, stack traces | | 5. History | Accumulates | Session | Conversation history |

Principle: Levels 1-2 are curated (high leverage). Levels 3-5 are per-call (keep minimal).

What to Include

Include ONLY what the agent cannot discover independently:

• Non-obvious conventions ("we use snake_case for DB columns")
• Project-specific constraints ("never modify the auth module")
• Architectural decisions not in code ("we chose Drizzle over Prisma because...")
• External dependencies not discoverable ("deploy via internal CI, not GitHub Actions")

What NOT to Include

The agent can discover these itself — including them wastes tokens:

• Tech stack (visible in package.json / requirements.txt)
• File structure (visible via ls / find)
• Key files (visible via search)
• Build commands (visible in scripts / Makefile)
• Standard patterns (the model already knows React, Express, etc.)

Sizing Guidelines

| Context Type | Max Size | Rationale | |-------------|----------|-----------| | AGENTS.md | 500-1000 tokens | ETH Zurich: more = worse | | SKILL.md (core) | 1000-2500 tokens | Balance detail vs overhead | | references/ per skill | 500-1000 tokens | Support data, not duplicate | | System prompt total | three redundant ones

1. Use tables over prose — 50% fewer tokens for structured info
2. Remove "obvious" instructions — "write clean code" is noise
3. Use references for static data — move schemas/checklists to files
4. Lazy-load context — only load what's needed for current task

Anti-Patterns

| Anti-Pattern | Problem | Fix | |-------------|---------|-----| | "Always be thorough" | Forces effort=high, +35% tokens | Remove — model handles this | | "Think step by step" | Redundant with adaptive thinking | Remove on modern models | | Repeating the same rule 3x | Token waste, no benefit | State once, clearly | | Including full API docs | Context overflow | Link to docs, summarize key parts | | "You are a helpful assistant" | Generic, no value | Use specific task context |

What This Skill Does NOT Do

• Does not manage conversation memory (different problem)
• Does not optimize the model itself (skill ≠ fine-tuning)
• Does not handle multi-agent coordination (orchestration concern)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BuilderCed
• Source: BuilderCed/agent-skills
• License: MIT
• Homepage: https://skills.sh/BuilderCed/agent-skills

Install and usage instructions live in the source repository linked above.