@hailer/mcp 0.0.1

package/.claude/skills/agent-building/SKILL.md

@@ -0,0 +1,243 @@
+# Agent Building Skill
+
+This skill provides comprehensive guidance for building skill-based autonomous agent systems, specifically for the Hailer MCP (Model Context Protocol) server architecture.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building or modifying agent systems with dynamic skill loading
+- Implementing autonomous agents that work with Hailer
+- Adding skill-based expertise to LLM agents
+- Understanding agent architecture patterns
+- Troubleshooting agent concurrency or performance issues
+
+## Core Concepts
+
+### Skill-Based Agent Architecture
+
+Instead of creating multiple specialized agent instances, we use **one agent with dynamic skill loading**:
+
+```
+Single Agent + Dynamic Skills = Multiple Expertise Domains
+```
+
+**Key Principle**: The agent analyzes each request and loads relevant skills on-demand, becoming an expert in that domain for that specific request.
+
+### Why This Approach?
+
+✅ **One Hailer Account** - No need for multiple bot user accounts
+✅ **Concurrent by Default** - Node.js handles multiple requests naturally
+✅ **Cost-Effective** - Single LLM call per request (no extra analysis call)
+✅ **Lightweight** - Rule-based skill matching (~1-5ms overhead)
+✅ **Maintainable** - Update skills without touching agent code
+✅ **Scalable** - Add new skills easily
+
+### Architecture Components
+
+1. **Skill Loader** - Reads skill files from disk, caches in memory
+2. **Skill Manager** - Analyzes requests using keyword matching, selects skills
+3. **Message Processor** - Integrates skill selection into message flow
+4. **LLM Provider** - Uses skill content to enhance system prompts
+
+## Quick Reference
+
+### Skill System Flow
+
+```
+User Message
+    ↓
+Skill Manager Analyzes (keyword matching)
+    ↓
+Skill Loader Loads Relevant Skills (cached)
+    ↓
+Enhanced System Prompt (with skill content)
+    ↓
+LLM Responds with Expertise
+```
+
+### Performance Characteristics
+
+- **Skill Analysis**: 1-5ms (keyword matching)
+- **Skill Loading**: 10-50ms first time, 0ms cached
+- **Total Overhead**: ~15-55ms (negligible)
+- **LLM Calls**: 1 per request (same as without skills)
+- **Cost**: No additional cost
+
+### Concurrency Model
+
+**Node.js handles concurrent requests naturally**:
+- Each request is processed independently (async/await)
+- No shared state between requests
+- All requests can be in-flight simultaneously
+- Bottleneck is LLM API, not agent code
+
+Single agent easily handles 100+ concurrent users without issues.
+
+## Architecture Patterns
+
+See [architecture-patterns.md](references/architecture-patterns.md) for:
+- Current vs Future state diagrams
+- Component relationships
+- Data flow patterns
+- Integration points
+
+## Skill System Details
+
+See [skill-system.md](references/skill-system.md) for:
+- How Skill Loader works
+- Keyword mapping strategies
+- Caching mechanisms
+- Skill file structure
+
+## Implementation Guide
+
+See [implementation-guide.md](references/implementation-guide.md) for:
+- Step-by-step build instructions
+- File modifications required
+- Configuration changes
+- Testing procedures
+
+## Code Examples
+
+See [code-examples.md](references/code-examples.md) for:
+- Complete working implementations
+- Integration patterns
+- Error handling
+- Testing examples
+
+## Key Design Decisions
+
+### Why Single Agent Instead of Multiple?
+
+**Multiple Agent Instances** (❌ Not Recommended):
+```
+Agent 1 (workflow-bot@company.com) → Skills A, B
+Agent 2 (data-bot@company.com) → Skills C, D
+Agent 3 (general-bot@company.com) → Skill E
+
+Issues:
+- Requires multiple Hailer accounts
+- More complex configuration
+- Same concurrency (Node.js handles it either way)
+- Harder to maintain
+```
+
+**Single Agent with Dynamic Skills** (✅ Recommended):
+```
+One Agent (user@company.com)
+  - Workflow request → loads skills A, B
+  - Data request → loads skills C, D
+  - General request → loads skill E
+
+Benefits:
+- One Hailer account
+- Simple configuration
+- Natural concurrency handling
+- Easy maintenance
+```
+
+### Why Rule-Based Matching Instead of LLM Analysis?
+
+**LLM-Based Skill Selection** (❌ Expensive):
+```
+User message → LLM analyzes (call #1) → picks skills
+            → Hailer Agent responds (call #2)
+
+Cost: 2x LLM calls per message
+Latency: 2x response time
+```
+
+**Rule-Based Skill Selection** (✅ Efficient):
+```
+User message → Keyword matching (1-5ms) → picks skills
+            → Hailer Agent responds (call #1)
+
+Cost: Same as before
+Latency: +15-55ms (negligible)
+```
+
+### Why Extend Existing Config Instead of New Files?
+
+**Configuration should live in `.env.local`** because:
+- Already parsed by existing config system
+- Git-ignored (credentials safe)
+- Single source of truth
+- Type-safe with Zod validation
+- No additional files to manage
+
+## Common Pitfalls to Avoid
+
+❌ **Don't** create multiple Hailer accounts unless you have specific reasons (rate limits, permissions)
+❌ **Don't** use LLM for skill selection (expensive, unnecessary)
+❌ **Don't** create separate config files (use existing `.env.local`)
+❌ **Don't** worry about concurrency with single agent (Node.js handles it)
+❌ **Don't** add shared state between requests (breaks concurrent processing)
+
+✅ **Do** use keyword-based skill matching (fast, free)
+✅ **Do** cache skills in memory (avoid repeated file reads)
+✅ **Do** keep agents stateless (each request independent)
+✅ **Do** use existing configuration systems
+✅ **Do** measure performance before optimizing
+
+## Testing Strategy
+
+1. **Unit Tests** - Test Skill Loader and Skill Manager independently
+2. **Integration Tests** - Test skill selection with real messages
+3. **E2E Tests** - Test full flow from Hailer message to response
+4. **Load Tests** - Verify concurrent request handling
+5. **Manual Tests** - Use Claude terminal to test different requests
+
+## Troubleshooting
+
+**Skills not loading?**
+- Check `.claude/skills/` directory exists
+- Verify skill files are readable
+- Check skill cache (may need restart)
+
+**Wrong skills loaded?**
+- Review keyword mappings in skill-manager.ts
+- Add more specific keywords
+- Check message content parsing
+
+**Performance issues?**
+- Verify skills are cached (shouldn't reload each time)
+- Check LLM API response times (likely bottleneck)
+- Monitor concurrent request counts
+
+**Concurrency problems?**
+- Check for shared state in agent code
+- Verify async/await used correctly
+- Look for blocking operations
+
+## Next Steps
+
+After implementing the skill system:
+1. Monitor skill selection accuracy
+2. Refine keyword mappings based on usage
+3. Add new skills as needed
+4. Consider A/B testing responses with/without skills
+5. Collect metrics on skill usage frequency
+
+## Related Skills
+
+- **mcp-tools**: For understanding MCP tool development
+- **hailer-api**: For Hailer API integration details
+
+## Maintenance
+
+**Adding New Skills**:
+1. Create skill directory in `.claude/skills/`
+2. Write SKILL.md and reference docs
+3. Add keyword mappings to skill-manager.ts
+4. Test with sample messages
+5. Deploy
+
+**Updating Skills**:
+1. Edit skill markdown files
+2. Restart server (clears cache)
+3. Test changes
+
+**Removing Skills**:
+1. Remove directory from `.claude/skills/`
+2. Remove keyword mappings from skill-manager.ts
+3. Restart server

package/.claude/skills/agent-building/references/architecture-patterns.md

@@ -0,0 +1,446 @@
+# Architecture Patterns for Skill-Based Agents
+
+## Core Architecture Pattern
+
+### Component Diagram
+
+```
+┌──────────────────────────────────────────┐
+│   User in Hailer                         │
+│   "Help me create a workflow"            │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Hailer Socket.io Signal                │
+│   messenger.new event                    │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   MCP Client                             │
+│   Receives signal, extracts message      │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Message Processor                      │
+│   Parses message content                 │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Skill Manager (NEW)                    │
+│   analyzeRequest(message)                │
+│   - Keywords: workflow, create            │
+│   - Selected: 'mcp-tools'                │
+│   - Confidence: 0.9                      │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Skill Loader (NEW)                     │
+│   load('mcp-tools')                      │
+│   - Reads .claude/skills/mcp-tools/      │
+│   - Returns full skill content           │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Enhanced System Prompt                 │
+│   Base prompt + skill content            │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   LLM Provider (OpenAI/Anthropic)        │
+│   Sends enhanced prompt to LLM           │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   LLM Response                           │
+│   Expert answer about workflows          │
+└─────────────────┬────────────────────────┘
+                  │
+                  ▼
+┌──────────────────────────────────────────┐
+│   Posted to Hailer                       │
+│   User sees response                     │
+└──────────────────────────────────────────┘
+```
+
+## Data Flow Patterns
+
+### Request Processing Flow
+
+```typescript
+// 1. Message arrives
+const signal = { type: 'messenger.new', data: {...} };
+
+// 2. Extract message
+const message = {
+  content: "Help me create a workflow",
+  userId: "user123",
+  discussionId: "disc456"
+};
+
+// 3. Analyze with Skill Manager
+const guidance = {
+  skills: ['mcp-tools'],
+  confidence: 0.9,
+  guidance: "Workflow creation request",
+  recommendedTools: ['install_workflow'],
+  skillContent: "...full mcp-tools skill content..."
+};
+
+// 4. Build enhanced prompt
+const systemPrompt = `
+You are an AI assistant...
+
+DOMAIN EXPERTISE:
+${guidance.skillContent}
+
+GUIDANCE:
+${guidance.guidance}
+`;
+
+// 5. Send to LLM
+const response = await llm.chat({
+  messages: [
+    { role: 'system', content: systemPrompt },
+    { role: 'user', content: message.content }
+  ]
+});
+
+// 6. Post response
+await hailer.postMessage(response);
+```
+
+## Concurrency Pattern
+
+### How Multiple Requests are Handled
+
+```javascript
+// Time: 0ms
+handleMessage(userA, "create workflow")
+  ↓ starts async execution
+  ↓ skill analysis: 5ms
+  ↓ skill loading: 10ms (cached after first)
+  ↓ LLM call starts...
+  ⏳ waiting for LLM (2000ms)
+
+// Time: 100ms (while A is waiting for LLM)
+handleMessage(userB, "list activities")
+  ↓ starts async execution (doesn't block A!)
+  ↓ skill analysis: 5ms
+  ↓ skill loading: 0ms (cached)
+  ↓ LLM call starts...
+  ⏳ waiting for LLM (2000ms)
+
+// Time: 200ms (while A and B waiting)
+handleMessage(userC, "analyze data")
+  ↓ starts async execution (doesn't block!)
+  ↓ skill analysis: 5ms
+  ↓ skill loading: 0ms (cached)
+  ↓ LLM call starts...
+  ⏳ waiting for LLM (2000ms)
+
+// All 3 requests processed concurrently!
+// Responses arrive as LLMs complete
+```
+
+### Key Points
+
+- **Async/Await**: Each request is independent
+- **No Blocking**: Requests don't wait for each other
+- **Stateless**: No shared state between requests
+- **Concurrent LLM Calls**: All 3 LLM calls happen simultaneously
+
+## Integration Points
+
+### Existing Components (Don't Modify)
+
+```
+✅ MCP Client (mcp-client.ts)
+   - Receives Hailer signals
+   - Manages bot lifecycle
+
+✅ Multi-Bot Manager (multi-bot-manager.ts)
+   - Manages bot connections
+   - Already supports multiple bots
+
+✅ Signal Handler (signal-handler.ts)
+   - Handles socket.io signals
+   - Subscription management
+```
+
+### Components to Modify
+
+```
+📝 Message Processor (message-processor.ts)
+   ADD: Skill manager calls
+   ADD: Pass skill context to provider
+
+📝 LLM Providers (openai-provider.ts, anthropic-provider.ts)
+   ADD: Accept skill guidance parameter
+   MODIFY: Build enhanced system prompts
+```
+
+### Components to Create
+
+```
+✨ Skill Loader (skill-loader.ts)
+   NEW: Load skill files from disk
+   NEW: Cache skills in memory
+
+✨ Skill Manager (skill-manager.ts)
+   NEW: Analyze requests
+   NEW: Select appropriate skills
+```
+
+## Design Patterns Used
+
+### 1. Strategy Pattern (Skill Selection)
+
+```typescript
+interface SkillMatcher {
+  match(message: string): boolean;
+  getSkillName(): string;
+}
+
+// Different matching strategies
+class KeywordMatcher implements SkillMatcher { ... }
+class RegexMatcher implements SkillMatcher { ... }
+class MLMatcher implements SkillMatcher { ... }
+```
+
+### 2. Cache Pattern (Skill Loading)
+
+```typescript
+class SkillLoader {
+  private cache = new Map<string, LoadedSkill>();
+
+  async load(name: string): Promise<LoadedSkill> {
+    if (this.cache.has(name)) {
+      return this.cache.get(name)!; // O(1) retrieval
+    }
+
+    const skill = await this.loadFromDisk(name);
+    this.cache.set(name, skill);
+    return skill;
+  }
+}
+```
+
+### 3. Decorator Pattern (Enhanced Prompts)
+
+```typescript
+// Base prompt
+const basePrompt = "You are an AI assistant...";
+
+// Decorated with skill content
+const enhancedPrompt = `
+${basePrompt}
+
+DOMAIN EXPERTISE:
+${skillContent}
+`;
+```
+
+### 4. Factory Pattern (Provider Selection)
+
+```typescript
+// Already exists in current architecture
+class ProviderFactory {
+  createProvider(type: string): LlmProvider {
+    switch(type) {
+      case 'openai': return new OpenAIProvider();
+      case 'anthropic': return new AnthropicProvider();
+    }
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Graceful Degradation
+
+```typescript
+async analyzeRequest(message: string): Promise<SkillGuidance> {
+  try {
+    // Try to load skill
+    const skill = await this.skillLoader.load(skillName);
+    return { ...guidance, skillContent: skill.content };
+  } catch (error) {
+    // Skill loading failed - degrade gracefully
+    logger.error('Skill loading failed', error);
+    return { ...guidance, skillContent: undefined };
+    // Agent still works, just without skill enhancement
+  }
+}
+```
+
+### Fallback Pattern
+
+```typescript
+async analyzeRequest(message: string): Promise<SkillGuidance> {
+  const primarySkill = this.selectPrimarySkill(message);
+
+  if (!primarySkill) {
+    // No skill matched - use default
+    return this.getDefaultGuidance();
+  }
+
+  try {
+    return await this.loadSkillGuidance(primarySkill);
+  } catch (error) {
+    // Primary skill failed - try fallback
+    logger.warn('Primary skill failed, using fallback');
+    return this.getDefaultGuidance();
+  }
+}
+```
+
+## Performance Patterns
+
+### Lazy Loading
+
+```typescript
+// Skills only loaded when needed
+class SkillManager {
+  async analyzeRequest(message: string) {
+    // 1. Quick keyword analysis (1-5ms)
+    const skillName = this.selectSkill(message);
+
+    // 2. Only load if skill selected
+    if (skillName) {
+      const skill = await this.skillLoader.load(skillName);
+    }
+  }
+}
+```
+
+### Eager Caching
+
+```typescript
+// Preload common skills on startup
+class SkillLoader {
+  async preloadCommonSkills() {
+    await Promise.all([
+      this.load('mcp-tools'),
+      this.load('hailer-api')
+    ]);
+    // Now cached for instant retrieval
+  }
+}
+```
+
+## Scalability Patterns
+
+### Horizontal Scaling
+
+```
+Load Balancer
+    ├─ Server 1 (Agent + Skills)
+    ├─ Server 2 (Agent + Skills)
+    └─ Server 3 (Agent + Skills)
+
+Each server:
+- Has its own skill cache
+- Handles subset of users
+- Shares same skill files (via NFS/S3)
+```
+
+### Vertical Scaling
+
+```
+Single Server
+├─ Agent Instance (handles all requests)
+├─ Skill Cache (shared in memory)
+└─ LLM Provider (concurrent API calls)
+
+Handles 100+ concurrent users easily
+```
+
+## Testing Patterns
+
+### Unit Testing
+
+```typescript
+describe('SkillManager', () => {
+  it('selects correct skill', async () => {
+    const manager = new SkillManager(mockLoader);
+    const guidance = await manager.analyzeRequest("create workflow");
+    expect(guidance.skills).toContain('mcp-tools');
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+describe('Message Flow', () => {
+  it('enhances prompts with skills', async () => {
+    const processor = new MessageProcessor(mockManager);
+    const result = await processor.process(mockMessage);
+    expect(result.systemPrompt).toContain('DOMAIN EXPERTISE');
+  });
+});
+```
+
+### E2E Testing
+
+```typescript
+describe('Hailer Integration', () => {
+  it('responds with skill-enhanced answers', async () => {
+    await sendHailerMessage("create workflow");
+    const response = await waitForResponse();
+    expect(response).toContain('install_workflow');
+  });
+});
+```
+
+## Monitoring Patterns
+
+### Skill Usage Metrics
+
+```typescript
+class SkillManager {
+  private metrics = new Map<string, number>();
+
+  async analyzeRequest(message: string) {
+    const guidance = ...;
+
+    // Track usage
+    for (const skill of guidance.skills) {
+      this.metrics.set(skill, (this.metrics.get(skill) || 0) + 1);
+    }
+
+    return guidance;
+  }
+
+  getMetrics() {
+    return Array.from(this.metrics.entries())
+      .sort(([,a], [,b]) => b - a);
+  }
+}
+```
+
+### Performance Tracking
+
+```typescript
+async analyzeRequest(message: string) {
+  const start = Date.now();
+  const guidance = await this.doAnalysis(message);
+  const duration = Date.now() - start;
+
+  this.logger.info('Skill analysis complete', {
+    duration,
+    selectedSkills: guidance.skills,
+    confidence: guidance.confidence
+  });
+
+  return guidance;
+}
+```