Feature: Lazy Loading for Skills (Metadata-Only Context)

Feature Request: Lazy Loading for Skills (Metadata-Only Context)

Problem Statement

Current Behavior:
Claude Code loads ALL installed skills completely into the context window at session start, regardless of whether they are used.

Impact:

• My setup: 50+ skills consuming ~180k tokens (18% of 1M context)
• spec-executor: 14.6k tokens
• spec-finalizer: 10.7k tokens
• config-generator: 9.4k tokens
• etc.

This causes:

1. High baseline context usage before any actual work
2. Reduced effective context for long conversations
3. Slower session initialization (more tokens to process)
4. Scalability issues as skill library grows

Proposed Solution

Option 1: Metadata-Only Loading (Recommended)

Load at startup:

{
  "name": "spec-executor",
  "description": "Execute specs autonomously via Ralph loops",
  "triggers": ["/spec-executor", "execute spec", "run spec"],
  "location": "user",
  "tokenCount": 14600
}

→ ~50 tokens per skill (vs. 14.6k full content)

Load full skill content:

• When user invokes the skill via Skill tool
• When Claude Code detects trigger keywords in user message
• On-demand via explicit user request

Benefits:

• 50 skills × 50 tokens = 2.5k tokens (vs. 180k tokens = 98.6% reduction)
• Skills registry still visible for discovery
• No breaking changes to user workflow

Option 2: Tiered Loading

Tier 1 - Always Loaded (Core Skills):

• Frequently used skills (user-configurable)
• Project-specific skills (in .claude/skills/)

Tier 2 - Lazy Loaded (Extended Skills):

• Global skills (~/.claude/skills/)
• Plugin skills
• Rarely used skills

Tier 3 - On-Demand:

• Archived skills
• Experimental skills

Option 3: Smart Caching

• Load skills based on conversation context
• Cache recently used skills for session
• Unload unused skills after N turns

Use Cases

Use Case 1: Large Skill Library

User: Developer with 50+ custom skills for different project types
Benefit: Can maintain extensive skill library without context penalty

Use Case 2: Long Conversations

User: Complex debugging session requiring deep codebase exploration
Benefit: More context available for actual work vs. unused skill definitions

Use Case 3: Plugin Developers

User: Testing/developing multiple plugin variants
Benefit: Can install multiple plugins without token explosion

Implementation Considerations

Breaking Changes

• None - Skills work identically from user perspective
• Transparent lazy loading on invocation

Performance Trade-offs

• Pro: 95%+ token reduction at startup
• Con: Small latency (~50-100ms) on first skill invocation
• Mitigation: Predictive pre-loading based on conversation context

Backward Compatibility

• Existing skills work without modification
• Optional skill.json metadata for optimization
• Fallback to full loading if metadata missing

Example Metadata Format

{
  "version": "1.0",
  "name": "spec-executor",
  "description": "Execute specs autonomously via Ralph loops with Gap Analysis",
  "triggers": {
    "commands": ["/spec-executor", "/execute-spec"],
    "keywords": ["execute spec", "run spec", "implement spec"],
    "patterns": ["spec [0-9]{4}"]
  },
  "category": "automation",
  "tags": ["specs", "ralph-loops", "autonomous"],
  "requiredTools": ["Task", "Read", "Edit", "Bash"],
  "estimatedTokens": 14600
}

Migration Path

Phase 1: Opt-In (v1.x)

• Add --lazy-skills flag
• Users can test and provide feedback
• Skills work as before without flag

Phase 2: Default (v2.0)

• Lazy loading becomes default
• Opt-out via --eager-skills for legacy behavior
• Auto-generate metadata for skills without it

Phase 3: Optimization (v2.1+)

• Smart caching
• Predictive pre-loading
• Analytics on skill usage patterns

Metrics for Success

• Token Reduction: >90% reduction in skill-related context usage
• Performance: <100ms latency on skill invocation
• Compatibility: 100% of existing skills work without modification
• Adoption: >50% of power users enable lazy loading within 3 months

Related Issues

• Token optimization for large projects
• Context window management
• Plugin scalability

Additional Context

My current setup:

Context Usage: 39k/1000k tokens (4%)
├─ System prompt: 4.7k (0.5%)
├─ System tools: 19.9k (2.0%)
├─ Custom agents: 205 (0.0%)
├─ Memory files: 14.5k (1.4%)
├─ Skills: ~180k (18.0%) ← NOT SHOWN in summary!
└─ Messages: 8 (0.0%)

The /context output doesn't even show the full skill token usage, suggesting it may be loaded separately or summarized.

---

Would this feature be valuable to other Claude Code users?
I believe many power users face this challenge as their skill library grows. This feature would enable sustainable scaling of custom tooling without context trade-offs.