gh-resolve-io-prism/skills/skill-builder/reference/philosophy.md

Best Practices Guide

Progressive Disclosure Applied: This guide uses a hierarchical structure where you start with high-level concepts and progressively drill down into technical details.

Token-Optimized Structure:

• This file: ~628 tokens (overview & navigation)
• best-practices.md: ~920 tokens (quick reference for building skills)
• Topic files: 1.4k-2.2k tokens each (deep dives loaded as-needed)

📑 Navigation: See INDEX.md for complete file reference and navigation patterns.

---

🎯 Quick Start (Level 1)

Building a New Skill?

→ Skill Creation Process - Follow this step-by-step guide

Learning Patterns?

Choose your learning path:

• Progressive Disclosure - Learn the core UX/architectural pattern
• Dynamic Manifests - Implement runtime capability discovery
• Deferred Loading - Optimize resource initialization

Need Quick Reference?

→ best-practices.md - Checklists, templates, and common pitfalls

---

📚 Concept Map

Best Practices
│
├─── Progressive Disclosure ◄──┐
│    (Design Pattern)           │
│    │                           │
│    └─── Influences ────────────┤
│                                │
├─── Dynamic Manifests ◄────────┤
│    (Runtime Discovery)         │
│    │                           │
│    └─── Enables ───────────────┤
│                                │
└─── Deferred Loading ◄─────────┘
     (Lazy Initialization)

---

🚀 Why These Patterns Matter

The Problem

Traditional systems load everything at startup:

• ❌ Slow initialization
• ❌ High memory consumption
• ❌ Wasted resources on unused features
• ❌ Poor scalability

The Solution

Progressive Disclosure + Dynamic Manifests + Deferred Loading:

• ✅ Fast startup (load on-demand)
• ✅ Efficient resource usage
• ✅ Adaptive capabilities
• ✅ Context-aware feature availability

---

📖 Learning Path

For Beginners

1. Start with Progressive Disclosure - Understand the philosophy
2. See Simple Examples
3. Review Quick Start

For Practitioners

1. Read Implementation Patterns
2. Configure Dynamic Manifests
3. Optimize with Deferred Loading

For Architects

1. Study Architectural Principles
2. Design Capability Systems
3. Implement Advanced Optimization

---

🔗 Topic Relationships

Progressive Disclosure → Dynamic Manifests

Progressive disclosure provides the design philosophy: show users only what they need, when they need it.

Dynamic manifests provide the technical implementation: systems query capabilities at runtime, enabling features progressively.

Example: A chat interface starts with basic tools (Level 1), then reveals advanced tools (Level 2) as the user demonstrates expertise → The system's dynamic manifest adjusts which tools are available based on context.

Dynamic Manifests → Deferred Loading

Dynamic manifests tell you what's available.

Deferred loading determines when to initialize it.

Example: Dynamic manifest says "Tool X is available" → Deferred loading ensures Tool X's code isn't loaded until first use → Saves memory and startup time.

---

🎓 Real-World Applications

MCP (Model Context Protocol) Skills

User opens Claude Code
  ↓
[Progressive Disclosure]
  → Only basic skills shown initially

User works with project files
  ↓
[Dynamic Manifests]
  → System detects project type
  → New relevant skills appear

User invokes advanced skill
  ↓
[Deferred Loading]
  → Skill code loaded on first use
  → Subsequent calls use cached version

Web Applications

User visits page
  ↓
[Progressive Disclosure]
  → Core UI loads first

User navigates to dashboard
  ↓
[Dynamic Manifests]
  → Check user permissions
  → Build feature menu dynamically

User clicks "Export Data"
  ↓
[Deferred Loading]
  → Load export library on demand
  → Initialize only when needed

---

🛠️ Implementation Checklist

Use this as a quick reference when implementing these patterns:

• Design information hierarchy (Progressive Disclosure)
• Identify capability tiers (Basic → Intermediate → Advanced)
• Implement runtime discovery endpoints (Dynamic Manifests)
• Create .well-known/mcp/manifest.json (MCP specific)
• Enable lazy initialization (Deferred Loading)
• Add caching strategies (Optimization)
• Implement change notifications (Dynamic updates)
• Test without system restart (Validation)

---

📊 Performance Metrics

Track these to measure success:

Metric	Before	Target	Pattern
Initial Load Time	5s	< 1s	Progressive Disclosure
Memory at Startup	500MB	< 100MB	Deferred Loading
Feature Discovery	Static	Dynamic	Dynamic Manifests
Context Tokens Used	10k	< 2k	Progressive Loading

---

🔍 Deep Dive Topics

Ready to go deeper? Click any topic:

1. Progressive Disclosure

   • Design philosophy
   • UX patterns
   • Information architecture
   • Cognitive load management

2. Dynamic Manifests

   • Configuration guide
   • Endpoint implementation
   • Registry patterns
   • MCP-specific setup

3. Deferred Loading

   • Lazy initialization
   • Code splitting
   • Resource optimization
   • Caching strategies

---

🎯 Quick Wins

Want immediate improvements? Start here:

5-Minute Win: Enable Dynamic Discovery

// claude_desktop_config.json
{
  "mcpServers": {
    "your-server": {
      "dynamicDiscovery": true,
      "discoveryInterval": 5000
    }
  }
}

See Dynamic Manifests: Quick Start

15-Minute Win: Implement Lazy Loading

from functools import lru_cache

@lru_cache(maxsize=128)
def load_expensive_resource():
    # Only loads on first call
    return initialize_resource()

See Deferred Loading: Basic Patterns

30-Minute Win: Progressive Disclosure UI

# Level 1: Essentials (always visible)
## Getting Started

# Level 2: Intermediate (click to expand)
<details>
<summary>Advanced Features</summary>
...
</details>

# Level 3: Expert (separate page)
See [Advanced Guide](./advanced.md)

See Progressive Disclosure: UI Patterns

---

📚 Additional Resources

• MCP Official Spec
• Progressive Disclosure (Nielsen Norman Group)
• Lazy Loading Best Practices

---

🆘 Troubleshooting

Problem: Changes not appearing without restart Solution: Check Dynamic Manifests: Configuration

Problem: High memory usage at startup Solution: Review Deferred Loading: Strategies

Problem: Users overwhelmed by options Solution: Apply Progressive Disclosure: Principles

---

Last Updated: 2025-10-20 Version: 1.0.0