18 KiB
18 KiB
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:
- Metadata always in context (~50 tokens per skill)
- Content loads on-demand (only when needed)
- Keyword-based activation (automatic skill discovery)
- 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.