# 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](./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](./INDEX.md) for complete file reference and navigation patterns.

---

## 🎯 Quick Start (Level 1)

### Building a New Skill?
→ **[Skill Creation Process](./reference/skill-creation-process.md)** - Follow this step-by-step guide

### Learning Patterns?
Choose your learning path:

- **[Progressive Disclosure](./topics/progressive-disclosure.md)** - Learn the core UX/architectural pattern
- **[Dynamic Manifests](./topics/dynamic-manifests.md)** - Implement runtime capability discovery
- **[Deferred Loading](./topics/deferred-loading.md)** - Optimize resource initialization

### Need Quick Reference?
→ **[best-practices.md](./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](./topics/progressive-disclosure.md#what-is-it)** - Understand the philosophy
2. See **[Simple Examples](./topics/progressive-disclosure.md#simple-examples)**
3. Review **[Quick Start](./topics/dynamic-manifests.md#quick-start)**

### For Practitioners
1. Read **[Implementation Patterns](./topics/progressive-disclosure.md#implementation-patterns)**
2. Configure **[Dynamic Manifests](./topics/dynamic-manifests.md#configuration)**
3. Optimize with **[Deferred Loading](./topics/deferred-loading.md#strategies)**

### For Architects
1. Study **[Architectural Principles](./topics/progressive-disclosure.md#architectural-principles)**
2. Design **[Capability Systems](./topics/dynamic-manifests.md#capability-systems)**
3. Implement **[Advanced Optimization](./topics/deferred-loading.md#advanced-techniques)**

---

## 🔗 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](./topics/progressive-disclosure.md)**
   - Design philosophy
   - UX patterns
   - Information architecture
   - Cognitive load management

2. **[Dynamic Manifests](./topics/dynamic-manifests.md)**
   - Configuration guide
   - Endpoint implementation
   - Registry patterns
   - MCP-specific setup

3. **[Deferred Loading](./topics/deferred-loading.md)**
   - Lazy initialization
   - Code splitting
   - Resource optimization
   - Caching strategies

---

## 🎯 Quick Wins

Want immediate improvements? Start here:

### 5-Minute Win: Enable Dynamic Discovery
```json
// claude_desktop_config.json
{
  "mcpServers": {
    "your-server": {
      "dynamicDiscovery": true,
      "discoveryInterval": 5000
    }
  }
}
```
See [Dynamic Manifests: Quick Start](./topics/dynamic-manifests.md#quick-start)

### 15-Minute Win: Implement Lazy Loading
```python
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](./topics/deferred-loading.md#basic-patterns)

### 30-Minute Win: Progressive Disclosure UI
```markdown
# 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](./topics/progressive-disclosure.md#ui-patterns)

---

## 📚 Additional Resources

- [MCP Official Spec](https://spec.modelcontextprotocol.io/)
- [Progressive Disclosure (Nielsen Norman Group)](https://www.nngroup.com/articles/progressive-disclosure/)
- [Lazy Loading Best Practices](https://web.dev/lazy-loading/)

---

## 🆘 Troubleshooting

**Problem**: Changes not appearing without restart
**Solution**: Check [Dynamic Manifests: Configuration](./topics/dynamic-manifests.md#configuration)

**Problem**: High memory usage at startup
**Solution**: Review [Deferred Loading: Strategies](./topics/deferred-loading.md#strategies)

**Problem**: Users overwhelmed by options
**Solution**: Apply [Progressive Disclosure: Principles](./topics/progressive-disclosure.md#principles)

---

**Last Updated**: 2025-10-20
**Version**: 1.0.0