Initial commit
This commit is contained in:
Zhongwei Li
272
skills/skill-builder/reference/philosophy.md
Normal file
272
skills/skill-builder/reference/philosophy.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user