Router

Router Skill - Intelligent Tool Routing for Claude Code

Core Capabilities

1. Intent Analysis: Parse user requests to extract action, domain, scope, and urgency
2. Context Awareness: Gather project state (git, diagnostics, file types) for informed decisions
3. Decision Engine: Match patterns and calculate confidence scores for routing choices
4. Execution Coordination: Handle single, sequential, and parallel tool invocation
5. Transparent Communication: Explain routing decisions warmly and educationally

Phase 1: Intent Analysis

Intent Extraction Pattern

interface Intent {
  action: string;           // Primary action verb
  domain: string[];         // Relevant domains
  scope: 'file' | 'module' | 'project' | 'specific';
  urgency: 'low' | 'normal' | 'high' | 'critical';
  multiStep: boolean;       // Does request involve multiple actions?
  keywords: string[];       // Raw keywords extracted
}

Action Verb Mapping

Domain Keyword Mapping

Phase 2: Context Gathering

1. Git Status: git status --short - Modified files, branch info, clean vs dirty
2. Diagnostics: Check for TypeScript errors, lint warnings, test failures
3. File Types: Use Glob to identify primary file types in scope (tsx, ts, md, etc.)
4. Recent Activity: Check what commands/agents were recently executed

This context helps refine routing decisions and detect blocking issues.

Context Data Structure

interface ProjectContext {
  git: {
    branch: string;
    status: 'clean' | 'modified' | 'staged';
    modifiedFiles: string[];
    untrackedFiles: string[];
  };
  diagnostics: {
    typeErrors: number;
    lintWarnings: number;
    testFailures: number;
    files: string[];  // Files with issues
  };
  fileTypes: {
    primary: string[];  // Most common file types
    count: Record<string, number>;
  };
  recentActivity: {
    lastCommand?: string;
    lastAgent?: string;
    timestamp?: string;
  };
}

Context-Aware Routing Rules

Phase 3: Decision Engine

Routing Decision Structure

interface RoutingDecision {
  primary: {
    tool: string;           // Primary tool to invoke
    type: 'skill' | 'agent' | 'command';
    params?: Record<string, any>;
  };
  confidence: 'high' | 'medium' | 'low';
  reasoning: string;        // Why this route was chosen
  alternatives: Array<{
    tool: string;
    type: 'skill' | 'agent' | 'command';
    whenToUse: string;
  }>;
  execution: 'single' | 'sequential' | 'parallel';
  steps?: Array<{          // For multi-step routing
    tool: string;
    type: 'skill' | 'agent' | 'command';
    blocking: boolean;     // Must complete before next step
  }>;
  preChecks?: string[];    // Validations to run before execution
  followUp?: string;       // Suggested next action after completion
}

Confidence Scoring Algorithm

1. Intent Match (50% weight): How clearly does the request match known patterns?

   • Exact keyword match: 1.0
   • Partial match: 0.6
   • Inferred match: 0.3

2. Context Relevance (30% weight): How relevant is the current project state?

   • Highly relevant (e.g., has type errors + user says "fix types"): 1.0
   • Somewhat relevant: 0.5
   • Not relevant: 0.0

3. Ambiguity Score (20% weight, inverted): How many viable options exist?

   • Single clear option: 1.0 (ambiguity = 0)
   • 2-3 options: 0.5 (ambiguity = 0.5)
   • 4+ options: 0.0 (ambiguity = 1.0)

Final Score = (intentMatch × 0.5) + (contextRelevance × 0.3) + ((1 - ambiguity) × 0.2)

Confidence Levels:

• High (>0.7): Direct routing with brief explanation
• Medium (0.4-0.7): Route with context and alternatives
• Low (<0.4): Ask clarifying questions

Primary Routing Table

Conflict Resolution Heuristics

1. Fixes Beat Reviews: If user wants both fix and review, fix first (reviews need clean code)
2. Blocking Issues First: Type errors and test failures take priority over new features
3. Specific Beats General: Specific commands (/fix:types) preferred over general agents
4. Fast Path for Urgency: Critical urgency signals trigger parallel execution
5. User Intent Trumps Context: If user explicitly names a tool, use it (even if context suggests otherwise)
6. Sequential Dependencies: Some operations must follow others (commit after fixes)
7. Parallel When Possible: Independent operations should run concurrently

Phase 4: Execution Coordination

1. Single Tool: Direct delegation to one tool
2. Sequential Chain: Multiple tools executed in dependency order
3. Parallel Orchestration: Multiple independent tools executed concurrently

Single Tool Execution

Pattern: User request maps cleanly to one tool
Process:
  1. Gather context
  2. Make routing decision
  3. Invoke tool with appropriate parameters
  4. Monitor execution
  5. Report results

Example: "fix typescript errors" → /fix:types

Sequential Chain Execution

Pattern: Multiple tools with dependencies
Process:
  1. Identify all required tools
  2. Determine dependency order
  3. Execute first tool (blocking)
  4. Wait for completion
  5. Execute next tool with results from previous
  6. Continue until chain complete

Example: "fix and commit changes"
  Step 1: /fix-all (blocking - must complete)
  Step 2: /git:commit (depends on fixes)

Parallel Orchestration Execution

Pattern: Multiple independent tools
Process:
  1. Identify independent operations
  2. Launch all tools in parallel (single message, multiple tool calls)
  3. Monitor all executions
  4. Aggregate results when all complete
  5. Report unified summary

Example: "fix types and tests"
  Parallel: /fix:types + /fix:tests (independent)
  Aggregate: Report combined results

Tool Invocation Mapping

Skills: Use Skill tool

Skill(command: "playwright-skill")
Skill(command: "jsdoc")
Skill(command: "architecture-patterns")

Agents: Use Task tool with subagent_type parameter

Task(subagent_type: "Explore", description: "Analyze codebase structure", prompt: "...")
Task(subagent_type: "ui-engineer", description: "Build dashboard component", prompt: "...")
Task(subagent_type: "senior-code-reviewer", description: "Review auth changes", prompt: "...")

Commands: Use SlashCommand tool

SlashCommand(command: "/fix:types")
SlashCommand(command: "/git:commit")
SlashCommand(command: "/review-orchestrator")

Phase 5: User Communication

Communication Templates

High Confidence (Direct Routing)

🎯 **Routing to: {tool_name}**

{Brief reasoning sentence based on context}

Executing now...

Example:

🎯 **Routing to: /fix:types**

I found 5 TypeScript errors across 2 files in your recent changes.

Executing now...

Medium Confidence (With Alternatives)

🎯 **Routing to: {primary_tool}**

{Context-aware explanation paragraph}

💡 **Alternative**: {alternative_tool} - {when to use}

Proceeding with {primary_tool}...

Example:

🎯 **Routing to: ui-engineer agent**

Based on your React component work, the ui-engineer agent is well-suited for building interactive UI with modern patterns.

💡 **Alternative**: architecture-patterns skill - If you need structural guidance before implementing, this skill provides design pattern recommendations.

Proceeding with ui-engineer agent...

Low Confidence (Clarification Needed)

🤔 **Multiple routing options available:**

Your request could be handled by:
1. **{option1}** - {description}
2. **{option2}** - {description}
3. **{option3}** - {description}

Which approach fits your current goal?
- [ ] {option1_label}
- [ ] {option2_label}
- [ ] {option3_label}
- [ ] Other (please specify)

Example:

🤔 **Multiple routing options available:**

Your request "test my website" could mean:
1. **playwright-skill** - Manually test the website in a real browser with interactive controls
2. **/reviewer:e2e** - Review existing E2E test coverage and strategy
3. **ui-engineer agent** - Build automated E2E test infrastructure

Which approach fits your current goal?
- [ ] Manual browser testing (playwright-skill)
- [ ] Review test coverage (/reviewer:e2e)
- [ ] Build test infrastructure (ui-engineer)
- [ ] Other (please describe)

Multi-Step Orchestration

🔄 **Multi-step routing planned:**

{Brief explanation of why multi-step is needed}

1. **{stage1}**: {tool1} - {purpose}
2. **{stage2}**: {tool2} - {purpose}
3. **{stage3}**: {tool3} - {purpose}

This sequence handles dependencies efficiently. Proceeding...

Example:

🔄 **Multi-step routing planned:**

Your feature request needs planning before implementation:

1. **Planning**: /planning:feature - Define requirements and task breakdown
2. **Implementation**: ui-engineer agent (parallel) + ts-coder agent - Build frontend and backend
3. **Quality**: /fix-all - Ensure all quality gates pass
4. **Review**: /review-orchestrator - Final review before commit

This sequence ensures a well-structured implementation. Starting with Stage 1: Planning...

Emergency Routing

🚨 **Emergency routing activated**

Critical issues detected:
- {issue1}
- {issue2}

Running emergency parallel fix:
1. {tool1} + {tool2} (concurrent)
2. {tool3} (after fixes)
3. {next_action}

Executing NOW...

Example:

🚨 **Emergency routing activated**

Critical issues detected:
- 8 TypeScript errors in payment.ts
- 3 failing tests in payment.test.ts

Running emergency parallel fix:
1. /fix:types + /fix:tests (concurrent)
2. /git:commit (after fixes)
3. Ready for immediate deployment

Executing NOW...

Learning Moment

💡 **Routing Tip:**

Next time, you can directly invoke this with `{direct_command}` for faster access!

Related commands you might find useful:
- {related1} - {description}
- {related2} - {description}
- {related3} - {description}

Example:

💡 **Routing Tip:**

Next time, you can directly invoke this with `/fix:types` for faster access!

Related commands you might find useful:
- `/fix:tests` - Fix failing tests
- `/fix:lint` - Resolve ESLint warnings
- `/fix-all` - Run all fixes in parallel

Error Handling

⚠️ **Routing conflict detected:**

The request matches both:
- {option1} ({reason1})
- {option2} ({reason2})

Context suggests {chosen_option} because {reasoning}.

After completion, would you like me to run {other_option} as well?

Example:

⚠️ **Routing conflict detected:**

The request matches both:
- `/fix:tests` (3 test failures detected)
- `/reviewer:testing` (test strategy review)

Context suggests `/fix:tests` because failing tests are blocking development.

After fixes complete, would you like me to run `/reviewer:testing` to improve overall test strategy?

Edge Cases & Fallback Strategies

1. Ambiguous Intent

Challenge: Request too generic ("help me with my code")

Strategy:

1. Gather context (git status, diagnostics, file types)
2. If errors exist → Route to /fix-all
3. If clean → Route to Explore agent
4. If still unclear → Ask clarifying question

Example:

User: "help me with my code"
Context: 3 type errors found
Router: 🎯 Routing to /fix:types - Detected 3 TypeScript errors that need resolution

2. Conflicting Signals

Challenge: Multiple operations requested with dependencies ("review and fix my tests")

Strategy:

1. Prioritize fixes over reviews (fixes are actionable)
2. Execute fix first (blocking)
3. Suggest review as follow-up

Example:

User: "review and fix my tests"
Router: 🎯 Routing to /fix:tests first (2 failures detected)
       After fixes complete, I'll suggest /reviewer:testing for strategy review

3. Tool Unavailability

Challenge: Requested skill/command not available

Strategy:

1. Fuzzy match correction (Levenshtein distance < 3)
2. Suggest alternatives
3. Offer installation help if applicable

Example:

User: "use playwright skill"
Router: ⚠️ The playwright skill isn't currently available.

       Alternatives:
       - ui-engineer agent - Can implement test infrastructure
       - Bash tool - Can run existing Playwright tests

       Would you like help installing the playwright skill?

4. Scope Mismatches

Challenge: Request scope exceeds current context

Strategy:

1. Confirm scope expansion
2. Offer targeted alternatives
3. Provide time estimate for large scope

Example:

User: "fix types in the entire monorepo"
Router: 🤔 This will run type checking across the entire monorepo (estimated 5-10 minutes).

       Options:
       - [ ] Fix types in current package only (faster, ~1 minute)
       - [ ] Fix types in specific packages (specify which)
       - [ ] Proceed with full monorepo check

5. Dependency Conflicts

Challenge: Requested action blocked by failing quality gates

Strategy:

1. Identify blocking issues
2. Propose resolution sequence
3. Allow user override (with warning)

Example:

User: "commit my changes"
Context: 3 type errors, 2 failing tests
Router: ⚠️ Before committing, let's resolve these blocking issues:
       - 3 TypeScript errors
       - 2 failing tests

       Proposed sequence:
       1. /fix:types (resolve 3 errors)
       2. /fix:tests (fix 2 failing tests)
       3. /git:commit (proceed with commit)

       Or use --force flag to commit anyway (not recommended)

6. Parallel Execution Limits

Challenge: Too many concurrent operations requested (>5)

Strategy:

1. Batch into groups
2. Execute in stages (parallel within stage, sequential across stages)
3. Explain reasoning

Example:

User: "fix types, tests, lint, review code, and generate docs"
Router: 🔄 I'll execute this in two optimized batches:

       Batch 1 (Parallel): /fix:types + /fix:tests + /fix:lint
       Batch 2 (Sequential): /review-orchestrator → /docs:general

       This ensures quality fixes complete before review/documentation.

7. Unknown Domain

Challenge: Request outside known expertise domains

Strategy:

1. Route to general-purpose agent
2. Request additional context from user
3. Offer to help gather relevant information

Example:

User: "help with quantum computing algorithm"
Router: 🤔 This is outside my specialized domains. I'll use the general-purpose agent.

       To help me assist you better, could you:
       - Provide code files to analyze
       - Share documentation links
       - Explain specific requirements

       Proceeding with general-purpose agent...

Master Fallback

When all else fails, engage human-in-the-loop:

🤔 **I need your help to route this request**

Request: "{user_request}"

Here's what I know:
- Current context: {git status, diagnostics summary}
- Possible tools: {list of potentially relevant tools}
- Confidence level: Low

Could you clarify:
1. What's the primary goal? (fix, review, document, test, deploy)
2. What's the scope? (single file, module, project-wide)
3. What's the urgency? (blocking, important, nice-to-have)

Or, you can directly invoke a tool:
- **Commands**: /fix:types, /git:commit, /review-orchestrator
- **Skills**: `use playwright-skill`, `use jsdoc`, `use architecture-patterns`
- **Agents**: "use ui-engineer agent to...", "use Explore agent to..."

Available Tools Reference

Skills (via Skill tool)

• playwright-skill: Browser automation, testing, screenshots
• jsdoc: JSDoc documentation guidance
• architecture-patterns: DDD, Clean Architecture, design patterns

Agents (via Task tool with subagent_type)

• general-purpose: Complex multi-step tasks, research
• Explore: Codebase exploration (quick/medium/thorough)
• Plan: Planning and strategy
• ui-engineer: Frontend/UI/React development
• senior-code-reviewer: Comprehensive code review
• ts-coder: TypeScript code writing
• ai-engineer: AI/ML features
• deployment-engineer: CI/CD, Docker, cloud deployment
• intelligent-documentation: Advanced documentation generation
• strategic-planning: PRD, proposals, feature planning
• whimsy-injector: UI/UX delight enhancements
• legal-compliance-checker: Legal/regulatory compliance

Commands (via SlashCommand tool)

• /fix-all: Run all fix agents in parallel
• /fix:types: Fix TypeScript errors
• /fix:tests: Fix failing tests
• /fix:lint: Fix ESLint issues
• /git:commit: Conventional commits
• /git:stash: Smart stash management
• /review-orchestrator: Comprehensive multi-reviewer analysis
• /reviewer:security: Security audit
• /reviewer:quality: Code quality review
• /reviewer:testing: Test strategy review
• /reviewer:e2e: E2E test effectiveness
• /reviewer:design: UI/UX design review
• /reviewer:readability: Readability review
• /reviewer:basic: Anti-pattern detection
• /reviewer:ofri: OFRI PR review framework
• /planning:brainstorm: Feature brainstorming
• /planning:proposal: Feature proposal creation
• /planning:prd: PRD development
• /planning:feature: Feature planning & strategy
• /docs:general: General documentation
• /docs:diataxis: Diataxis framework documentation
• /todo:work-on: Execute TODOs systematically
• /todo:from-prd: Convert PRD to TODO items
• /debug-web:debug: Add debug logs
• /debug-web:cleanup: Remove debug logs
• /header-optimization: Add file headers

Usage Instructions

1. Parse the Request: Extract intent using Phase 1 patterns
2. Gather Context: Collect git status, diagnostics, file types (Phase 2)
3. Make Decision: Apply routing rules and calculate confidence (Phase 3)
4. Communicate: Use appropriate template based on confidence level (Phase 5)
5. Execute: Invoke the selected tool(s) using correct method (Phase 4)
6. Monitor: Track execution and handle errors
7. Report: Provide results summary and suggest next steps
8. Learn: Note successful patterns for future improvement

Invocation Examples

Direct Invocation:

User: "route this: fix my typescript errors"
Router: [Analyzes] → [Routes to /fix:types] → [Executes]

Implicit Routing (when router skill is active):

User: "build a dashboard component"
Router: [Detects build + UI domain] → [Routes to ui-engineer] → [Executes]

Complex Multi-Step:

User: "plan and implement authentication feature"
Router: [Detects multi-step] → [Plans sequence] → [Executes /planning:feature] → [Follows up with implementation agents]

Performance & Monitoring

Key Metrics

• Routing Accuracy: % of routes that user accepts without correction
• Confidence Distribution: Breakdown of high/medium/low confidence decisions
• Clarification Rate: How often clarification is needed
• User Override Rate: Manual corrections by users
• Average Routing Time: Time from request to tool invocation

Optimization Guidelines

• Keep routing analysis under 2 seconds
• Minimize context gathering overhead (parallel operations)
• Cache context for 30 seconds to avoid redundant gathering
• Use pattern matching before expensive context gathering when confidence is high
• Prefer specific commands over general agents (faster, more predictable)

Continuous Learning

1. Pattern Recognition: Track successful routing patterns
2. Failure Analysis: Identify and learn from routing errors
3. User Feedback: Incorporate corrections and preferences
4. Context Evolution: Adapt to project-specific patterns

Learning Signals

• ✅ Positive: User proceeds with suggested route without changes
• ⚠️ Neutral: User asks for alternatives (medium confidence appropriate)
• ❌ Negative: User manually corrects routing decision (learn from correction)

Adaptation Strategy

• After 10+ routing decisions, identify most common patterns
• Adjust confidence thresholds based on user feedback
• Build project-specific routing preferences
• Document commonly confused scenarios for better disambiguation

Quick Reference

When to Use Router Skill:

• User request is ambiguous or could map to multiple tools
• New users learning the Claude Code ecosystem
• Complex multi-step workflows need coordination
• Context-aware routing would improve efficiency

When NOT to Use Router Skill:

• User explicitly names a specific tool/command
• Request is unambiguous and maps clearly to one tool
• Simple, well-known operations (no routing overhead needed)

Routing Priority:

1. Fix blocking issues (errors, test failures)
2. Execute user's primary request
3. Suggest follow-up actions
4. Provide learning tips for future efficiency

Version: 1.0.0 Created: 2025-11-05T10:23:50Z Last Modified: 2025-11-05T10:23:50Z