claude-code-router-config 1.0.0 → 1.1.0

package/docs/AGENTSKILLS_SETUP.md

@@ -0,0 +1,743 @@
+# AgentSkills Setup Guide
+
+## Quick Start
+
+This guide provides step-by-step instructions for integrating AgentSkills into your Claude Code Router configuration.
+
+## Prerequisites
+
+- Working Claude Code Router installation (see Homebrew setup)
+- Anthropic API key with Claude Sonnet 4 access
+- Node.js 16+ and pnpm installed
+- Basic understanding of JSON and JavaScript configuration
+
+## Step 1: Update Configuration Files
+
+### 1.1 Update config.json
+
+Add AgentSkills as a new provider:
+
+```bash
+# Backup current config
+cp ~/.claude-code-router/config.json ~/.claude-code-router/config.json.backup
+```
+
+Edit `~/.claude-code-router/config.json` and add the AgentSkills provider:
+
+```json
+{
+  "_comment": "Claude Code Router Configuration with AgentSkills Integration",
+  "_attribution": "Original project: https://github.com/musistudio/claude-code-router",
+  "_author": "Configuration by Halil Ertekin",
+  "LOG": true,
+  "LOG_LEVEL": "info",
+  "API_TIMEOUT_MS": 300000,
+  "CUSTOM_ROUTER_PATH": "$HOME/.claude-code-router/intent-router.js",
+
+  "Providers": [
+    {
+      "name": "openai",
+      "api_base_url": "https://api.openai.com/v1/chat/completions",
+      "api_key": "$OPENAI_API_KEY",
+      "models": ["gpt-4o", "gpt-4-turbo", "gpt-4o-mini", "o1", "o1-mini"],
+      "transformer": { "use": [] }
+    },
+    {
+      "name": "anthropic",
+      "api_base_url": "https://api.anthropic.com/v1/messages",
+      "api_key": "$ANTHROPIC_API_KEY",
+      "models": ["claude-sonnet-4-latest", "claude-3-5-sonnet-latest"],
+      "transformer": { "use": ["Anthropic"] }
+    },
+    {
+      "name": "agentskills",
+      "api_base_url": "https://api.anthropic.com/v1/messages",
+      "api_key": "$ANTHROPIC_API_KEY",
+      "models": ["claude-sonnet-4-latest"],
+      "transformer": { "use": ["Anthropic"] },
+      "skills_enabled": true,
+      "skills_registry": "$HOME/.claude-code-router/skills"
+    }
+    // ... other providers
+  ],
+
+  "Router": {
+    "default": "openai,gpt-4o",
+    "background": "qwen,qwen-turbo",
+    "think": "anthropic,claude-sonnet-4-latest",
+    "longContext": "gemini,gemini-2.5-flash",
+    "longContextThreshold": 60000,
+    "skills": "agentskills,claude-sonnet-4-latest"
+  }
+}
+```
+
+### 1.2 Create Skills Directory
+
+```bash
+# Create skills directory
+mkdir -p ~/.claude-code-router/skills
+
+# Create skill registry file
+cat > ~/.claude-code-router/skills/registry.json << 'EOF'
+{
+  "version": "1.0.0",
+  "skills": [
+    {
+      "name": "business-panel",
+      "description": "Business analysis with expert frameworks",
+      "provider": "agentskills",
+      "model": "claude-sonnet-4-latest",
+      "enabled": true,
+      "priority": "highest"
+    },
+    {
+      "name": "code-review",
+      "description": "Comprehensive code quality analysis",
+      "provider": "agentskills",
+      "model": "claude-sonnet-4-latest",
+      "enabled": true,
+      "priority": "high"
+    }
+  ]
+}
+EOF
+```
+
+## Step 2: Update Intent Router
+
+### 2.1 Create Enhanced Intent Router
+
+```bash
+# Backup current router
+cp ~/.claude-code-router/intent-router.js ~/.claude-code-router/intent-router.js.backup
+```
+
+Create a new enhanced intent router at `~/.claude-code-router/intent-router.js`:
+
+```javascript
+/**
+ * Multi-Provider Intent Router with AgentSkills Integration
+ * Routes requests based on task type and skill requirements to optimal provider
+ *
+ * This router is designed for use with @musistudio/claude-code-router
+ * Original project: https://github.com/musistudio/claude-code-router
+ *
+ * Enhanced with AgentSkills support by Halil Ertekin
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Load skills registry
+let skillsRegistry = null;
+try {
+  const registryPath = path.join(process.env.HOME || process.env.USERPROFILE, '.claude-code-router/skills/registry.json');
+  skillsRegistry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+} catch (error) {
+  console.log('[Router] Skills registry not found, using standard routing');
+}
+
+const INTENTS = {
+  // AgentSkills routing - highest priority
+  AGENT_SKILLS: {
+    patterns: [
+      /\b\/sc:[\w-]+\b/i,  // All SuperClaude commands
+      /\b(skill:|capability:|expertise:)\w+/i,
+      /\b(agent|assistant) with \w+ skill/i
+    ],
+    route: "agentskills,claude-sonnet-4-latest",
+    priority: 100
+  },
+
+  // Business Panel - specialized expert analysis
+  BUSINESS_PANEL: {
+    patterns: [
+      /\b\/sc:business-panel\b/i,
+      /\b(business analysis|strategic planning|market research)\b/i,
+      /\b(porter|christensen|drucker|godin|meadows)\b/i
+    ],
+    route: "agentskills,business-panel",
+    priority: 90,
+    fallback: "anthropic,claude-sonnet-4-latest"
+  },
+
+  // Code Review - specialized analysis
+  CODE_REVIEW: {
+    patterns: [
+      /\b\/sc:code-review\b/i,
+      /\b(review code|code quality|best practices)\b/i,
+      /\b(pr review|pull request|code analysis)\b/i
+    ],
+    route: "agentskills,code-review",
+    priority: 85,
+    fallback: "openai,gpt-4o"
+  },
+
+  // Original intents with adjusted priorities
+  CODING: {
+    patterns: [
+      /\b(implement|refactor|debug|fix|write|code|function|class|method|bug|error|compile|syntax)\b/i,
+      /\b(typescript|javascript|python|rust|go|java|react|vue|angular|swift|kotlin)\b/i,
+      /\b(api|endpoint|database|query|migration|schema|test|unit test)\b/i,
+      /\b(codex|o1|reasoning)\b/i
+    ],
+    route: "openai,gpt-4o",
+    priority: 80
+  },
+
+  REASONING: {
+    patterns: [
+      /\b(architect|design|analyze|plan|strategy|structure|system|trade-?off)\b/i,
+      /\b(why|explain|reason|understand|compare|evaluate|consider|review)\b/i,
+      /\b(decision|approach|best practice|pattern|principle|philosophy)\b/i
+    ],
+    route: "anthropic,claude-sonnet-4-latest",
+    priority: 75
+  },
+
+  // ... other existing intents
+};
+
+// Helper function to extract content
+function extractContent(req) {
+  const messages = req.body?.messages || [];
+  return messages
+    .filter(m => m.role === "user" || m.role === "system")
+    .map(m => typeof m.content === "string" ? m.content : JSON.stringify(m.content))
+    .join(" ")
+    .slice(0, 3000);
+}
+
+// Enhanced skill detection
+function detectSkills(content) {
+  const skills = [];
+
+  // Check for SuperClaude commands
+  const scMatch = content.match(/\/sc:([\w-]+)/i);
+  if (scMatch) {
+    skills.push({
+      type: 'superclaude',
+      command: scMatch[1],
+      confidence: 0.95
+    });
+  }
+
+  // Check for skill keywords
+  if (skillsRegistry) {
+    skillsRegistry.skills.forEach(skill => {
+      if (skill.enabled && content.toLowerCase().includes(skill.name.toLowerCase())) {
+        skills.push({
+          type: 'skill',
+          name: skill.name,
+          provider: skill.provider,
+          model: skill.model,
+          confidence: 0.8
+        });
+      }
+    });
+  }
+
+  return skills.sort((a, b) => b.confidence - a.confidence);
+}
+
+// Enhanced intent detection with skill awareness
+function detectIntent(content) {
+  const skills = detectSkills(content);
+  const scores = {};
+
+  // Score intents
+  for (const [intent, config] of Object.entries(INTENTS)) {
+    scores[intent] = {
+      score: config.patterns.reduce((score, pattern) => {
+        const matches = (content.match(pattern) || []).length;
+        return score + matches;
+      }, 0),
+      priority: config.priority || 0,
+      config: config
+    };
+  }
+
+  // Factor in skills
+  if (skills.length > 0) {
+    // Boost AgentSkills intent if skills detected
+    if (scores.AGENT_SKILLS) {
+      scores.AGENT_SKILLS.score += skills.length * 2;
+    }
+  }
+
+  // Sort by score, then priority
+  const sorted = Object.entries(scores)
+    .filter(([_, data]) => data.score > 0)
+    .sort((a, b) => {
+      // Primary sort: score
+      if (b[1].score !== a[1].score) {
+        return b[1].score - a[1].score;
+      }
+      // Secondary sort: priority
+      return b[1].priority - a[1].priority;
+    });
+
+  return sorted.length > 0 ? sorted[0][0] : null;
+}
+
+// Main routing function
+module.exports = async function router(req, config) {
+  const content = extractContent(req);
+  const skills = detectSkills(content);
+  const intent = detectIntent(content);
+
+  // Log detection for debugging
+  if (skills.length > 0) {
+    console.log(`[Router] Skills detected: ${skills.map(s => s.name || s.type).join(', ')}`);
+  }
+
+  if (intent && INTENTS[intent]) {
+    const route = INTENTS[intent].route;
+    console.log(`[Router] ${intent} → ${route}`);
+
+    // Check if route uses AgentSkills
+    if (route.includes('agentskills') && skills.length > 0) {
+      // Enhance request with skill information
+      if (!req.body) req.body = {};
+      if (!req.body.metadata) req.body.metadata = {};
+      req.body.metadata.skills = skills;
+      req.body.metadata.intent = intent;
+    }
+
+    return route;
+  }
+
+  // Fallback
+  console.log("[Router] No match → openai,gpt-4o");
+  return null;
+};
+
+// Export helper functions for testing
+module.exports.detectSkills = detectSkills;
+module.exports.detectIntent = detectIntent;
+module.exports.INTENTS = INTENTS;
+```
+
+## Step 3: Create Skill Definitions
+
+### 3.1 Business Panel Skill
+
+Create `~/.claude-code-router/skills/business-panel/SKILL.md`:
+
+```markdown
+---
+name: "business-panel"
+description: "Business analysis with expert frameworks (Porter, Christensen, Drucker, Godin, Meadows)"
+version: "1.0.0"
+license: "MIT"
+compatibility: ["claude-sonnet-4-latest"]
+tags: ["business", "strategy", "analysis", "expert-panel"]
+allowed_tools: ["web-search", "context7", "sequential-thinking"]
+metadata:
+  expertise_level: "expert"
+  response_time: "slow"
+  cost_level: "high"
+  experts: ["porter", "christensen", "drucker", "godin", "meadows"]
+---
+
+# Business Panel Skill
+
+## Overview
+This skill activates a virtual expert panel for comprehensive business analysis using established frameworks and methodologies.
+
+## Expert Capabilities
+
+### Michael Porter - Competitive Strategy
+- **Five Forces Analysis**: Industry structure assessment
+- **Value Chain Analysis**: Internal capability evaluation
+- **Generic Strategies**: Cost leadership, differentiation, focus
+- **Competitive Advantage**: Sustainable positioning
+
+### Clayton Christensen - Disruption Theory
+- **Jobs-to-be-Done**: Customer need analysis
+- **Disruption Patterns**: Industry transformation identification
+- **Innovation Metrics**: Growth opportunity assessment
+- **Market Entry Strategy**: Disruptive positioning
+
+### Peter Drucker - Management Principles
+- **Management by Objectives**: Goal alignment
+- **Knowledge Worker Productivity**: Team optimization
+- **Innovation and Entrepreneurship**: Growth frameworks
+- **Effective Executive**: Leadership development
+
+### Seth Godin - Marketing & Remarkability
+- **Purple Cow Theory**: Remarkable product development
+- **Permission Marketing**: Customer relationship building
+- **Tribes**: Community creation and management
+- **Storytelling**: Brand narrative crafting
+
+### Donella Meadows - Systems Thinking
+- **Leverage Points**: System intervention identification
+- **Feedback Loops**: Pattern recognition
+- **System Archetypes**: Common dynamics understanding
+- **Sustainability**: Long-term viability analysis
+
+## Usage Patterns
+
+### Trigger Phrases
+- "/sc:business-panel"
+- "business analysis"
+- "strategic planning"
+- "market research"
+- "competitive analysis"
+- "expert panel"
+
+### Analysis Types
+
+1. **Comprehensive Strategic Analysis**
+   - Input: Business plan, market data, competitive landscape
+   - Process: Multi-expert framework application
+   - Output: Integrated strategic recommendations
+
+2. **Market Entry Strategy**
+   - Input: Target market, product/service, resources
+   - Process: Disruption + competitive analysis
+   - Output: Go-to-market strategy with timing and positioning
+
+3. **Organizational Design**
+   - Input: Current structure, goals, constraints
+   - Process: Systems thinking + management principles
+   - Output: Optimized organizational design
+
+## Implementation Notes
+
+### Best Practices
+- Use for complex, multi-faceted business challenges
+- Combine multiple expert perspectives for comprehensive analysis
+- Apply systems thinking for organizational and market problems
+- Focus on actionable insights rather than theoretical frameworks
+
+### Limitations
+- Requires substantial context for meaningful analysis
+- Best with Claude Sonnet 4 for optimal reasoning
+- Higher token usage due to comprehensive analysis
+- Response time may be longer due to complexity
+
+## Quality Indicators
+- Clear framework identification and application
+- Integration of multiple expert perspectives
+- Actionable, specific recommendations
+- Recognition of system interdependencies
+- Balanced consideration of short-term and long-term factors
+```
+
+### 3.2 Code Review Skill
+
+Create `~/.claude-code-router/skills/code-review/SKILL.md`:
+
+```markdown
+---
+name: "code-review"
+description: "Comprehensive code quality analysis with security, performance, and maintainability focus"
+version: "1.0.0"
+license: "MIT"
+compatibility: ["claude-sonnet-4-latest", "claude-3-5-sonnet-latest"]
+tags: ["code", "review", "quality", "security", "performance"]
+allowed_tools: ["context7", "sequential-thinking", "lsp"]
+metadata:
+  expertise_level: "senior-developer"
+  response_time: "medium"
+  cost_level: "medium"
+  focus_areas: ["security", "performance", "maintainability", "patterns"]
+---
+
+# Code Review Skill
+
+## Overview
+This skill provides comprehensive code analysis covering security vulnerabilities, performance optimization opportunities, maintainability issues, and adherence to best practices.
+
+## Review Dimensions
+
+### Security Analysis
+- **Vulnerability Detection**: SQL injection, XSS, CSRF, authentication flaws
+- **Data Protection**: Sensitive data handling, encryption, access controls
+- **Input Validation**: Sanitization, bounds checking, type safety
+- **Dependency Security**: Known vulnerabilities, license compliance
+
+### Performance Optimization
+- **Algorithm Efficiency**: Time/space complexity analysis
+- **Resource Usage**: Memory, CPU, I/O optimization
+- **Caching Strategies**: Implementation opportunities
+- **Database Optimization**: Query efficiency, indexing, connection pooling
+
+### Code Quality & Maintainability
+- **Design Patterns**: Appropriate pattern usage and anti-patterns
+- **Code Organization**: Modularity, coupling, cohesion
+- **Documentation**: Code comments, API documentation
+- **Testing**: Test coverage, test quality, edge cases
+
+### Best Practices
+- **Language-Specific**: Idiomatic code usage per language
+- **Framework Guidelines**: Framework-specific conventions
+- **Error Handling**: Exception management, graceful degradation
+- **Logging**: Appropriate logging levels and information
+
+## Usage Patterns
+
+### Trigger Phrases
+- "/sc:code-review"
+- "review my code"
+- "code quality check"
+- "security review"
+- "performance analysis"
+- "best practices review"
+
+### Review Types
+
+1. **Security-Focused Review**
+   - Priority: Critical vulnerabilities first
+   - Scope: Authentication, authorization, data protection
+   - Output: Security issues with severity ratings and fixes
+
+2. **Performance Review**
+   - Priority: Bottlenecks and optimization opportunities
+   - Scope: Algorithm efficiency, resource usage
+   - Output: Performance issues with optimization suggestions
+
+3. **Comprehensive Review**
+   - All dimensions with equal priority
+   - Holistic code quality assessment
+   - Detailed improvement roadmap
+
+## Review Process
+
+### Analysis Steps
+1. **Code Structure Understanding**: Parse and understand architecture
+2. **Pattern Recognition**: Identify design patterns and anti-patterns
+3. **Issue Detection**: Find security, performance, and quality issues
+4. **Impact Assessment**: Rate severity and priority of issues
+5. **Recommendation Generation**: Provide actionable improvement suggestions
+
+### Output Format
+```
+## Code Review Summary
+
+### 🔴 Critical Issues
+[High-priority security or functionality issues]
+
+### 🟡 Important Improvements
+[Performance optimizations, security enhancements]
+
+### 🟢 Suggestions
+[Code quality, maintainability improvements]
+
+### 📊 Metrics
+- Security Score: X/10
+- Performance Score: X/10
+- Maintainability Score: X/10
+```
+
+## Implementation Notes
+
+### Supported Languages
+- JavaScript/TypeScript
+- Python
+- Java
+- Go
+- Rust
+- C#
+- Ruby
+
+### Integration Points
+- GitHub/GitLab PR reviews
+- CI/CD pipeline integration
+- IDE plugins
+- Code quality dashboards
+
+### Quality Metrics
+- Lines of code analyzed
+- Issues found by category
+- False positive rate
+- Review completion time
+
+## Limitations
+- Cannot replace human code review entirely
+- May miss business logic issues
+- Context-dependent bugs may be overlooked
+- Requires sufficient code context for accurate analysis
+```
+
+## Step 4: Update Environment Variables
+
+Add to your `~/.env` file:
+
+```bash
+# AgentSkills Configuration
+export AGENTSKILLS_ENABLED="true"
+export AGENTSKILLS_REGISTRY_PATH="$HOME/.claude-code-router/skills"
+export AGENTSKILLS_LOG_LEVEL="info"
+export AGENTSKILLS_CACHE_TTL="3600"
+
+# Skill-Specific Configuration
+export AGENTSKILLS_BUSINESS_PANEL_ENABLED="true"
+export AGENTSKILLS_CODE_REVIEW_ENABLED="true"
+export AGENTSKILLS_MAX_SKILLS_PER_REQUEST="3"
+```
+
+Reload your shell:
+```bash
+source ~/.zshrc
+```
+
+## Step 5: Test the Integration
+
+### 5.1 Test Skill Detection
+
+```bash
+# Test SuperClaude command detection
+echo "Testing skill detection..."
+node -e "
+const router = require('$HOME/.claude-code-router/intent-router.js');
+const mockReq = {
+  body: {
+    messages: [{ role: 'user', content: '/sc:business-panel analyze our competitive position' }]
+  }
+};
+router(mockReq, {}).then(route => console.log('Route:', route));
+"
+```
+
+### 5.2 Test Business Panel Skill
+
+```bash
+# Start the router
+ccr code
+
+# In another terminal, test with curl
+curl -X POST http://localhost:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "/sc:business-panel Analyze the competitive landscape for electric vehicle startups"}
+    ],
+    "model": "claude-sonnet-4-latest"
+  }'
+```
+
+### 5.3 Test Code Review Skill
+
+```bash
+# Test code review functionality
+curl -X POST http://localhost:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "/sc:code-review Review this Python code for security issues:\n\n```python\ndef login(username, password):\n    query = \"SELECT * FROM users WHERE username = '\" + username + \"' AND password = '\" + password + \"'\"\n    return db.execute(query)\n```"}
+    ],
+    "model": "claude-sonnet-4-latest"
+  }'
+```
+
+## Step 6: Monitor and Optimize
+
+### 6.1 Enable Logging
+
+Add to your `~/.claude-code-router/config.json`:
+
+```json
+{
+  "LOG": true,
+  "LOG_LEVEL": "debug",
+  "AGENTSKILLS_LOG_REQUESTS": true,
+  "AGENTSKILLS_LOG_ROUTING_DECISIONS": true
+}
+```
+
+### 6.2 Monitor Performance
+
+Create a monitoring script at `~/.claude-code-router/monitor.js`:
+
+```javascript
+const fs = require('fs');
+
+// Log routing decisions
+setInterval(() => {
+  const logs = fs.readFileSync('/tmp/claude-router.log', 'utf8');
+  const agentSkillsRequests = logs.match(/\[Router\].*agentskills/g) || [];
+
+  console.log(`AgentSkills requests in last minute: ${agentSkillsRequests.length}`);
+
+  // Parse skill usage
+  const skillUsage = {};
+  agentSkillsRequests.forEach(log => {
+    const skillMatch = log.match(/Skill route: (\w+)/);
+    if (skillMatch) {
+      skillUsage[skillMatch[1]] = (skillUsage[skillMatch[1]] || 0) + 1;
+    }
+  });
+
+  console.log('Skill usage:', skillUsage);
+}, 60000);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Skills not loading**
+   ```bash
+   # Check skills directory
+   ls -la ~/.claude-code-router/skills/
+
+   # Verify registry file
+   cat ~/.claude-code-router/skills/registry.json
+   ```
+
+2. **Router not using AgentSkills**
+   ```bash
+   # Check intent router syntax
+   node -c ~/.claude-code-router/intent-router.js
+
+   # Test routing manually
+   node -e "console.log(require('./intent-router.js').detectIntent('/sc:business-panel test'))"
+   ```
+
+3. **Skill files not found**
+   ```bash
+   # Verify skill structure
+   find ~/.claude-code-router/skills -name "SKILL.md"
+
+   # Check skill file format
+   cat ~/.claude-code-router/skills/business-panel/SKILL.md | head -20
+   ```
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+# Set debug environment
+export AGENTSKILLS_DEBUG=true
+export AGENTSKILLS_LOG_LEVEL=debug
+
+# Restart router with verbose output
+ccr code --verbose
+```
+
+## Next Steps
+
+1. **Add Custom Skills**: Create domain-specific skills for your use cases
+2. **Integrate with CI/CD**: Add automated code reviews to your pipeline
+3. **Build Skill Marketplace**: Share skills with your team
+4. **Monitor Usage**: Track which skills provide most value
+5. **Optimize Performance**: Fine-tune routing based on usage patterns
+
+## Support
+
+- **Main Repository**: https://github.com/halilertekin/CC-RouterMultiProvider
+- **AgentSkills**: https://github.com/agentskills/agentskills
+- **Issues**: Report via GitHub issues
+- **Documentation**: See `/docs` directory for more guides
+
+## Attribution
+
+This setup guide is for the [claude-code-router-config](https://github.com/halilertekin/CC-RouterMultiProvider) project.
+Original project: https://github.com/musistudio/claude-code-router
+AgentSkills: https://github.com/agentskills/agentskills
+Guide by Halil Ertekin