@hailer/mcp 0.0.1

package/.claude/skills/agent-building/references/implementation-guide.md

@@ -0,0 +1,619 @@
+# Implementation Guide: Skill-Based Agent System
+
+This document provides step-by-step instructions for implementing a skill-based agent system in the Hailer MCP server.
+
+## Prerequisites
+
+- Existing Hailer MCP server running
+- Node.js and TypeScript environment
+- Basic understanding of async/await patterns
+- Access to `.claude/skills/` directory with existing skills
+
+## Implementation Overview
+
+**Total Time**: ~1 hour
+**Difficulty**: Medium
+**Files to Create**: 2 new files
+**Files to Modify**: 3 existing files
+
+## Step 1: Create Skill Loader
+
+**File**: `server/src/client/skill-loader.ts`
+**Time**: ~15 minutes
+**Purpose**: Load skill files from disk and cache them
+
+### Implementation
+
+```typescript
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { createLogger } from '../lib/logger';
+
+export interface LoadedSkill {
+  name: string;
+  content: string;
+  description: string;
+  loadedAt: number;
+}
+
+export class SkillLoader {
+  private skillsPath: string;
+  private cache = new Map<string, LoadedSkill>();
+  private logger = createLogger({ component: 'skill-loader' });
+
+  constructor(skillsPath: string = '.claude/skills/') {
+    this.skillsPath = skillsPath;
+  }
+
+  /**
+   * Load multiple skills at once
+   */
+  async loadMultiple(skillNames: string[]): Promise<LoadedSkill[]> {
+    return Promise.all(skillNames.map(name => this.load(name)));
+  }
+
+  /**
+   * Load a single skill by name
+   */
+  async load(skillName: string): Promise<LoadedSkill> {
+    // Check cache first
+    if (this.cache.has(skillName)) {
+      this.logger.debug('Skill loaded from cache', { skillName });
+      return this.cache.get(skillName)!;
+    }
+
+    try {
+      const skillPath = path.join(this.skillsPath, skillName);
+
+      // Load main SKILL.md
+      const mainPath = path.join(skillPath, 'SKILL.md');
+      let content = await fs.readFile(mainPath, 'utf-8');
+
+      // Load reference files if they exist
+      const referencesPath = path.join(skillPath, 'references');
+      try {
+        const files = await fs.readdir(referencesPath);
+        for (const file of files.filter(f => f.endsWith('.md'))) {
+          const refContent = await fs.readFile(
+            path.join(referencesPath, file),
+            'utf-8'
+          );
+          content += `\n\n## ${file.replace('.md', '')}\n\n${refContent}`;
+        }
+      } catch (error) {
+        // References directory doesn't exist or is empty - that's ok
+      }
+
+      const skill: LoadedSkill = {
+        name: skillName,
+        content,
+        description: this.extractDescription(content),
+        loadedAt: Date.now()
+      };
+
+      this.cache.set(skillName, skill);
+      this.logger.info('Skill loaded successfully', {
+        skillName,
+        contentLength: content.length
+      });
+
+      return skill;
+    } catch (error) {
+      this.logger.error('Failed to load skill', error, { skillName });
+      throw new Error(`Failed to load skill '${skillName}': ${error}`);
+    }
+  }
+
+  /**
+   * Extract description from skill content (first paragraph)
+   */
+  private extractDescription(content: string): string {
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        return trimmed.slice(0, 200);
+      }
+    }
+    return '';
+  }
+
+  /**
+   * Clear cache for a specific skill or all skills
+   */
+  clearCache(skillName?: string): void {
+    if (skillName) {
+      this.cache.delete(skillName);
+      this.logger.debug('Skill cache cleared', { skillName });
+    } else {
+      this.cache.clear();
+      this.logger.debug('All skill caches cleared');
+    }
+  }
+
+  /**
+   * Get list of available skills
+   */
+  async getAvailableSkills(): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(this.skillsPath, { withFileTypes: true });
+      return entries
+        .filter(entry => entry.isDirectory())
+        .map(entry => entry.name);
+    } catch (error) {
+      this.logger.error('Failed to list available skills', error);
+      return [];
+    }
+  }
+}
+```
+
+### Testing
+
+```typescript
+// Quick test
+const loader = new SkillLoader();
+const skill = await loader.load('mcp-tools');
+console.log(`Loaded skill: ${skill.name}`);
+console.log(`Content length: ${skill.content.length}`);
+```
+
+## Step 2: Create Skill Manager
+
+**File**: `server/src/client/skill-manager.ts`
+**Time**: ~20 minutes
+**Purpose**: Analyze requests and select appropriate skills
+
+### Implementation
+
+```typescript
+import { SkillLoader, LoadedSkill } from './skill-loader';
+import { createLogger } from '../lib/logger';
+
+export interface SkillGuidance {
+  skills: string[];
+  confidence: number;
+  guidance: string;
+  recommendedTools: string[];
+  skillContent?: string;
+}
+
+interface SkillMapping {
+  keywords: string[];
+  tools: string[];
+  priority?: number;
+}
+
+export class SkillManager {
+  private skillLoader: SkillLoader;
+  private skillMappings: Map<string, SkillMapping>;
+  private logger = createLogger({ component: 'skill-manager' });
+
+  constructor(skillLoader: SkillLoader) {
+    this.skillLoader = skillLoader;
+    this.skillMappings = this.buildSkillMappings();
+  }
+
+  /**
+   * Analyze a user request and determine which skills to load
+   */
+  async analyzeRequest(message: string): Promise<SkillGuidance> {
+    const lower = message.toLowerCase();
+    const scores = new Map<string, number>();
+
+    // Score each skill based on keyword matches
+    for (const [skillName, mapping] of this.skillMappings) {
+      let score = 0;
+      for (const keyword of mapping.keywords) {
+        if (lower.includes(keyword.toLowerCase())) {
+          score += 1;
+          // Bonus for exact matches
+          if (lower.includes(` ${keyword.toLowerCase()} `)) {
+            score += 0.5;
+          }
+        }
+      }
+
+      // Apply priority multiplier
+      if (mapping.priority) {
+        score *= mapping.priority;
+      }
+
+      if (score > 0) {
+        scores.set(skillName, score);
+      }
+    }
+
+    // Get best matching skills (up to 2)
+    const sortedSkills = Array.from(scores.entries())
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 2);
+
+    if (sortedSkills.length === 0) {
+      // No specific skill matched - use general
+      return await this.getDefaultGuidance();
+    }
+
+    const primarySkill = sortedSkills[0];
+    const [skillName, score] = primarySkill;
+    const mapping = this.skillMappings.get(skillName)!;
+
+    // Load the primary skill
+    const loadedSkills = await this.skillLoader.loadMultiple([skillName]);
+
+    this.logger.info('Skills selected', {
+      message: message.slice(0, 50),
+      selectedSkills: [skillName],
+      confidence: score
+    });
+
+    return {
+      skills: [skillName],
+      confidence: Math.min(score / 3, 1.0), // Normalize
+      guidance: this.buildGuidance(skillName, message),
+      recommendedTools: mapping.tools,
+      skillContent: loadedSkills[0]?.content
+    };
+  }
+
+  /**
+   * Define keyword mappings for each skill
+   */
+  private buildSkillMappings(): Map<string, SkillMapping> {
+    return new Map([
+      [
+        'mcp-tools',
+        {
+          keywords: [
+            'workflow', 'phase', 'field', 'schema',
+            'create workflow', 'install workflow',
+            'workflow template', 'workflow structure',
+            'activity field', 'workflow phase'
+          ],
+          tools: [
+            'install_workflow',
+            'list_workflow_phases',
+            'get_workflow_schema',
+            'update_workflow_field'
+          ],
+          priority: 1.2
+        }
+      ],
+      [
+        'hailer-api',
+        {
+          keywords: [
+            'api', 'endpoint', 'activity', 'list activities',
+            'filter', 'search', 'show activity',
+            'discussion', 'message', 'fetch'
+          ],
+          tools: [
+            'list_activities',
+            'show_activity_by_id',
+            'fetch_discussion_messages',
+            'add_discussion_message'
+          ],
+          priority: 1.0
+        }
+      ],
+      [
+        'data-analysis',
+        {
+          keywords: [
+            'analyze', 'report', 'statistics', 'trends',
+            'insights', 'metrics', 'summary',
+            'count', 'aggregate'
+          ],
+          tools: ['list_activities'],
+          priority: 0.8
+        }
+      ],
+      [
+        'agent-building',
+        {
+          keywords: [
+            'build agent', 'create agent', 'agent system',
+            'skill system', 'autonomous agent',
+            'agent architecture', 'multi-agent'
+          ],
+          tools: [],
+          priority: 1.0
+        }
+      ]
+    ]);
+  }
+
+  /**
+   * Build guidance text for a skill
+   */
+  private buildGuidance(skillName: string, message: string): string {
+    const guidanceMap: Record<string, string> = {
+      'mcp-tools': 'This request involves workflow/schema operations. Use the workflow management tools available.',
+      'hailer-api': 'This request involves Hailer API operations. Use the appropriate API endpoints.',
+      'data-analysis': 'This request involves data analysis. Gather data using list_activities and analyze it.',
+      'agent-building': 'This request is about building agent systems. Reference the skill system architecture.'
+    };
+
+    return guidanceMap[skillName] || 'Use available tools to help the user.';
+  }
+
+  /**
+   * Get default guidance when no specific skill matches
+   */
+  private async getDefaultGuidance(): Promise<SkillGuidance> {
+    this.logger.debug('No specific skill matched, using default');
+
+    return {
+      skills: [],
+      confidence: 0.3,
+      guidance: 'General assistance request. Use available tools as needed.',
+      recommendedTools: [],
+      skillContent: undefined
+    };
+  }
+
+  /**
+   * Add or update a skill mapping
+   */
+  addSkillMapping(skillName: string, mapping: SkillMapping): void {
+    this.skillMappings.set(skillName, mapping);
+    this.logger.info('Skill mapping added', { skillName });
+  }
+}
+```
+
+### Testing
+
+```typescript
+// Quick test
+const loader = new SkillLoader();
+const manager = new SkillManager(loader);
+
+const guidance1 = await manager.analyzeRequest("Help me create a workflow");
+console.log('Guidance:', guidance1);
+// Should select 'mcp-tools' skill
+
+const guidance2 = await manager.analyzeRequest("List my activities");
+console.log('Guidance:', guidance2);
+// Should select 'hailer-api' skill
+```
+
+## Step 3: Modify Message Processor
+
+**File**: `server/src/client/message-processor.ts`
+**Time**: ~10 minutes
+**Purpose**: Integrate skill manager into message flow
+
+### Changes Needed
+
+1. Import new classes
+2. Add skill manager instance
+3. Call skill manager before processing
+4. Pass skill context to provider
+
+### Implementation
+
+```typescript
+// At top of file, add imports:
+import { SkillLoader } from './skill-loader';
+import { SkillManager } from './skill-manager';
+
+// In class HailerMessageProcessor:
+export class HailerMessageProcessor implements MessageProcessor {
+  // ... existing properties ...
+
+  // ADD these new properties:
+  private skillLoader: SkillLoader;
+  private skillManager: SkillManager;
+
+  constructor(
+    multiBotManager: MultiBotManager,
+    mcpAgentIds: string[],
+    enableDirectMessages: boolean
+  ) {
+    // ... existing constructor code ...
+
+    // ADD skill system initialization:
+    this.skillLoader = new SkillLoader();
+    this.skillManager = new SkillManager(this.skillLoader);
+  }
+
+  // MODIFY the processHailerMessage method:
+  async processHailerMessage(
+    signal: HailerSignal,
+    botClient: BotClient
+  ): Promise<void> {
+    // ... existing message extraction code ...
+
+    for (const message of messages) {
+      // ADD skill analysis before provider call:
+      const skillGuidance = await this.skillManager.analyzeRequest(
+        message.content
+      );
+
+      // Pass to provider with skill context
+      await this.processMessageWithProvider(
+        message,
+        botClient,
+        skillGuidance  // NEW parameter
+      );
+    }
+  }
+
+  // MODIFY to accept skill guidance:
+  private async processMessageWithProvider(
+    message: ChatMessage,
+    botClient: BotClient,
+    skillGuidance: SkillGuidance  // NEW parameter
+  ): Promise<void> {
+    // ... existing provider selection code ...
+
+    // Pass skill guidance to provider
+    await provider.processMessage(message, skillGuidance);
+  }
+}
+```
+
+## Step 4: Modify LLM Providers
+
+**Files**:
+- `server/src/client/providers/openai-provider.ts`
+- `server/src/client/providers/anthropic-provider.ts`
+
+**Time**: ~15 minutes total
+**Purpose**: Use skill content in system prompts
+
+### Changes for OpenAI Provider
+
+```typescript
+import { SkillGuidance } from '../skill-manager';
+
+export class OpenAIProvider extends LlmProvider {
+  // MODIFY processMessage to accept skill guidance:
+  async processMessage(
+    message: ChatMessage,
+    skillGuidance?: SkillGuidance  // NEW optional parameter
+  ): Promise<void> {
+    // Build enhanced system prompt
+    const systemPrompt = this.buildSystemPrompt(skillGuidance);
+
+    // ... rest of existing code uses systemPrompt ...
+  }
+
+  // ADD method to build enhanced system prompt:
+  private buildSystemPrompt(skillGuidance?: SkillGuidance): string {
+    let prompt = `You are an AI assistant for Hailer workflow management.
+
+You have access to MCP tools that can interact with the Hailer platform.
+Use these tools to help users effectively.`;
+
+    // Add skill content if available
+    if (skillGuidance?.skillContent) {
+      prompt += `\n\n**DOMAIN EXPERTISE FOR THIS REQUEST:**
+${skillGuidance.skillContent}
+
+**GUIDANCE:**
+${skillGuidance.guidance}`;
+
+      if (skillGuidance.recommendedTools.length > 0) {
+        prompt += `\n\n**RECOMMENDED TOOLS:**
+${skillGuidance.recommendedTools.join(', ')}
+
+Consider using these tools to best address the user's request.`;
+      }
+    }
+
+    return prompt;
+  }
+}
+```
+
+### Changes for Anthropic Provider
+
+Same pattern - add `skillGuidance` parameter and build enhanced prompt.
+
+## Step 5: Testing
+
+**Time**: ~10 minutes
+
+### Unit Tests
+
+```typescript
+// test/skill-loader.test.ts
+describe('SkillLoader', () => {
+  it('should load skill from disk', async () => {
+    const loader = new SkillLoader();
+    const skill = await loader.load('mcp-tools');
+    expect(skill.name).toBe('mcp-tools');
+    expect(skill.content).toContain('workflow');
+  });
+
+  it('should cache skills', async () => {
+    const loader = new SkillLoader();
+    const skill1 = await loader.load('mcp-tools');
+    const skill2 = await loader.load('mcp-tools');
+    expect(skill1.loadedAt).toBe(skill2.loadedAt);
+  });
+});
+
+// test/skill-manager.test.ts
+describe('SkillManager', () => {
+  it('should select workflow skill for workflow requests', async () => {
+    const loader = new SkillLoader();
+    const manager = new SkillManager(loader);
+
+    const guidance = await manager.analyzeRequest("create a workflow");
+    expect(guidance.skills).toContain('mcp-tools');
+  });
+});
+```
+
+### Integration Test
+
+```bash
+# Start server
+cd server && npm run dev
+
+# In another terminal, test with Hailer
+# Send message: "Help me create a workflow"
+# Verify response includes workflow expertise
+```
+
+## Rollback Plan
+
+If something goes wrong:
+
+```bash
+# Remove new files
+rm server/src/client/skill-loader.ts
+rm server/src/client/skill-manager.ts
+
+# Revert modified files
+git checkout server/src/client/message-processor.ts
+git checkout server/src/client/providers/
+
+# Restart server
+npm run dev
+```
+
+## Configuration
+
+No configuration changes needed! The system works with existing `.env.local`.
+
+Optional: Add skill configuration to `.env.local`:
+
+```bash
+# Optional: Configure available skills
+AVAILABLE_SKILLS=mcp-tools,hailer-api,data-analysis,agent-building
+```
+
+## Deployment Checklist
+
+- [ ] SkillLoader implemented and tested
+- [ ] SkillManager implemented and tested
+- [ ] Message processor modified
+- [ ] LLM providers modified
+- [ ] Unit tests passing
+- [ ] Integration tests passing
+- [ ] Skills exist in `.claude/skills/` directory
+- [ ] Server starts without errors
+- [ ] Test messages produce skill-enhanced responses
+- [ ] Performance overhead < 100ms
+- [ ] No breaking changes to existing functionality
+
+## Next Steps After Implementation
+
+1. Monitor skill selection accuracy
+2. Add more keyword mappings based on usage
+3. Create additional skills as needed
+4. Implement skill usage analytics
+5. A/B test responses with/without skills
+
+## Support
+
+If you encounter issues:
+1. Check logs for skill loading errors
+2. Verify skill files exist and are readable
+3. Test skill loader and manager independently
+4. Review keyword mappings
+5. Check for TypeScript compilation errors