| name | context-engineering |
| description | Active context curation to fight context rot. Curates what goes into limited context window from constantly evolving information universe. 39% improvement, 84% token reduction. |
| auto_invoke | true |
| tags | ["context","curation","optimization","memory"] |
Context Engineering Skill
This skill provides a systematic methodology for active context curation - the art and science of optimizing what goes into the limited context window from the constantly evolving universe of possible information.
Definition
Context Engineering: The art and science of curating what goes into the limited context window from the constantly evolving universe of possible information.
Evolution: Natural progression of prompt engineering
- Old paradigm: Finding the right words for prompts
- New paradigm: "What configuration of context is most likely to generate desired behavior?"
When Claude Should Use This Skill
Claude will automatically invoke this skill when:
- Conversation starts (optimize CLAUDE.md and knowledge-core.md relevance)
- During long sessions exceeding 50 messages (context rot likely)
- Before complex operations (ensure high-signal, minimal-token context)
- After tool use (update context with learnings, remove obsolete info)
- Task switching (archive old task context, load new task context)
Core Principles
-
Context Rot is Real: Information degrades as conversation lengthens
- Stale information accumulates
- Relevance decreases over time
- Attention budget gets wasted on low-signal content
-
Finite Attention Budget: Models have limited attention; optimize for signal
- Every token in context competes for attention
- High-signal tokens improve performance
- Low-signal tokens degrade outputs
-
Active Curation: Editing context is not cheating, it's engineering
- Context should be dynamically managed
- Archive what's no longer needed
- Load what's currently relevant
-
CLAUDE.md as Structure: Folder/file structure is context engineering
- Naming conventions encode information
- Directory patterns signal architecture
- Organization reduces cognitive load
Performance Results (Anthropic Research)
With Context Engineering:
- 39% improvement in agent-based search performance
- 84% reduction in token consumption (100-round web search)
- Higher signal-to-noise ratio in context window
- Better decision-making due to clearer, focused context
Example:
- Without context editing: 100-round search uses 50,000 tokens
- With context editing: 100-round search uses 8,000 tokens
- Improvement: 84% fewer tokens, 39% better quality
Context Curation Protocol
Curation Triggers
Automatic Triggers:
- Conversation exceeds 50 messages → Review and prune context
- Switching tasks → Archive old task context, load new task context
- Before complex operations → Ensure context is optimized for upcoming task
- After major learnings → Update knowledge-core.md, remove superseded info
- Tool use with large outputs → Consider archiving immediately
Manual Triggers (user-initiated):
/context analyze - Analyze current context configuration/context optimize - Actively prune and reorganize/context reset - Fresh start for new projects
Curation Actions
Step 1: Identify Stale Information
- Information no longer relevant to current task
- Outdated context from previous tasks
- Redundant or repetitive content
- Generic advice not specific to this project
Step 2: Archive to knowledge-core.md
- Preserve learnings for future sessions
- Maintain institutional knowledge
- Enable retrieval when needed again
Step 3: Remove from Active Context
- Reduce token count
- Improve signal-to-noise ratio
- Free up attention budget
Step 4: Verify Context Quality
- All information is high-signal for current task
- No redundancy or duplication
- Proper organization and structure
CLAUDE.md Optimization
What Belongs in CLAUDE.md
✅ Include:
- Project-specific guidelines: "Use 2-space indentation for JavaScript"
- Repository etiquette: "Never commit to main directly; use feature branches"
- Environment setup: "Run
npm install && npm run db:migrate before testing"
- Architecture patterns: "We use hexagonal architecture; see /docs/architecture.md"
- Conventions: "API routes go in /src/routes/, business logic in /src/services/"
❌ Avoid:
- Generic programming advice
- Universal best practices (Claude already knows these)
- Outdated information about the project
- Redundant content already in code comments
- Information that changes frequently (belongs in knowledge-core.md)
CLAUDE.md Structure Best Practices
# Project Name
## Quick Context
[2-3 sentences about what this project does]
## Development Environment
[Specific setup steps for THIS project]
## Architecture Patterns
[High-level patterns used in THIS codebase]
## Conventions
[Project-specific conventions that differ from defaults]
## Common Tasks
[Frequently performed workflows specific to THIS project]
## Import User Preferences
@~/.claude/agentic-substrate-personal.md
Context Engineering Best Practices
1. Few-Shot Prompting
- Curate 3-5 diverse canonical examples
- Show expected behavior patterns
- Choose examples that generalize well
- Include examples in CLAUDE.md or knowledge-core.md
Example:
## API Implementation Pattern
Example 1: GET /users/:id
[Show complete example]
Example 2: POST /orders
[Show complete example]
Example 3: PATCH /products/:id
[Show complete example]
2. Minimize Tokens
- Find smallest set of high-signal tokens
- Remove redundant information
- Archive historical context to knowledge-core.md
- Use references instead of duplication
Before:
Our authentication system uses JWT tokens. JWT tokens are JSON Web Tokens
that encode user information. We use JWT tokens for API authentication.
JWT tokens expire after 1 hour. JWT tokens are signed with HS256.
After (75% token reduction):
Authentication: JWT (HS256, 1hr expiry)
3. Structure as Context
- Use folder/file structure meaningfully
- Naming conventions encode information
- Directory patterns signal architecture
Example:
/src/
/api/ → API layer (REST endpoints)
/services/ → Business logic
/models/ → Data models
/utils/ → Shared utilities
/config/ → Configuration
This structure tells Claude the architecture without verbose explanation.
4. Dynamic Context Management
Load: Bring relevant context for current task
# Working on authentication now
@docs/authentication-architecture.md
Edit: Remove stale/irrelevant information
Archive: Preserve learnings to knowledge-core.md
# knowledge-core.md
## Authentication Implementation (2025-10-15)
Implemented JWT auth with refresh tokens.
Pattern: See /src/services/auth-service.js
Learnings: [what we learned]
Reload: Fetch archived context when needed again
# Switching back to authentication work
@knowledge-core.md#authentication-implementation
Tools for Context Engineering
Claude has these tools available for context management:
-
Read: Load context from CLAUDE.md, knowledge-core.md
- Use to understand current project context
- Check what's already documented
-
Edit: Update context files to remove stale info
- Remove outdated sections
- Update with new learnings
-
Write: Archive learnings to knowledge-core.md
- Preserve institutional knowledge
- Document patterns for future sessions
-
Grep: Find relevant context across codebase
- Locate existing patterns
- Find similar implementations
Anti-Pattern: Context Hoarding
❌ Don't: Keep all information in context "just in case"
- Results in context rot
- Wastes attention budget
- Degrades model performance
- Increases token costs
✅ Do: Archive to knowledge-core.md, reload when needed
- Maintains clean, focused context
- Preserves information for future
- Enables retrieval on demand
- Optimizes performance
Context Editing Mid-Session Example
Scenario
After completing API integration task, switching to UI work
Actions
Step 1: Archive API learnings
# knowledge-core.md
## API Integration Pattern (2025-10-18)
Integrated Stripe API v2023-10-16.
Pattern: See /src/services/payment-service.js
Learnings:
- Use idempotency keys for all payment requests
- Webhook signature verification is mandatory
- Test mode uses sk_test_, live uses sk_live_
Step 2: Remove API-specific context from active memory
- Edit CLAUDE.md to remove Stripe-specific guidelines
- Clear conversation history of API implementation details
- Archive API ResearchPack to knowledge-core.md
Step 3: Load UI patterns and conventions
# CLAUDE.md
## UI Development (Active Task)
Framework: React 18
Styling: Tailwind CSS
Component library: shadcn/ui
Pattern: Atomic design (atoms → molecules → organisms)
Step 4: Verify context optimization
- Context now focused on UI work
- API knowledge preserved in knowledge-core.md
- Can reload API context if needed later
Result
- 84% token reduction (removed API context)
- Clearer focus on current UI task
- Better performance due to optimized context
- Knowledge preserved for future API work
Context Scope Management
Scope Levels
1. Conversation Scope (current session)
- Immediate task context
- Recent tool outputs
- Active file contents
- Current problem being solved
2. Project Scope (CLAUDE.md)
- Project conventions
- Architecture patterns
- Environment setup
- Team guidelines
3. Knowledge Scope (knowledge-core.md)
- Accumulated learnings
- Historical patterns
- Solved problems
- Lessons learned
4. User Scope (~/.claude/agentic-substrate-personal.md)
- Personal preferences
- Coding style
- Common workflows
- Individual shortcuts
Managing Across Scopes
Promote (Conversation → Project):
- New pattern used multiple times → Add to CLAUDE.md
Archive (Conversation → Knowledge):
- Solved problem → Document in knowledge-core.md
Demote (Project → Knowledge):
- Outdated convention → Move to knowledge-core.md historical section
Reload (Knowledge → Conversation):
- Similar problem encountered → Load relevant knowledge
Integration with Memory Hierarchy
Context engineering integrates with Claude Code's memory system:
Memory Hierarchy (4 levels):
- Enterprise (
/Library/Application Support/ClaudeCode/CLAUDE.md) - Organization-wide
- Project (
./CLAUDE.md) - Team-shared
- User (
~/.claude/CLAUDE.md) - Personal preferences
- Imports (
@path/to/file.md) - Modular organization
Import Syntax:
# Load user preferences
@~/.claude/agentic-substrate-personal.md
# Load project-specific patterns
@.claude/templates/agents-overview.md
@.claude/templates/skills-overview.md
Benefits:
- Modular context organization
- User customization without changing project files
- Team conventions shared via project CLAUDE.md
- Enterprise policies enforced at org level
Common Context Problems & Solutions
Problem 1: Context Rot
Symptom: Model performance degrades over long conversations
Solution: Regular pruning at 50-message intervals
Problem 2: Information Overload
Symptom: Too much context, model misses key details
Solution: Archive historical content to knowledge-core.md
Problem 3: Redundant Information
Symptom: Same information repeated in multiple places
Solution: Use references/imports instead of duplication
Problem 4: Stale Context
Symptom: Outdated patterns or deprecated approaches in context
Solution: Regular CLAUDE.md review and updates
Problem 5: Missing Context
Symptom: Model lacks necessary project-specific information
Solution: Document critical patterns in CLAUDE.md
Quality Checklist
Before considering context optimized:
Performance Monitoring
Track these metrics to measure context engineering effectiveness:
Token Efficiency:
- Tokens per conversation round (should decrease over time)
- Context window utilization (should stay < 70%)
- Redundancy ratio (duplicate info / total info)
Quality Metrics:
- Successful task completion rate (should increase)
- Self-correction frequency (should decrease)
- Clarification questions needed (should decrease)
Knowledge Preservation:
- knowledge-core.md growth rate (steady accumulation)
- Pattern reuse frequency (documented patterns applied)
- Historical context retrieval success rate
Context engineering is not optional - it's the foundation of sustainable, high-performance agent interactions.
Remember: Every token in context either helps or hurts. Make each one count.
