context-engineering

# 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

1. **Context Rot is Real**: Information degrades as conversation lengthens
   - Stale information accumulates
   - Relevance decreases over time
   - Attention budget gets wasted on low-signal content

2. **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

3. **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

4. **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**:
1. **Conversation exceeds 50 messages** → Review and prune context
2. **Switching tasks** → Archive old task context, load new task context
3. **Before complex operations** → Ensure context is optimized for upcoming task
4. **After major learnings** → Update knowledge-core.md, remove superseded info
5. **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

```markdown
# 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**:
```markdown
## 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**:
```markdown
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):
```markdown
Authentication: JWT (HS256, 1hr expiry)
```

### 3. Structure as Context
- Use folder/file structure meaningfully
- Naming conv