context-loader

# Context Management in SpecWeave

## Overview

SpecWeave achieves efficient context usage through **two native Claude Code mechanisms**:

1. **Progressive Disclosure** (Skills) - Claude's built-in skill loading system
2. **Sub-Agent Parallelization** - Isolated context windows for parallel work

**Important**: SpecWeave does NOT use custom context manifests or caching systems. It leverages Claude's native capabilities.

---

## 1. Progressive Disclosure (Skills)

### How It Works

Claude Code uses a **two-level progressive disclosure system** for skills:

#### Level 1: Metadata Only (Always Loaded)

```yaml
---
name: nextjs
description: NextJS 14+ implementation specialist. Creates App Router projects...
---
```

**What Claude sees initially:**
- Only the YAML frontmatter (name + description)
- ~50-100 tokens per skill
- **All** skills' metadata is visible
- Claude can decide which skills are relevant

#### Level 2: Full Skill Content (Loaded On-Demand)

```markdown
# NextJS Skill

[Full documentation, examples, best practices...]
[Could be 5,000+ tokens]
```

**What Claude loads:**
- Full SKILL.md content **only if** skill is relevant to current task
- Prevents loading 35+ skills (175,000+ tokens) when you only need 2-3
- **This is the actual mechanism** that saves tokens

### Example Workflow

```
User: "Create a Next.js authentication page"
    ↓
Claude reviews skill metadata (35 skills × 75 tokens = 2,625 tokens)
    ↓
Claude determines relevant skills:
  - nextjs (matches "Next.js")
  - frontend (matches "page")
  - (NOT loading: python-backend, devops, hetzner-provisioner, etc.)
    ↓
Claude loads ONLY relevant skills:
  - nextjs: 5,234 tokens
  - frontend: 3,891 tokens
    ↓
Total loaded: 9,125 tokens (vs 175,000+ if loading all skills)
Token reduction: ~95%
```

### References

- [What are Skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
- [Agent Skills Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real