aibot88 Context Management in SpecWeave
Overview
SpecWeave achieves efficient context usage through two native Claude Code mechanisms:
- Progressive Disclosure (Skills) - Claude's built-in skill loading system
- 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)
---
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)
# 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
"Skills work through progressive disclosure—Claude determines which Skills are relevant and loads the information it needs to complete that task, helping to prevent context window overload."
2. Sub-Agent Parallelization
How It Works
Sub-agents in Claude Code have isolated context windows:
Main conversation (100K tokens used)
↓
Launches 3 sub-agents in parallel
↓
├─ Sub-agent 1: Fresh context (0K tokens used)
├─ Sub-agent 2: Fresh context (0K tokens used)
└─ Sub-agent 3: Fresh context (0K tokens used)
Benefits:
Context Isolation
- Each sub-agent starts with empty context
- Doesn't inherit main conversation's 100K tokens
- Can load its own relevant skills
Parallelization
- Multiple agents work simultaneously
- Each with own context budget
- Results merged back to main conversation
Token Multiplication
- Main: 200K token limit
- Sub-agent 1: 200K token limit
- Sub-agent 2: 200K token limit
- Effective capacity: 600K+ tokens across parallel work
Example Workflow
User: "Build a full-stack Next.js app with auth, payments, and admin"
↓
Main conversation launches 3 sub-agents in parallel:
↓
├─ Sub-agent 1 (Frontend)
│ - Loads: nextjs, frontend skills
│ - Context: 12K tokens
│ - Implements: Auth UI, payment forms
│
├─ Sub-agent 2 (Backend)
│ - Loads: nodejs-backend, security skills
│ - Context: 15K tokens
│ - Implements: API routes, auth logic
│
└─ Sub-agent 3 (DevOps)
- Loads: devops, hetzner-provisioner skills
- Context: 8K tokens
- Implements: Deployment configs
↓
All 3 work in parallel with isolated contexts
↓
Results merged back to main conversation
↓
Total effective context: 35K tokens across 3 agents
(vs 175K+ if loaded all skills in main conversation)
References
Actual Token Savings
Progressive Disclosure Savings
Scenario: User asks about Next.js
Without progressive disclosure:
Load all 35 skills: ~175,000 tokens
Context bloat: Massive
With progressive disclosure:
Metadata (all skills): ~2,625 tokens
Load relevant (2 skills): ~9,000 tokens
Total: ~11,625 tokens
Reduction: ~93%
Sub-Agent Savings
Scenario: Complex multi-domain task
Single agent approach:
Load all relevant skills: ~50,000 tokens
Main conversation history: ~80,000 tokens
Total context used: ~130,000 tokens
Risk: Approaching context limit
Sub-agent approach:
Main conversation: ~5,000 tokens (coordination only)
Sub-agent 1: ~15,000 tokens (isolated)
Sub-agent 2: ~18,000 tokens (isolated)
Sub-agent 3: ~12,000 tokens (isolated)
Total: ~50,000 tokens across 4 contexts
Reduction: ~62% (130K → 50K)
Note: Exact percentages vary by task complexity. These are approximate based on typical usage patterns.
How SpecWeave Leverages These Mechanisms
1. Skill Organization (Progressive Disclosure)
SpecWeave organizes 35+ skills with clear, focused descriptions:
# Good: Focused description
---
name: nextjs
description: NextJS 14+ App Router specialist. Server Components, SSR, routing.
---
# Bad: Vague description
---
name: frontend
description: Does frontend stuff
---
Why this matters:
- Clear descriptions help Claude identify relevance quickly
- Prevents loading irrelevant skills
- Maximizes progressive disclosure benefits
2. Agent Coordination (Sub-Agent Parallelization)
SpecWeave's role-orchestrator skill automatically:
- Detects multi-domain tasks
- Launches specialized sub-agents (PM, Architect, DevOps, etc.)
- Each sub-agent loads only its relevant skills
- Coordinates results back to main conversation
Example:
User: "/sw:inc 'Full-stack SaaS with Stripe payments'"
↓
role-orchestrator activates
↓
Launches sub-agents in parallel:
├─ PM agent (requirements)
├─ Architect agent (system design)
├─ Security agent (threat model)
└─ DevOps agent (deployment)
↓
Each loads only relevant skills in isolated context
↓
Results merged into increment spec
Common Misconceptions
❌ Myth 1: "SpecWeave has custom context manifests"
Reality: No. SpecWeave uses Claude's native progressive disclosure. Skills load based on Claude's relevance detection, not custom YAML manifests.
❌ Myth 2: "SpecWeave caches loaded context"
Reality: No custom caching. Claude Code handles caching internally (if applicable). SpecWeave doesn't implement additional caching layers.
❌ Myth 3: "70-90% token reduction"
Reality: Token savings vary by task:
- Simple tasks: 90%+ (load 1-2 skills vs all 35)
- Complex tasks: 50-70% (load 5-10 skills + use sub-agents)
- Exact percentages depend on task complexity
✅ Truth: "It just works"
Reality: Progressive disclosure and sub-agents are automatic. You don't configure them. Claude handles skill loading, sub-agent context isolation happens automatically when agents are launched.
Best Practices
For Skill Descriptions
Do:
- Be specific about what the skill does
- Include trigger keywords users might say
- List technologies/frameworks explicitly
Don't:
- Write vague descriptions ("helps with coding")
- Omit key activation triggers
- Mix multiple unrelated domains in one skill
For Sub-Agent Usage
When to use sub-agents:
- Multi-domain tasks (frontend + backend + devops)
- Parallel work (multiple features simultaneously)
- Large codebase exploration (different modules)
When NOT to use sub-agents:
- Simple single-domain tasks
- Sequential work requiring shared context
- When main conversation context is already low
Debugging Context Usage
Check Active Skills
When Claude mentions using a skill:
User: "Create a Next.js page"
Claude: "🎨 Using nextjs skill..."
This means:
- Progressive disclosure worked
- Only nextjs skill loaded (not all 35)
- Context efficient
Check Sub-Agent Usage
When Claude mentions launching agents:
Claude: "🤖 Launching 3 specialized agents in parallel..."
This means:
- Sub-agent parallelization active
- Each agent has isolated context
- Efficient multi-domain processing
Summary
SpecWeave achieves context efficiency through:
Progressive Disclosure (Native Claude)
- Skills load only when relevant
- Metadata-first approach
- 90%+ savings on simple tasks
Sub-Agent Parallelization (Native Claude Code)
- Isolated context windows
- Parallel processing
- 50-70% savings on complex tasks
No custom manifests. No custom caching. Just smart use of Claude's native capabilities.