version: "1.0.0" name: context-engineering description: "Optimize Claude Code context-window usage for accuracy and cost. TRIGGER when: hitting context limits, structuring prompts for an agent, or trimming what gets injected into a task. SKIP: persisting knowledge across sessions (use agent-memory); semantic recall tuning (use semantic-memory-mcp)."

Context Engineering Skill

Optimizes Claude Code context for better performance and accuracy.

Tracked files in repo: !git ls-files 2>/dev/null | wc -l || true

Auto-Invoke Triggers

• Every 50 messages in conversation
• After major refactoring
• When context feels stale
• Task switching
• User requests /context command

Context Principles

Active Curation

• Keep only relevant information
• Remove completed task details
• Archive outdated patterns
• Focus on current work

Signal-to-Noise Ratio

Token Budget

Context Analysis Process

Step 1: Measure Current State

## Context Analysis
 
### Token Counts
-CLAUDE.md: XXX tokens
-Agent docs: XXX tokens total
-Skills: XXX tokens total
-Total: XXXX tokens
 
### Staleness Check
-[ ] Last updated: [date]
-[ ] References current project state
-[ ] No deprecated APIs/patterns

Step 2: Identify Issues

### Issues Found
 
#### Stale Content
-Section X: Outdated [reason]
-Section Y: No longer relevant
 
#### Redundant Content
-Duplicated in files A and B
-Can consolidate X and Y
 
#### Missing Content
-Current API not documented
-New pattern not captured

Step 3: Optimization Actions

### Optimization Plan
 
1.**Archive**: Move section X to knowledge-core.md
2.**Remove**: Delete duplicate Y
3.**Update**: Refresh API documentation
4.**Add**: Document new pattern Z

CLAUDE.md Structure

Optimal structure for quick reference:

# Project Name
 
[One-line description]
 
## Quick Reference
| Action | Command |
|--------|---------|
| Run | command |
| Test | command |
| Build | command |
 
## Agent System
[Link to detailed docs]
 
## Tech Stack
-Frontend: [stack]
-Backend: [stack]
 
## Project Structure
[Key directories only]
 
## Key Rules
1.[Critical rule]
2.[Critical rule]

Always-loaded vs lazy path-scoped rules

CLAUDE.md content splits into two tiers by when it must be available:

Hard rule: the routing sections NEVER move into a nested CLAUDE.md — routing must fire on the first message, but a nested file only loads on Edit/Write under its tree (too late to route). Only path-specific code conventions are candidates to relocate, and only via the opt-in /init-rules scaffolder. This trims always-loaded tokens (modest for the plugin CLAUDE.md, larger for heavy project repos) without weakening routing. /doctor asserts the routing section is still present in the root CLAUDE.md.

Optimization Strategies

Token Reduction

• Use tables instead of prose
• Link to details instead of inline
• Remove examples from main docs
• Keep explanations brief

Information Hierarchy

1. Immediate: In CLAUDE.md
2. Reference: In linked docs
3. Archive: In knowledge-core.md
4. Delete: Truly obsolete

Import Chain Management

• Max 5 levels of imports
• No circular references
• Clear dependency direction

Context Health Metrics

Maintenance Schedule

Output: Context Report

## Context Report
 
**Date**: [date]
**Health**: Healthy | Warning | Critical
 
### Metrics
-Total tokens: XXXX
-Stale sections: X
-Redundancy: X%
 
### Findings
1.[Finding]
2.[Finding]
 
### Recommendations
1.[Action to take]
2.[Action to take]
 
### Potential Savings
-Current: XXXX tokens
-After optimization: XXXX tokens
-Savings: XX%