@hailer/mcp 0.0.1

package/.claude/skills/agent-building/references/code-examples.md

@@ -0,0 +1,587 @@
+# Code Examples: Skill-Based Agent System
+
+## Complete Working Examples
+
+### Example 1: Basic Skill Loader
+
+```typescript
+// skill-loader.ts
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+export class SkillLoader {
+  private cache = new Map<string, LoadedSkill>();
+  private skillsPath = '.claude/skills/';
+
+  async load(skillName: string): Promise<LoadedSkill> {
+    // Check cache
+    if (this.cache.has(skillName)) {
+      return this.cache.get(skillName)!;
+    }
+
+    // Load from disk
+    const mainPath = path.join(this.skillsPath, skillName, 'SKILL.md');
+    const content = await fs.readFile(mainPath, 'utf-8');
+
+    const skill = { name: skillName, content, loadedAt: Date.now() };
+    this.cache.set(skillName, skill);
+
+    return skill;
+  }
+
+  clearCache() {
+    this.cache.clear();
+  }
+}
+
+// Usage
+const loader = new SkillLoader();
+const skill = await loader.load('mcp-tools');
+console.log(`Loaded ${skill.name}: ${skill.content.length} characters`);
+```
+
+### Example 2: Keyword-Based Skill Manager
+
+```typescript
+// skill-manager.ts
+export class SkillManager {
+  private skillMappings = new Map([
+    ['mcp-tools', {
+      keywords: ['workflow', 'phase', 'field'],
+      tools: ['install_workflow']
+    }],
+    ['hailer-api', {
+      keywords: ['api', 'endpoint', 'activity'],
+      tools: ['list_activities']
+    }]
+  ]);
+
+  constructor(private skillLoader: SkillLoader) {}
+
+  async analyzeRequest(message: string): Promise<SkillGuidance> {
+    const lower = message.toLowerCase();
+    const scores = new Map<string, number>();
+
+    // Score each skill
+    for (const [skillName, mapping] of this.skillMappings) {
+      const score = mapping.keywords.filter(kw =>
+        lower.includes(kw)
+      ).length;
+
+      if (score > 0) {
+        scores.set(skillName, score);
+      }
+    }
+
+    // Get best match
+    const best = Array.from(scores.entries())
+      .sort(([,a], [,b]) => b - a)[0];
+
+    if (!best) {
+      return { skills: [], confidence: 0.3, guidance: 'General' };
+    }
+
+    const [skillName, score] = best;
+    const skill = await this.skillLoader.load(skillName);
+
+    return {
+      skills: [skillName],
+      confidence: score / 3,
+      guidance: `Use ${skillName} expertise`,
+      skillContent: skill.content
+    };
+  }
+}
+
+// Usage
+const manager = new SkillManager(loader);
+const guidance = await manager.analyzeRequest("create a workflow");
+console.log(`Selected skill: ${guidance.skills[0]}`);
+```
+
+### Example 3: Enhanced System Prompt Builder
+
+```typescript
+// In providers/openai-provider.ts
+class OpenAIProvider {
+  private buildSystemPrompt(skillGuidance?: SkillGuidance): string {
+    let prompt = `You are an AI assistant for Hailer workflow management.`;
+
+    if (skillGuidance?.skillContent) {
+      prompt += `\n\n**DOMAIN EXPERTISE:**\n${skillGuidance.skillContent}`;
+      prompt += `\n\n**GUIDANCE:** ${skillGuidance.guidance}`;
+
+      if (skillGuidance.recommendedTools.length > 0) {
+        prompt += `\n\n**RECOMMENDED TOOLS:**\n`;
+        prompt += skillGuidance.recommendedTools.join(', ');
+      }
+    }
+
+    return prompt;
+  }
+
+  async processMessage(
+    message: ChatMessage,
+    skillGuidance?: SkillGuidance
+  ): Promise<void> {
+    const systemPrompt = this.buildSystemPrompt(skillGuidance);
+
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: message.content }
+      ],
+      tools: this.mcpTools
+    });
+
+    // Post response to Hailer...
+  }
+}
+```
+
+### Example 4: Message Processor Integration
+
+```typescript
+// In message-processor.ts
+export class HailerMessageProcessor {
+  private skillLoader = new SkillLoader();
+  private skillManager = new SkillManager(this.skillLoader);
+
+  async processHailerMessage(
+    signal: HailerSignal,
+    botClient: BotClient
+  ): Promise<void> {
+    // Extract message
+    const messages = await this.extractMessage(signal);
+
+    for (const message of messages) {
+      // Analyze request for skills
+      const skillGuidance = await this.skillManager.analyzeRequest(
+        message.content
+      );
+
+      console.log(`Skills selected: ${skillGuidance.skills.join(', ')}`);
+      console.log(`Confidence: ${skillGuidance.confidence}`);
+
+      // Get provider
+      const provider = this.getProvider();
+
+      // Process with skill enhancement
+      await provider.processMessage(message, skillGuidance);
+    }
+  }
+}
+```
+
+## Testing Examples
+
+### Unit Test: Skill Loader
+
+```typescript
+import { SkillLoader } from '../skill-loader';
+
+describe('SkillLoader', () => {
+  let loader: SkillLoader;
+
+  beforeEach(() => {
+    loader = new SkillLoader();
+  });
+
+  it('should load skill from disk', async () => {
+    const skill = await loader.load('mcp-tools');
+
+    expect(skill.name).toBe('mcp-tools');
+    expect(skill.content).toBeTruthy();
+    expect(skill.content.length).toBeGreaterThan(100);
+  });
+
+  it('should cache loaded skills', async () => {
+    const skill1 = await loader.load('mcp-tools');
+    const skill2 = await loader.load('mcp-tools');
+
+    expect(skill1.loadedAt).toBe(skill2.loadedAt);
+  });
+
+  it('should throw error for non-existent skill', async () => {
+    await expect(
+      loader.load('non-existent-skill')
+    ).rejects.toThrow();
+  });
+});
+```
+
+### Unit Test: Skill Manager
+
+```typescript
+import { SkillManager } from '../skill-manager';
+
+describe('SkillManager', () => {
+  let manager: SkillManager;
+  let mockLoader: jest.Mocked<SkillLoader>;
+
+  beforeEach(() => {
+    mockLoader = {
+      load: jest.fn().mockResolvedValue({
+        name: 'mcp-tools',
+        content: 'skill content',
+        loadedAt: Date.now()
+      })
+    } as any;
+
+    manager = new SkillManager(mockLoader);
+  });
+
+  it('should select mcp-tools for workflow requests', async () => {
+    const guidance = await manager.analyzeRequest('create a workflow');
+
+    expect(guidance.skills).toContain('mcp-tools');
+    expect(guidance.confidence).toBeGreaterThan(0.5);
+  });
+
+  it('should select hailer-api for activity requests', async () => {
+    const guidance = await manager.analyzeRequest('list my activities');
+
+    expect(guidance.skills).toContain('hailer-api');
+  });
+
+  it('should return default for unmatched requests', async () => {
+    const guidance = await manager.analyzeRequest('hello');
+
+    expect(guidance.skills).toHaveLength(0);
+    expect(guidance.confidence).toBeLessThan(0.5);
+  });
+});
+```
+
+### Integration Test
+
+```typescript
+describe('Skill System Integration', () => {
+  let processor: HailerMessageProcessor;
+
+  beforeEach(() => {
+    processor = new HailerMessageProcessor(mockManager, [], true);
+  });
+
+  it('should enhance prompts with skill content', async () => {
+    const message = {
+      content: 'help me create a workflow',
+      userId: 'test',
+      discussionId: 'test'
+    };
+
+    const spy = jest.spyOn(processor as any, 'processMessageWithProvider');
+
+    await processor.processHailerMessage(mockSignal, mockBotClient);
+
+    expect(spy).toHaveBeenCalled();
+    const skillGuidance = spy.mock.calls[0][2];
+    expect(skillGuidance.skills).toContain('mcp-tools');
+  });
+});
+```
+
+## Performance Monitoring Examples
+
+### Skill Usage Tracking
+
+```typescript
+class SkillManager {
+  private usageStats = new Map<string, number>();
+
+  async analyzeRequest(message: string): Promise<SkillGuidance> {
+    const guidance = await this.doAnalysis(message);
+
+    // Track usage
+    for (const skill of guidance.skills) {
+      this.usageStats.set(
+        skill,
+        (this.usageStats.get(skill) || 0) + 1
+      );
+    }
+
+    return guidance;
+  }
+
+  getTopSkills(limit = 5): Array<[string, number]> {
+    return Array.from(this.usageStats.entries())
+      .sort(([,a], [,b]) => b - a)
+      .slice(0, limit);
+  }
+}
+
+// Usage
+const topSkills = manager.getTopSkills();
+console.log('Most used skills:', topSkills);
+// Output: [['mcp-tools', 45], ['hailer-api', 32], ...]
+```
+
+### Performance Tracking
+
+```typescript
+class SkillLoader {
+  private loadTimes = new Map<string, number[]>();
+
+  async load(skillName: string): Promise<LoadedSkill> {
+    const start = performance.now();
+
+    const skill = await this.doLoad(skillName);
+
+    const duration = performance.now() - start;
+
+    // Track load time
+    if (!this.loadTimes.has(skillName)) {
+      this.loadTimes.set(skillName, []);
+    }
+    this.loadTimes.get(skillName)!.push(duration);
+
+    return skill;
+  }
+
+  getAverageLoadTime(skillName: string): number {
+    const times = this.loadTimes.get(skillName) || [];
+    if (times.length === 0) return 0;
+    return times.reduce((a, b) => a + b, 0) / times.length;
+  }
+}
+
+// Usage
+console.log(`Average load time: ${loader.getAverageLoadTime('mcp-tools')}ms`);
+```
+
+## Error Handling Examples
+
+### Graceful Degradation
+
+```typescript
+class SkillManager {
+  async analyzeRequest(message: string): Promise<SkillGuidance> {
+    try {
+      const skillName = this.selectSkill(message);
+
+      if (!skillName) {
+        return this.getDefaultGuidance();
+      }
+
+      const skill = await this.skillLoader.load(skillName);
+
+      return {
+        skills: [skillName],
+        confidence: 0.9,
+        skillContent: skill.content
+      };
+    } catch (error) {
+      // Skill loading failed - degrade gracefully
+      this.logger.error('Skill analysis failed', error);
+
+      // Still return guidance, just without skill content
+      return {
+        skills: [],
+        confidence: 0.3,
+        guidance: 'General assistance (skill loading failed)',
+        skillContent: undefined
+      };
+    }
+  }
+}
+```
+
+### Retry Logic
+
+```typescript
+class SkillLoader {
+  async load(skillName: string, retries = 3): Promise<LoadedSkill> {
+    for (let i = 0; i < retries; i++) {
+      try {
+        return await this.doLoad(skillName);
+      } catch (error) {
+        if (i === retries - 1) {
+          // Last retry failed
+          throw new Error(
+            `Failed to load skill '${skillName}' after ${retries} attempts`
+          );
+        }
+
+        // Wait before retry
+        await new Promise(resolve => setTimeout(resolve, 100 * (i + 1)));
+      }
+    }
+
+    throw new Error('Unreachable');
+  }
+}
+```
+
+## Configuration Examples
+
+### Adding New Skill Mapping
+
+```typescript
+// In skill-manager.ts, add to buildSkillMappings():
+[
+  'customer-support',
+  {
+    keywords: [
+      'help', 'support', 'issue', 'problem',
+      'customer', 'user', 'complaint'
+    ],
+    tools: ['create_ticket', 'assign_support'],
+    priority: 1.0
+  }
+]
+```
+
+### Dynamic Skill Registration
+
+```typescript
+class SkillManager {
+  registerSkill(
+    skillName: string,
+    keywords: string[],
+    tools: string[]
+  ): void {
+    this.skillMappings.set(skillName, {
+      keywords,
+      tools,
+      priority: 1.0
+    });
+
+    this.logger.info('Skill registered', { skillName });
+  }
+
+  unregisterSkill(skillName: string): void {
+    this.skillMappings.delete(skillName);
+    this.logger.info('Skill unregistered', { skillName });
+  }
+}
+
+// Usage
+manager.registerSkill(
+  'custom-skill',
+  ['keyword1', 'keyword2'],
+  ['tool1', 'tool2']
+);
+```
+
+## CLI Examples
+
+### Skill Management CLI
+
+```typescript
+// cli/skill-cli.ts
+export class SkillCLI {
+  constructor(private manager: SkillManager) {}
+
+  async listSkills(): Promise<void> {
+    const skills = await this.manager.getAvailableSkills();
+    console.table(skills.map(s => ({ name: s })));
+  }
+
+  async testSkill(message: string): Promise<void> {
+    const guidance = await this.manager.analyzeRequest(message);
+
+    console.log('Analysis Results:');
+    console.log(`  Selected Skills: ${guidance.skills.join(', ')}`);
+    console.log(`  Confidence: ${guidance.confidence}`);
+    console.log(`  Recommended Tools: ${guidance.recommendedTools.join(', ')}`);
+  }
+
+  async showStats(): Promise<void> {
+    const stats = this.manager.getTopSkills();
+
+    console.log('Skill Usage Statistics:');
+    for (const [skill, count] of stats) {
+      console.log(`  ${skill}: ${count} uses`);
+    }
+  }
+}
+
+// Usage
+const cli = new SkillCLI(manager);
+await cli.testSkill("help me create a workflow");
+await cli.showStats();
+```
+
+### NPM Scripts
+
+```json
+{
+  "scripts": {
+    "skills:list": "ts-node cli/skill-cli.ts list",
+    "skills:test": "ts-node cli/skill-cli.ts test",
+    "skills:stats": "ts-node cli/skill-cli.ts stats"
+  }
+}
+```
+
+## Real-World Usage Examples
+
+### Example 1: Workflow Creation Request
+
+```typescript
+// User asks: "Help me create a workflow with phases"
+
+// 1. Skill analysis
+const guidance = await manager.analyzeRequest(
+  "Help me create a workflow with phases"
+);
+
+// Result:
+{
+  skills: ['mcp-tools'],
+  confidence: 0.95,
+  guidance: 'Workflow creation request detected',
+  recommendedTools: ['install_workflow', 'list_workflow_phases'],
+  skillContent: '...full mcp-tools documentation...'
+}
+
+// 2. Enhanced prompt sent to LLM:
+`You are an AI assistant...
+
+DOMAIN EXPERTISE:
+[Full mcp-tools skill content with workflow examples]
+
+GUIDANCE:
+Workflow creation request detected
+
+RECOMMENDED TOOLS:
+install_workflow, list_workflow_phases`
+
+// 3. LLM Response:
+"I'll help you create a workflow. You can use the install_workflow
+tool with the following structure..."
+```
+
+### Example 2: Activity List Request
+
+```typescript
+// User asks: "List all activities from last week"
+
+// 1. Skill analysis
+const guidance = await manager.analyzeRequest(
+  "List all activities from last week"
+);
+
+// Result:
+{
+  skills: ['hailer-api'],
+  confidence: 0.85,
+  guidance: 'API operation request',
+  recommendedTools: ['list_activities'],
+  skillContent: '...hailer-api documentation...'
+}
+
+// 2. Enhanced prompt
+`...
+DOMAIN EXPERTISE:
+[Full hailer-api skill content with filter examples]
+
+RECOMMENDED TOOLS:
+list_activities
+...`
+
+// 3. LLM Response:
+"I'll list activities from last week using the list_activities tool
+with a date range filter..."
+```