@booklib/skills 1.2.0 → 1.3.1

package/skill-router/examples/after.md

@@ -0,0 +1,63 @@
+# After: Routed Code Review Request
+
+## User Message (same as before)
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## Skill Router Output
+
+**Primary skill:** `clean-code-reviewer`
+**Why:** The user wants general code quality improvement for a Java class. The dominant issues are language-agnostic: poor naming (`o`, `isAdmin` flag arg, magic return codes), static mutable state, nested conditionals, and multiple responsibilities — all Clean Code's territory.
+**Secondary (optional):** `effective-java` — after the Clean Code review, apply Effective Java for Java-specific improvements: replace `Map<String, Object>` with a typed class (Item 64: refer to objects by their interfaces), use enums instead of int return codes (Item 34).
+**Don't apply:** `domain-driven-design` — while an Order is a domain concept, applying DDD here would produce advice about Aggregates and Bounded Contexts that is premature. Fix the code quality first.
+
+---
+
+## What the Clean Code Review Produces
+
+With the right skill applied, the review is sharp and specific:
+
+### Issues Found
+
+🔴 **Critical — F3: Flag Arguments**
+`isAdmin` and `sendEmail` are boolean flags — the function does 4 different things depending on their combination. Split into `approveAsAdmin()` and keep email logic separate.
+
+🔴 **Critical — Shared Mutable Static State (Ch. 13)**
+`pendingOrders` is a static mutable list — not thread-safe and makes the class impossible to test in isolation.
+
+🔴 **Critical — Error Codes Instead of Exceptions (Ch. 7)**
+Returning `-1` and `-2` forces callers to check magic numbers. Throw `InvalidOrderException` and `UnauthorizedOperationException` instead.
+
+🟡 **Important — N1: Poor Naming**
+`o`, `process` — names reveal nothing. `o` → `order`, `process` → `approveOrder`.
+
+🟡 **Important — G30: Function Does Multiple Things**
+`process()` validates, approves, removes from list, and sends email. Each is a separate responsibility.
+
+🟢 **Suggestion — G25: Magic Numbers**
+Return codes `-1`, `-2` should be named constants at minimum, or better: exceptions.
+
+### Result
+
+The user gets a **focused, actionable review** from one authoritative source — not a scattered survey of four books.

package/skill-router/examples/before.md

@@ -0,0 +1,39 @@
+# Before: Unrouted Code Review Request
+
+## User Message
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## What Happens Without Routing
+
+The AI must guess which lens to apply:
+
+- Does the user want **Java-specific** advice (Effective Java)? → Bloch would focus on generics, raw types, and static factory methods
+- Do they want **code quality** advice (Clean Code)? → Martin would focus on naming, flag arguments, static mutable state
+- Do they want **design pattern** advice (Design Patterns)? → Gang of Four would examine whether a Command or Strategy pattern fits
+- Do they want **domain modeling** advice (DDD)? → Evans would ask about Aggregates and Value Objects
+
+**Result:** The AI either picks one arbitrarily, tries to cover all four superficially, or asks a clarifying question that could have been avoided.
+
+The user gets a scattered review that's 40% relevant from four different books instead of a sharp, deep review from the right one.

package/skill-router/references/api_reference.md

@@ -0,0 +1,24 @@
+# API Reference: Skill Quick-Lookup
+
+Quick-lookup table for all 17 skills.
+
+| Skill | Domain | Works Well With | Conflicts With |
+|-------|--------|-----------------|----------------|
+| `animation-at-work` | Web animation, motion | `refactoring-ui` | None |
+| `clean-code-reviewer` | Code quality (any language) | `effective-java`, `effective-python`, `effective-kotlin` | `domain-driven-design` (model design context) |
+| `data-intensive-patterns` | Storage internals, distributed data | `system-design-interview` | `system-design-interview` (different altitude) |
+| `data-pipelines` | ETL, data ingestion, orchestration | `data-intensive-patterns`, `effective-python` | `microservices-patterns` |
+| `design-patterns` | GoF OO patterns | `clean-code-reviewer`, `effective-java` | `domain-driven-design` |
+| `domain-driven-design` | Domain modeling, DDD patterns | `microservices-patterns`, `clean-code-reviewer` | `clean-code-reviewer` (code review context) |
+| `effective-java` | Java idioms and best practices | `clean-code-reviewer`, `design-patterns` | `clean-code-reviewer` (Java-specific vs general) |
+| `effective-kotlin` | Kotlin best practices | `kotlin-in-action`, `clean-code-reviewer` | `kotlin-in-action` |
+| `effective-python` | Python idioms and best practices | `clean-code-reviewer`, `using-asyncio-python` | `using-asyncio-python` (async topics) |
+| `kotlin-in-action` | Kotlin language features | `effective-kotlin` | `effective-kotlin` |
+| `lean-startup` | Startup strategy, MVP, pivots | None (strategy only) | All technical skills |
+| `microservices-patterns` | Service decomposition, sagas, CQRS | `domain-driven-design`, `system-design-interview` | `domain-driven-design` (service vs model) |
+| `refactoring-ui` | UI design, visual hierarchy | `animation-at-work` | None |
+| `skill-router` | Skill selection and routing | All skills | None |
+| `storytelling-with-data` | Data visualization, charts | `data-pipelines` | None |
+| `system-design-interview` | System scalability, high-level design | `microservices-patterns`, `data-intensive-patterns` | `data-intensive-patterns` (altitude) |
+| `using-asyncio-python` | Python asyncio, concurrency | `effective-python` | `effective-python` (async topics) |
+| `web-scraping-python` | Web scraping, crawling | `effective-python`, `data-pipelines` | None |

package/skill-router/references/routing-heuristics.md

@@ -0,0 +1,89 @@
+# Routing Heuristics
+
+Decision rules for the skill-router. Apply these in order.
+
+## Primary Rules (apply first)
+
+### By Language
+
+| Language | Primary Skill | Override Condition |
+|----------|-------------|-------------------|
+| Python (general) | `effective-python` | If async → `using-asyncio-python`; if scraping → `web-scraping-python` |
+| Python (async/concurrent) | `using-asyncio-python` | Always wins over effective-python for async topics |
+| Python (web scraping) | `web-scraping-python` | Always wins for scraping topics |
+| Java | `effective-java` | If code quality focus → `clean-code-reviewer` |
+| Kotlin | `effective-kotlin` | If learning Kotlin → `kotlin-in-action` |
+| Any language (code quality) | `clean-code-reviewer` | Language-agnostic; always applicable for readability |
+| CSS/HTML/Frontend | `refactoring-ui` | If animation → `animation-at-work` |
+| Any (visualization) | `storytelling-with-data` | Must have a visual component |
+
+### By Domain
+
+| Domain | Primary Skill |
+|--------|-------------|
+| Domain modeling, DDD | `domain-driven-design` |
+| Service decomposition, distributed systems | `microservices-patterns` |
+| GoF design patterns | `design-patterns` |
+| System scalability, estimation | `system-design-interview` |
+| Storage internals, distributed data | `data-intensive-patterns` |
+| Data pipelines, ETL | `data-pipelines` |
+| Startup strategy, product | `lean-startup` |
+
+## Conflict Resolution Rules
+
+### clean-code-reviewer vs effective-java
+- **Code-level review with naming/readability focus** → `clean-code-reviewer`
+- **Java-specific items (generics, enums, serialization, lambdas)** → `effective-java`
+- **Both applicable** → primary: `clean-code-reviewer`, secondary: `effective-java`
+
+### effective-kotlin vs kotlin-in-action
+- **User knows Kotlin, wants best practice advice** → `effective-kotlin`
+- **User is learning Kotlin or asking about language features** → `kotlin-in-action`
+- **Ambiguous** → ask whether they want best practices or feature explanation
+
+### domain-driven-design vs microservices-patterns
+- **Designing or reviewing a domain model** → `domain-driven-design`
+- **Designing service decomposition, sagas, inter-service communication** → `microservices-patterns`
+- **Designing a new microservice with rich domain** → apply both: DDD first (model), microservices-patterns second (service design)
+
+### domain-driven-design vs clean-code-reviewer
+- **Model design** → `domain-driven-design` (ignore clean code's "small functions" rule when modeling)
+- **Code review** → `clean-code-reviewer` (DDD model concerns are separate from code readability)
+
+### data-intensive-patterns vs system-design-interview
+- **Internals: storage engines, replication, consistency models** → `data-intensive-patterns`
+- **High-level: system components, scale, estimation** → `system-design-interview`
+- **Full system design** → primary: `system-design-interview`, secondary: `data-intensive-patterns`
+
+### effective-python vs using-asyncio-python
+- **Any async/concurrent Python** → `using-asyncio-python` (always wins)
+- **Non-async Python** → `effective-python`
+
+## Work Type Rules
+
+| Work Type | Routing Preference |
+|-----------|-------------------|
+| Code review | Language-specific skill OR `clean-code-reviewer` |
+| Code generation | Domain-specific skill (DDD, microservices, design-patterns) |
+| Migration planning | Skill with Mode 3 (clean-code-reviewer, domain-driven-design, microservices-patterns) |
+| System design | `system-design-interview` + optional `microservices-patterns` |
+| Learning | Language-specific learning skill (kotlin-in-action) or domain skill |
+
+## Anti-Trigger Rules
+
+Never route to these skills if:
+
+| Skill | Don't route if... |
+|-------|------------------|
+| `domain-driven-design` | Simple CRUD, no complex domain, < 3 entity types |
+| `microservices-patterns` | Single service, no decomposition intent |
+| `lean-startup` | Pure technical code — this is a strategy skill only |
+| `effective-java` | Code is not Java |
+| `effective-kotlin` | Code is not Kotlin |
+| `effective-python` | Code is not Python |
+| `using-asyncio-python` | Code is not async Python |
+| `web-scraping-python` | Not web scraping |
+| `refactoring-ui` | No UI component |
+| `storytelling-with-data` | No visualization |
+| `animation-at-work` | No animation/motion concern |
+| `system-design-interview` | Code-level concern, not system-level |

package/skill-router/references/skill-catalog.md

@@ -0,0 +1,156 @@
+# Skill Catalog
+
+All 17 skills in the `@booklib/skills` library with routing metadata.
+
+## animation-at-work
+- **Source:** *Animation at Work* by Rachel Nabors
+- **Domain:** Web animation, UI motion design
+- **Language:** CSS, JavaScript, any frontend
+- **Trigger keywords:** "animation", "motion", "transition", "keyframe", "easing", "12 principles of animation", "web animation", "CSS animation", "performance of animation"
+- **Anti-triggers:** Backend code, data processing, non-visual concerns
+- **Works well with:** refactoring-ui (visual design context)
+- **Conflicts with:** None (niche domain)
+
+## clean-code-reviewer
+- **Source:** *Clean Code* by Robert C. Martin
+- **Domain:** Code quality, readability, maintainability
+- **Language:** Language-agnostic (Java, Python, Kotlin, JavaScript examples used)
+- **Trigger keywords:** "review my code", "code quality", "readable", "clean up", "refactor", "naming", "functions", "comments", "smells"
+- **Anti-triggers:** Architecture design (too high-level), language-specific idioms (use language-specific skill instead)
+- **Works well with:** effective-java, effective-python, effective-kotlin (clean code first, then language idioms)
+- **Conflicts with:** domain-driven-design (Clean Code's "small functions" vs DDD's "rich models" — clean code wins for code review, DDD wins for model design)
+
+## data-intensive-patterns
+- **Source:** *Designing Data-Intensive Applications* by Martin Kleppmann
+- **Domain:** Storage engines, replication, partitioning, distributed systems, transactions, consistency
+- **Language:** Language-agnostic (systems-level)
+- **Trigger keywords:** "replication", "partitioning", "consistency", "CAP theorem", "event sourcing internals", "storage engine", "LSM tree", "B-tree", "distributed transactions", "ACID", "BASE", "linearizability"
+- **Anti-triggers:** Application-level code quality, UI, domain modeling
+- **Works well with:** system-design-interview (data layer + high-level architecture)
+- **Conflicts with:** system-design-interview (data-intensive-patterns is deeper/lower-level; use it for internals, system-design-interview for high-level)
+
+## data-pipelines
+- **Source:** *Data Pipelines Pocket Reference* by James Densmore
+- **Domain:** Data ingestion, ETL, streaming, pipeline orchestration
+- **Language:** Python, SQL, any data engineering stack
+- **Trigger keywords:** "data pipeline", "ETL", "ELT", "ingestion", "Airflow", "dbt", "Spark", "streaming pipeline", "batch processing", "data warehouse", "orchestration"
+- **Anti-triggers:** Application code unrelated to data movement, real-time microservices
+- **Works well with:** data-intensive-patterns (pipeline + storage), effective-python (Python data code)
+- **Conflicts with:** microservices-patterns (pipeline orchestration ≠ service decomposition)
+
+## design-patterns
+- **Source:** *Head First Design Patterns* by Freeman & Robson (GoF patterns)
+- **Domain:** Object-oriented design patterns (creational, structural, behavioral)
+- **Language:** Java primarily, but pattern-agnostic
+- **Trigger keywords:** "design pattern", "factory", "singleton", "observer", "strategy", "decorator", "facade", "command", "template method", "composite", "adapter", "proxy", "iterator", "state"
+- **Anti-triggers:** Functional programming (patterns don't apply the same way), microservices decomposition
+- **Works well with:** clean-code-reviewer (patterns + readability), effective-java (Java idioms + patterns)
+- **Conflicts with:** domain-driven-design (GoF patterns are structural; DDD patterns are domain-driven — use DDD for domain modeling, GoF for implementation structure)
+
+## domain-driven-design
+- **Source:** *Domain-Driven Design* by Eric Evans
+- **Domain:** Domain modeling, tactical patterns (Entities, Value Objects, Aggregates, Repositories), strategic patterns (Bounded Contexts, Context Maps, ACL)
+- **Language:** Language-agnostic (OO languages)
+- **Trigger keywords:** "DDD", "domain model", "aggregate", "value object", "bounded context", "ubiquitous language", "repository pattern", "domain service", "anticorruption layer", "entity", "anemic domain model", "primitive obsession"
+- **Anti-triggers:** Simple CRUD without domain complexity, microservices infrastructure concerns, code quality review
+- **Works well with:** microservices-patterns (domain model + service boundaries), clean-code-reviewer (model + code quality)
+- **Conflicts with:** clean-code-reviewer (rich models vs small functions — DDD wins for model design; clean code wins for code review)
+
+## effective-java
+- **Source:** *Effective Java* (3rd Edition) by Joshua Bloch
+- **Domain:** Java best practices and idioms
+- **Language:** Java only
+- **Trigger keywords:** "effective java", "java best practices", "generics", "enums", "lambdas", "streams", "builders", "serialization", "java concurrency", "checked exceptions", "java item"
+- **Anti-triggers:** Non-Java code, architecture concerns, domain modeling
+- **Works well with:** clean-code-reviewer (Java idioms + code quality), design-patterns (Java implementation of patterns)
+- **Conflicts with:** clean-code-reviewer (both review Java but from different angles — use effective-java for Java-specific items, clean-code-reviewer for general readability)
+
+## effective-kotlin
+- **Source:** *Effective Kotlin* (2nd Edition) by Marcin Moskała
+- **Domain:** Kotlin best practices, safety, readability
+- **Language:** Kotlin only
+- **Trigger keywords:** "effective kotlin", "kotlin best practices", "kotlin safety", "null safety", "extension functions best practices", "kotlin idioms", "kotlin item"
+- **Anti-triggers:** Non-Kotlin code, architecture concerns
+- **Works well with:** kotlin-in-action (best practices + language features), clean-code-reviewer (Kotlin idioms + readability)
+- **Conflicts with:** kotlin-in-action (effective-kotlin for best practices; kotlin-in-action for language learning — if user knows Kotlin and wants advice, use effective-kotlin)
+
+## effective-python
+- **Source:** *Effective Python* (2nd Edition) by Brett Slatkin
+- **Domain:** Python best practices, Pythonic idioms
+- **Language:** Python only
+- **Trigger keywords:** "effective python", "pythonic", "python best practices", "python idioms", "comprehensions", "generators", "decorators", "metaclasses", "python item"
+- **Anti-triggers:** Non-Python code, async Python (use using-asyncio-python instead)
+- **Works well with:** clean-code-reviewer (Pythonic + readable), using-asyncio-python (general Python + async)
+- **Conflicts with:** using-asyncio-python (using-asyncio-python wins for async topics)
+
+## kotlin-in-action
+- **Source:** *Kotlin in Action* (2nd Edition)
+- **Domain:** Kotlin language features, learning Kotlin
+- **Language:** Kotlin only
+- **Trigger keywords:** "kotlin in action", "learn kotlin", "kotlin coroutines", "kotlin lambdas", "kotlin classes", "kotlin functions", "kotlin nullability", "how does kotlin"
+- **Anti-triggers:** Best practices advice (use effective-kotlin), non-Kotlin code
+- **Works well with:** effective-kotlin (learning + best practices)
+- **Conflicts with:** effective-kotlin (kotlin-in-action for learning features; effective-kotlin for best practice advice)
+
+## lean-startup
+- **Source:** *The Lean Startup* by Eric Ries
+- **Domain:** Startup strategy, MVP, validated learning, Build-Measure-Learn
+- **Language:** Not applicable (strategy skill)
+- **Trigger keywords:** "lean startup", "MVP", "validated learning", "pivot", "build-measure-learn", "product market fit", "hypothesis", "experiment", "runway"
+- **Anti-triggers:** Technical code review, architecture, any pure engineering concern
+- **Works well with:** None (strategy domain, not engineering)
+- **Conflicts with:** All technical skills (don't apply to code)
+
+## microservices-patterns
+- **Source:** *Microservices Patterns* by Chris Richardson
+- **Domain:** Microservices architecture, sagas, CQRS, API gateways, event sourcing
+- **Language:** Language-agnostic (Java Spring Boot examples)
+- **Trigger keywords:** "microservice", "saga", "CQRS", "event sourcing", "API gateway", "service mesh", "decompose monolith", "circuit breaker", "distributed transaction", "choreography", "orchestration"
+- **Anti-triggers:** Monolith-only code with no decomposition intent, pure domain modeling without service concerns
+- **Works well with:** domain-driven-design (service boundaries + domain model), system-design-interview (microservices + scale)
+- **Conflicts with:** domain-driven-design (microservices-patterns for service decomposition; DDD for domain model — apply both for new services)
+
+## refactoring-ui
+- **Source:** *Refactoring UI* by Adam Wathan & Steve Schoger
+- **Domain:** UI design, visual hierarchy, typography, color, layout, spacing
+- **Language:** CSS, HTML, any frontend
+- **Trigger keywords:** "UI design", "visual hierarchy", "typography", "color palette", "spacing", "layout", "design system", "refactor UI", "looks bad", "UI review"
+- **Anti-triggers:** Backend code, APIs, data processing, animation (use animation-at-work)
+- **Works well with:** animation-at-work (UI design + motion)
+- **Conflicts with:** animation-at-work (refactoring-ui for static design; animation-at-work for motion — they complement each other)
+
+## storytelling-with-data
+- **Source:** *Storytelling with Data* by Cole Nussbaumer Knaflic
+- **Domain:** Data visualization, charts, narrative structure
+- **Language:** Not applicable (visualization skill)
+- **Trigger keywords:** "data visualization", "chart", "graph", "dashboard", "storytelling", "declutter", "visual", "bar chart", "line chart", "scatter plot", "pie chart"
+- **Anti-triggers:** Code quality, backend processing, no visual component
+- **Works well with:** data-pipelines (pipeline data + visualization)
+- **Conflicts with:** None (niche visual domain)
+
+## system-design-interview
+- **Source:** *System Design Interview* by Alex Xu
+- **Domain:** High-level system architecture, scalability, estimation, real-world system designs
+- **Language:** Language-agnostic
+- **Trigger keywords:** "system design", "scale", "scalability", "back of envelope", "rate limiting", "CDN", "load balancer", "cache", "sharding", "high availability", "design YouTube", "design Twitter", "design a URL shortener"
+- **Anti-triggers:** Code-level review, domain modeling, specific language idioms
+- **Works well with:** data-intensive-patterns (high-level + storage internals), microservices-patterns (system design + service architecture)
+- **Conflicts with:** data-intensive-patterns (system-design-interview for high-level; data-intensive-patterns for storage internals)
+
+## using-asyncio-python
+- **Source:** *Using Asyncio in Python* by Caleb Hattingh
+- **Domain:** Python asyncio, coroutines, event loop, async patterns
+- **Language:** Python only
+- **Trigger keywords:** "asyncio", "async def", "await", "coroutine", "event loop", "aiohttp", "async Python", "concurrent Python", "Python concurrency"
+- **Anti-triggers:** Non-async Python, non-Python code
+- **Works well with:** effective-python (async + general Python best practices)
+- **Conflicts with:** effective-python (using-asyncio-python wins for any async topic)
+
+## web-scraping-python
+- **Source:** *Web Scraping with Python* by Ryan Mitchell
+- **Domain:** Web scraping, BeautifulSoup, Scrapy, data extraction
+- **Language:** Python only
+- **Trigger keywords:** "web scraping", "BeautifulSoup", "Scrapy", "requests", "crawl", "parse HTML", "selenium scraping", "extract data from website"
+- **Anti-triggers:** Non-scraping Python, general Python best practices
+- **Works well with:** effective-python (scraping + Python best practices), data-pipelines (scraping + ingestion)
+- **Conflicts with:** None (niche domain)

package/skill-router/scripts/route.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+route.py — CLI for skill-router
+
+Usage:
+    python route.py --task "review my Python class for code quality"
+    python route.py --file path/to/file.py --task "review for correctness"
+    python route.py --task "design a saga for order processing"
+    python route.py --task "decompose my monolith into microservices"
+
+Prints the recommended skill(s) with rationale.
+"""
+
+import argparse
+import os
+
+# Skill routing rules
+SKILL_CATALOG = {
+    "animation-at-work": {
+        "domain": "Web animation, UI motion",
+        "languages": [],  # language-agnostic but frontend
+        "keywords": ["animation", "motion", "transition", "keyframe", "easing", "css animation", "web animation"],
+        "anti_keywords": ["backend", "data processing", "api"],
+    },
+    "clean-code-reviewer": {
+        "domain": "Code quality, readability (any language)",
+        "languages": ["py", "java", "kt", "js", "ts", "go", "rs", "cpp", "cs"],
+        "keywords": ["review", "code quality", "readable", "clean", "refactor", "naming", "smell", "heuristic"],
+        "anti_keywords": ["architecture", "system design"],
+    },
+    "data-intensive-patterns": {
+        "domain": "Storage internals, distributed data",
+        "languages": [],
+        "keywords": ["replication", "partitioning", "consistency", "cap theorem", "storage engine", "lsm", "b-tree", "acid", "base", "linearizability"],
+        "anti_keywords": ["ui", "frontend", "domain model"],
+    },
+    "data-pipelines": {
+        "domain": "ETL, data ingestion, orchestration",
+        "languages": ["py", "sql"],
+        "keywords": ["data pipeline", "etl", "elt", "ingestion", "airflow", "dbt", "spark", "streaming", "batch", "warehouse"],
+        "anti_keywords": ["microservice", "ui"],
+    },
+    "design-patterns": {
+        "domain": "GoF OO design patterns",
+        "languages": ["java", "py", "kt", "cs"],
+        "keywords": ["design pattern", "factory", "singleton", "observer", "strategy", "decorator", "facade", "command", "template method", "composite"],
+        "anti_keywords": ["functional", "microservice decomposition"],
+    },
+    "domain-driven-design": {
+        "domain": "Domain modeling, DDD tactical and strategic patterns",
+        "languages": [],
+        "keywords": ["ddd", "domain model", "aggregate", "value object", "bounded context", "ubiquitous language", "repository", "domain service", "anticorruption", "entity", "anemic"],
+        "anti_keywords": ["simple crud", "ui", "code quality"],
+    },
+    "effective-java": {
+        "domain": "Java best practices",
+        "languages": ["java"],
+        "keywords": ["java", "generics", "enum", "lambda", "stream", "builder pattern", "serialization", "checked exception"],
+        "anti_keywords": [],
+    },
+    "effective-kotlin": {
+        "domain": "Kotlin best practices",
+        "languages": ["kt"],
+        "keywords": ["kotlin", "kotlin best practices", "kotlin safety", "null safety", "kotlin idioms", "effective kotlin", "best practices"],
+        "anti_keywords": ["learning kotlin"],
+    },
+    "effective-python": {
+        "domain": "Python idioms and best practices",
+        "languages": ["py"],
+        "keywords": ["pythonic", "python best practices", "comprehension", "generator", "decorator", "metaclass"],
+        "anti_keywords": ["async", "asyncio", "web scraping"],
+    },
+    "kotlin-in-action": {
+        "domain": "Kotlin language features",
+        "languages": ["kt"],
+        "keywords": ["learn kotlin", "kotlin coroutines", "kotlin lambdas", "kotlin classes", "how does kotlin"],
+        "anti_keywords": ["best practices"],
+    },
+    "lean-startup": {
+        "domain": "Startup strategy, MVP, validated learning",
+        "languages": [],
+        "keywords": ["mvp", "validated learning", "pivot", "build-measure-learn", "lean startup", "hypothesis", "product market fit"],
+        "anti_keywords": ["code", "review", "architecture", "api"],
+    },
+    "microservices-patterns": {
+        "domain": "Service decomposition, sagas, CQRS, event sourcing",
+        "languages": [],
+        "keywords": ["microservice", "services", "saga", "cqrs", "event sourcing", "api gateway", "decompose monolith", "circuit breaker", "distributed transaction", "choreography", "service coordination", "inter-service", "strangle", "strangler"],
+        "anti_keywords": ["monolith only", "simple crud"],
+    },
+    "refactoring-ui": {
+        "domain": "UI design, visual hierarchy, typography",
+        "languages": ["css", "html", "jsx", "tsx", "svelte"],
+        "keywords": ["ui design", "visual hierarchy", "typography", "color", "spacing", "layout", "design system"],
+        "anti_keywords": ["backend", "api", "animation"],
+    },
+    "storytelling-with-data": {
+        "domain": "Data visualization, charts, narrative",
+        "languages": [],
+        "keywords": ["data visualization", "chart", "graph", "dashboard", "storytelling", "declutter", "bar chart", "scatter plot"],
+        "anti_keywords": ["backend", "api", "code quality"],
+    },
+    "system-design-interview": {
+        "domain": "System scalability, high-level architecture",
+        "languages": [],
+        "keywords": ["system design", "scale", "scalability", "rate limiting", "cdn", "load balancer", "cache", "sharding", "high availability"],
+        "anti_keywords": ["code review", "domain model"],
+    },
+    "using-asyncio-python": {
+        "domain": "Python asyncio, concurrency",
+        "languages": ["py"],
+        "keywords": ["asyncio", "async def", "await", "coroutine", "event loop", "aiohttp", "async python", "concurrent python"],
+        "anti_keywords": [],
+    },
+    "web-scraping-python": {
+        "domain": "Web scraping, crawling",
+        "languages": ["py"],
+        "keywords": ["web scraping", "beautifulsoup", "scrapy", "crawl", "parse html", "selenium scraping"],
+        "anti_keywords": [],
+    },
+}
+
+CONFLICT_RULES = [
+    ("effective-python", "using-asyncio-python", "using-asyncio-python wins for async topics"),
+    ("kotlin-in-action", "effective-kotlin", "effective-kotlin wins for best practice advice"),
+    ("clean-code-reviewer", "effective-java", "effective-java wins for Java-specific items; use both for comprehensive review"),
+]
+
+
+def detect_language(file_path: str | None) -> str | None:
+    """Detect language from file extension."""
+    if not file_path:
+        return None
+    ext = os.path.splitext(file_path)[1].lstrip(".")
+    return ext.lower() if ext else None
+
+
+def score_skill(skill_name: str, skill_info: dict, task: str, language: str | None) -> float:
+    """Score a skill's relevance for a task. Higher = more relevant."""
+    task_lower = task.lower()
+    score = 0.0
+
+    # Keyword matching
+    for keyword in skill_info["keywords"]:
+        if keyword in task_lower:
+            score += 2.0
+
+    # Anti-keyword penalty
+    for anti_keyword in skill_info["anti_keywords"]:
+        if anti_keyword in task_lower:
+            score -= 3.0
+
+    # Language match bonus
+    if language and language in skill_info["languages"]:
+        score += 3.0
+    elif skill_info["languages"] and language and language not in skill_info["languages"]:
+        score -= 5.0  # Strong penalty for language mismatch
+
+    return score
+
+
+def route(task: str, file_path: str | None = None) -> dict:
+    """Route a task to the best skill(s)."""
+    language = detect_language(file_path)
+    task_lower = task.lower()
+
+    scores = {}
+    keyword_hits = {}
+    for skill_name, skill_info in SKILL_CATALOG.items():
+        scores[skill_name] = score_skill(skill_name, skill_info, task, language)
+        keyword_hits[skill_name] = any(kw in task_lower for kw in skill_info["keywords"])
+
+    # Sort by score, descending
+    ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+
+    # Require positive score AND at least one keyword hit to prevent
+    # language-match-only false positives (e.g. data-pipelines for any .py file)
+    candidates = [(name, score) for name, score in ranked if score > 0 and keyword_hits[name]]
+
+    if not candidates:
+        return {
+            "primary": None,
+            "secondary": None,
+            "dont_apply": None,
+            "conflict_note": None,
+            "language_detected": language,
+            "rationale": "No skill matched. Try describing the task with more domain keywords, or browse the skill catalog.",
+        }
+
+    primary_name, _ = candidates[0]
+    secondary = candidates[1] if len(candidates) > 1 else None
+    dont_apply = candidates[2] if len(candidates) > 2 else None
+
+    # Apply conflict resolution
+    conflict_note = None
+    if secondary:
+        for skill_a, skill_b, note in CONFLICT_RULES:
+            if (primary_name == skill_a and secondary[0] == skill_b) or \
+               (primary_name == skill_b and secondary[0] == skill_a):
+                conflict_note = note
+                break
+
+    return {
+        "primary": primary_name,
+        "primary_domain": SKILL_CATALOG[primary_name]["domain"],
+        "secondary": secondary[0] if secondary else None,
+        "secondary_domain": SKILL_CATALOG[secondary[0]]["domain"] if secondary else None,
+        "dont_apply": dont_apply[0] if dont_apply else None,
+        "dont_apply_domain": SKILL_CATALOG[dont_apply[0]]["domain"] if dont_apply else None,
+        "conflict_note": conflict_note,
+        "language_detected": language,
+    }
+
+
+def format_output(result: dict) -> str:
+    """Format routing result for CLI output."""
+    lines = []
+
+    if result.get("language_detected"):
+        lines.append(f"Detected language: .{result['language_detected']}")
+        lines.append("")
+
+    if not result["primary"]:
+        lines.append("No matching skill found.")
+        lines.append(result.get("rationale", ""))
+        return "\n".join(lines)
+
+    lines.append(f"**Primary skill:** `{result['primary']}`")
+    lines.append(f"**Why:** {result['primary_domain']}")
+
+    if result["secondary"]:
+        lines.append(f"**Secondary (optional):** `{result['secondary']}` — {result['secondary_domain']}")
+    else:
+        lines.append("**Secondary (optional):** none")
+
+    if result.get("dont_apply"):
+        lines.append(f"**Don't apply:** `{result['dont_apply']}` — {result['dont_apply_domain']} (lower relevance for this task)")
+
+    if result.get("conflict_note"):
+        lines.append(f"**Conflict resolution:** {result['conflict_note']}")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Route a task to the best @booklib/skills skill",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  python route.py --task "review my Python class for code quality"
+  python route.py --file app/orders.py --task "review for correctness"
+  python route.py --task "design a saga for order processing"
+  python route.py --task "decompose my monolith into microservices"
+  python route.py --task "my bar chart is too cluttered"
+        """,
+    )
+    parser.add_argument("--file", help="Path to the file being reviewed (used for language detection)")
+    parser.add_argument("--task", required=True, help="Description of the task or question")
+    args = parser.parse_args()
+
+    result = route(task=args.task, file_path=args.file)
+    print(format_output(result))
+
+
+if __name__ == "__main__":
+    main()