router-first-architecture
Router-First Architecture
When & Why to Use This Skill
This Claude skill implements a Router-First Architecture designed to optimize AI agent performance through deterministic tool selection. By abstracting individual tools behind domain-specific routers, it ensures precise intent mapping, reduces tool-selection errors, and provides a scalable framework for managing complex multi-tool environments.
Use Cases
- Complex Domain Orchestration: Using specialized routers (e.g., a math-router) to deterministically map user queries to the correct CLI commands or scripts, ensuring high accuracy in technical tasks.
- Reducing Tool Hallucination: Preventing AI agents from calling incorrect or non-existent tools by enforcing a routing layer that validates intent before execution.
- Scalable Agent Architecture: Implementing a two-layer system where broad trigger patterns capture user intent while a precise routing layer handles the technical execution, making the agent easier to maintain and expand.
- Co-Activation Workflows: Ensuring that necessary domain knowledge and routing capabilities are always available simultaneously through structured co-activation patterns in agent configurations.
| name | router-first-architecture |
|---|---|
| description | Router-First Architecture |
Router-First Architecture
Route through domain routers before using individual tools. Routers abstract tool selection.
Pattern
Domain routers (like math-router) provide deterministic mapping from user intent to exact CLI commands. Always use the router first; only bypass for edge cases.
DO
- Call
math-router route "<intent>"before any math operation - Let domain skills co-activate with their router (via
coActivatein skill-rules.json) - Trust the router's confidence score; only fall back if
command: null - Keep trigger keywords/patterns in skill-rules.json broader than routing patterns
DON'T
- Call individual scripts directly when a router exists
- Duplicate routing logic in individual skills
- Let domain skills bypass their router
Co-Activation Pattern
Domain skills should co-activate with their router:
{
"math/abstract-algebra/groups": {
"coActivate": ["math-router"],
"coActivateMode": "always"
}
}
This ensures the router is always available when domain knowledge is activated.
Two-Layer Architecture
- Skill-rules trigger layer: Nudges Claude to use the router (keywords, intent patterns)
- Router routing layer: Deterministic mapping to scripts via regex patterns
Keep the trigger layer broader than routing - the router should handle "not found" gracefully.
Source Sessions
- 2bbc8d6e: "Trigger layer was narrower than routing layer" - expanded triggers
- This session: Wired 8 domain math skills to co-activate with math-router