337 lines
18 KiB
Markdown
337 lines
18 KiB
Markdown
# Progressive Disclosure Architecture Diagram
|
||
|
||
Visual representation of how progressive disclosure works in Claude Code 2.0+.
|
||
|
||
## High-Level Architecture
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ Claude Code 2.0+ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ skills/ Directory │ │
|
||
│ │ │ │
|
||
│ │ ├── testing-guide/SKILL.md │ │
|
||
│ │ ├── python-standards/SKILL.md │ │
|
||
│ │ ├── security-patterns/SKILL.md │ │
|
||
│ │ ├── api-design/SKILL.md │ │
|
||
│ │ └── ... (17 more skills) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ Startup: Load metadata only │
|
||
│ ↓ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Agent Context (Startup) │ │
|
||
│ │ │ │
|
||
│ │ ┌────────────────────────────────────────────────┐ │ │
|
||
│ │ │ Agent Prompt: ~500 tokens │ │ │
|
||
│ │ ├────────────────────────────────────────────────┤ │ │
|
||
│ │ │ Skill Metadata: 21 × 50 = ~1,050 tokens │ │ │
|
||
│ │ │ - testing-guide: 50 tokens │ │ │
|
||
│ │ │ - python-standards: 50 tokens │ │ │
|
||
│ │ │ - security-patterns: 50 tokens │ │ │
|
||
│ │ │ - ... (18 more) │ │ │
|
||
│ │ └────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ │ Total: ~1,550 tokens (efficient!) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ Task provided │
|
||
│ ↓ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Task Analysis │ │
|
||
│ │ │ │
|
||
│ │ User Task: "Write tests for authentication" │ │
|
||
│ │ (contains keywords: "tests", "auth") │ │
|
||
│ │ │ │
|
||
│ │ Keyword Matching: │ │
|
||
│ │ - "tests" matches testing-guide │ │
|
||
│ │ - "authentication" matches security-patterns │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ Load matching skills │
|
||
│ ↓ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Agent Context (Task Execution) │ │
|
||
│ │ │ │
|
||
│ │ ┌────────────────────────────────────────────────┐ │ │
|
||
│ │ │ Base Context: ~1,550 tokens │ │ │
|
||
│ │ ├────────────────────────────────────────────────┤ │ │
|
||
│ │ │ Task Description: ~200 tokens │ │ │
|
||
│ │ ├────────────────────────────────────────────────┤ │ │
|
||
│ │ │ testing-guide FULL CONTENT: ~5,000 tokens │ │ │
|
||
│ │ ├────────────────────────────────────────────────┤ │ │
|
||
│ │ │ security-patterns FULL CONTENT: ~6,000 tokens │ │ │
|
||
│ │ └────────────────────────────────────────────────┘ │ │
|
||
│ │ │ │
|
||
│ │ Total: ~12,750 tokens (only what's needed!) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Skill Loading Sequence
|
||
|
||
### Phase 1: Startup (Metadata Loading)
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ Claude Code │
|
||
│ Startup │
|
||
└──────┬───────┘
|
||
│
|
||
│ Scan skills/ directory
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ For each SKILL.md: │
|
||
│ 1. Read file │
|
||
│ 2. Extract YAML frontmatter │
|
||
│ 3. Store metadata in memory │
|
||
│ 4. Discard full content │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Result: Metadata only
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Skill Registry (In Memory) │
|
||
│ │
|
||
│ testing-guide: │
|
||
│ keywords: [test, testing, pytest] │
|
||
│ content_path: skills/testing-guide/ │
|
||
│ │
|
||
│ security-patterns: │
|
||
│ keywords: [security, auth, jwt] │
|
||
│ content_path: skills/security-.../ │
|
||
│ │
|
||
│ ... (19 more skills) │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Total: ~1,050 tokens
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Ready for tasks! │
|
||
│ (Minimal context used) │
|
||
└────────────────────────────────────────┘
|
||
```
|
||
|
||
### Phase 2: Task Execution (Progressive Loading)
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ User provides│
|
||
│ task │
|
||
└──────┬───────┘
|
||
│
|
||
│ "Write secure API tests with pytest"
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Keyword Extraction │
|
||
│ │
|
||
│ Keywords found: │
|
||
│ - "tests" (→ testing-guide) │
|
||
│ - "pytest" (→ testing-guide) │
|
||
│ - "secure" (→ security-patterns) │
|
||
│ - "api" (→ api-design) │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Match against skill registry
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Matching Skills: │
|
||
│ 1. testing-guide (matches: tests, pytest)│
|
||
│ 2. security-patterns (matches: secure) │
|
||
│ 3. api-design (matches: api) │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Load full content on-demand
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Skill Loading │
|
||
│ │
|
||
│ Load testing-guide: │
|
||
│ - Read full SKILL.md content │
|
||
│ - +5,000 tokens │
|
||
│ │
|
||
│ Load security-patterns: │
|
||
│ - Read full SKILL.md content │
|
||
│ - +6,000 tokens │
|
||
│ │
|
||
│ Load api-design: │
|
||
│ - Read full SKILL.md content │
|
||
│ - +4,000 tokens │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Total: +15,000 tokens
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Agent Context │
|
||
│ │
|
||
│ Base: ~1,550 tokens │
|
||
│ Task: ~200 tokens │
|
||
│ Skills: ~15,000 tokens │
|
||
│ ───────────────────────────── │
|
||
│ Total: ~16,750 tokens │
|
||
│ │
|
||
│ (Only 8% of 200K context budget) │
|
||
└────────────────────────────────────────┘
|
||
│
|
||
│ Agent processes task
|
||
↓
|
||
┌────────────────────────────────────────┐
|
||
│ Task Completed! │
|
||
└────────────────────────────────────────┘
|
||
```
|
||
|
||
## Token Comparison
|
||
|
||
### Traditional Approach (Load All Skills)
|
||
|
||
```
|
||
Startup:
|
||
┌──────────────────────────────────────┐
|
||
│ Agent Prompt: 500 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ testing-guide: 5,000 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ python-standards: 3,000 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ security-patterns: 6,000 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ api-design: 4,000 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ ... (17 more skills) │
|
||
└──────────────────────────────────────┘
|
||
Total: ~100,000 tokens (50% of budget!)
|
||
|
||
Problems:
|
||
❌ Half of context budget used before task starts
|
||
❌ Most skills irrelevant to task
|
||
❌ Slow loading time
|
||
❌ Can't scale beyond 20-30 skills
|
||
```
|
||
|
||
### Progressive Disclosure (Load on Demand)
|
||
|
||
```
|
||
Startup:
|
||
┌──────────────────────────────────────┐
|
||
│ Agent Prompt: 500 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ Skill Metadata: 1,050 tokens │
|
||
│ (21 skills × 50 tokens) │
|
||
└──────────────────────────────────────┘
|
||
Total: ~1,550 tokens (< 1% of budget!)
|
||
|
||
Task Execution:
|
||
┌──────────────────────────────────────┐
|
||
│ Base: 1,550 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ Task: 200 tokens │
|
||
├──────────────────────────────────────┤
|
||
│ testing-guide: 5,000 tokens │ ← Loaded on-demand
|
||
├──────────────────────────────────────┤
|
||
│ security-patterns: 6,000 tokens │ ← Loaded on-demand
|
||
├──────────────────────────────────────┤
|
||
│ api-design: 4,000 tokens │ ← Loaded on-demand
|
||
└──────────────────────────────────────┘
|
||
Total: ~16,750 tokens (8% of budget)
|
||
|
||
Benefits:
|
||
✅ Only 8% of context budget used
|
||
✅ Only relevant skills loaded
|
||
✅ Fast startup
|
||
✅ Scales to 100+ skills
|
||
```
|
||
|
||
## Multi-Stage Loading Example
|
||
|
||
Progressive disclosure can load skills at any point during task execution:
|
||
|
||
```
|
||
Task: "Implement user registration API with secure password storage and tests"
|
||
|
||
Time: 0 minutes
|
||
┌──────────────────────────────┐
|
||
│ Context: 1,750 tokens │
|
||
│ - Agent + metadata + task │
|
||
└──────────────────────────────┘
|
||
|
||
Time: 2 minutes (API design phase)
|
||
┌──────────────────────────────┐
|
||
│ Context: 5,750 tokens │
|
||
│ + api-design: 4,000 tokens │ ← Loaded when agent starts API design
|
||
└──────────────────────────────┘
|
||
|
||
Time: 5 minutes (Security implementation)
|
||
┌──────────────────────────────┐
|
||
│ Context: 11,750 tokens │
|
||
│ + security-patterns: 6K │ ← Loaded when agent encounters security requirements
|
||
└──────────────────────────────┘
|
||
|
||
Time: 8 minutes (Database schema)
|
||
┌──────────────────────────────┐
|
||
│ Context: 15,250 tokens │
|
||
│ + database-design: 3.5K │ ← Loaded when agent designs schema
|
||
└──────────────────────────────┘
|
||
|
||
Time: 12 minutes (Testing)
|
||
┌──────────────────────────────┐
|
||
│ Context: 20,250 tokens │
|
||
│ + testing-guide: 5K │ ← Loaded when agent writes tests
|
||
└──────────────────────────────┘
|
||
|
||
Time: 15 minutes (Documentation)
|
||
┌──────────────────────────────┐
|
||
│ Context: 24,250 tokens │
|
||
│ + documentation-guide: 4K │ ← Loaded when agent documents API
|
||
└──────────────────────────────┘
|
||
|
||
Task Completed!
|
||
Final context: 24,250 tokens (12% of budget)
|
||
```
|
||
|
||
## Scalability
|
||
|
||
### With Progressive Disclosure
|
||
|
||
```
|
||
Number of Skills vs Context Usage (Startup):
|
||
|
||
10 skills: 500 tokens (metadata)
|
||
20 skills: 1,000 tokens (metadata)
|
||
50 skills: 2,500 tokens (metadata)
|
||
100 skills: 5,000 tokens (metadata)
|
||
|
||
Scales linearly! ✅
|
||
```
|
||
|
||
### Without Progressive Disclosure
|
||
|
||
```
|
||
Number of Skills vs Context Usage (Startup):
|
||
|
||
10 skills: 50,000 tokens (full content)
|
||
20 skills: 100,000 tokens (full content)
|
||
50 skills: 250,000 tokens (exceeds budget!) ❌
|
||
100 skills: 500,000 tokens (impossible!) ❌
|
||
|
||
Doesn't scale! ❌
|
||
```
|
||
|
||
## Summary
|
||
|
||
Progressive disclosure architecture:
|
||
|
||
**Key principles:**
|
||
1. **Metadata always in context** (~50 tokens per skill)
|
||
2. **Content loads on-demand** (only when needed)
|
||
3. **Keyword-based activation** (automatic skill discovery)
|
||
4. **Linear scaling** (supports 100+ skills)
|
||
|
||
**Benefits:**
|
||
- 85% reduction in context usage
|
||
- Fast startup times
|
||
- Scales to 100+ skills
|
||
- Only relevant skills load
|
||
|
||
**Result:** Efficient, scalable skill system that maintains full access to specialized knowledge without context bloat.
|