@booklib/skills 1.2.0 → 1.3.1

package/refactoring-ui/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-poor-visual-hierarchy",
+      "prompt": "Review this CSS for a product card component:\n\n```css\n.product-card {\n  padding: 20px;\n  border: 1px solid #cccccc;\n  border-radius: 4px;\n  background: white;\n}\n\n.product-card .category-label {\n  font-size: 16px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-name {\n  font-size: 18px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-price {\n  font-size: 16px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 8px;\n}\n\n.product-card .product-description {\n  font-size: 15px;\n  font-weight: 400;\n  color: #333333;\n  margin-bottom: 12px;\n}\n\n.product-card .stock-status {\n  font-size: 14px;\n  font-weight: 400;\n  color: #333333;\n}\n\n.product-card .add-to-cart-btn {\n  font-size: 16px;\n  font-weight: 400;\n  background: #333333;\n  color: white;\n  padding: 10px 20px;\n  border: none;\n  border-radius: 4px;\n  margin-top: 12px;\n}\n```",
+      "expectations": [
+        "Identifies the core problem: visual hierarchy is flat — nearly every element uses the same font-size (15-18px) and font-weight (400), making it impossible to identify what matters most at a glance",
+        "Flags that the product name should be the most visually prominent element — it should use a larger size (24-30px) and heavier weight (600-700) to create a clear entry point",
+        "Flags that the price is the second most important element — it should be visually distinct, not the same weight as the description",
+        "Points out that category-label should be de-emphasized (smaller, lighter color like hsl(0,0%,55%)) — it is supporting context, not primary information",
+        "Notes that relying on font-size alone for hierarchy is addressed in Chapter 2 of Refactoring UI: use weight and color as primary levers, size as secondary",
+        "Flags that all elements use the same color (#333333) — tertiary elements like category-label and stock-status should use a lighter grey to create visual separation",
+        "Notes the add-to-cart button has font-weight: 400 — a primary action button should use font-weight 500-600 for emphasis",
+        "Recommends a concrete hierarchy: product-name (24px, 700 weight, dark), price (20px, 600 weight, dark), description (15px, 400 weight, medium grey #6b7280), category-label (12px, 500 weight, uppercase, light grey)"
+      ]
+    },
+    {
+      "id": "eval-02-too-many-colors-no-spacing-system",
+      "prompt": "Review this CSS for a dashboard sidebar:\n\n```css\n.sidebar {\n  background: #1a237e;\n  padding: 15px;\n  width: 240px;\n}\n\n.sidebar-header {\n  color: #ffffff;\n  font-size: 22px;\n  margin-bottom: 7px;\n  padding-bottom: 11px;\n  border-bottom: 2px solid #3949ab;\n}\n\n.nav-item {\n  color: #b0bec5;\n  font-size: 14px;\n  padding: 9px 13px;\n  margin-bottom: 3px;\n  border-radius: 6px;\n}\n\n.nav-item.active {\n  background: #ff6f00;\n  color: #ffffff;\n}\n\n.nav-item:hover {\n  background: #283593;\n  color: #e8eaf6;\n}\n\n.nav-section-label {\n  color: #ffd54f;\n  font-size: 11px;\n  text-transform: uppercase;\n  margin-top: 18px;\n  margin-bottom: 6px;\n  letter-spacing: 1px;\n}\n\n.badge {\n  background: #e53935;\n  color: white;\n  font-size: 10px;\n  padding: 2px 7px;\n  border-radius: 10px;\n}\n\n.sidebar-footer {\n  margin-top: 23px;\n  padding-top: 14px;\n  border-top: 1px solid #303f9f;\n  color: #90a4ae;\n  font-size: 13px;\n}\n```",
+      "expectations": [
+        "Identifies the color proliferation problem: #1a237e, #3949ab, #ff6f00, #b0bec5, #283593, #e8eaf6, #ffd54f, #e53935, #303f9f, #90a4ae — 10+ ad-hoc hex colors with no systematic relationship",
+        "Flags that the active state uses #ff6f00 (deep orange) which is unrelated to the #1a237e (indigo) background — the accent color should be a lighter tint of the primary palette or a purposeful brand color",
+        "Flags that nav-section-label uses #ffd54f (amber/yellow) as a color — this creates a third unrelated hue in the sidebar; section labels should use a desaturated light color consistent with the palette",
+        "Flags the arbitrary spacing values: 7px, 11px, 9px, 13px, 3px, 18px, 6px, 23px, 14px — none of these follow a spacing scale; Refactoring UI Ch 3 prescribes a constrained scale (4, 8, 12, 16, 24, 32px)",
+        "Notes that grey-on-deep-blue text (#b0bec5 on #1a237e) needs a contrast check — and recommends using a color that is hue-matched to the background rather than a neutral grey",
+        "Recommends defining a design token set: 2-3 shades of indigo for the sidebar tones, one accent color for the active state, one semantic red for the badge — not 10 unrelated hex values",
+        "Notes that the badge using an unrelated red (#e53935) is fine for semantic meaning but should be defined as a token (--color-danger) rather than a hard-coded hex"
+      ]
+    },
+    {
+      "id": "eval-03-clean-hierarchy-design",
+      "prompt": "Review this CSS for a pricing card component:\n\n```css\n:root {\n  --space-1: 4px;\n  --space-2: 8px;\n  --space-3: 12px;\n  --space-4: 16px;\n  --space-6: 24px;\n  --space-8: 32px;\n  --space-12: 48px;\n\n  --text-sm: 13px;\n  --text-base: 16px;\n  --text-lg: 18px;\n  --text-xl: 20px;\n  --text-3xl: 30px;\n\n  --color-text-primary: hsl(222, 47%, 11%);\n  --color-text-secondary: hsl(215, 20%, 40%);\n  --color-text-tertiary: hsl(215, 16%, 60%);\n  --color-accent: hsl(245, 75%, 60%);\n  --color-accent-light: hsl(245, 75%, 96%);\n}\n\n.pricing-card {\n  background: white;\n  border-radius: 12px;\n  padding: var(--space-8);\n  box-shadow: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);\n  max-width: 320px;\n}\n\n.plan-name {\n  font-size: var(--text-sm);\n  font-weight: 600;\n  color: var(--color-accent);\n  text-transform: uppercase;\n  letter-spacing: 0.08em;\n  margin-bottom: var(--space-3);\n}\n\n.plan-price {\n  font-size: var(--text-3xl);\n  font-weight: 700;\n  color: var(--color-text-primary);\n  margin-bottom: var(--space-1);\n}\n\n.price-period {\n  font-size: var(--text-sm);\n  color: var(--color-text-tertiary);\n  margin-bottom: var(--space-6);\n}\n\n.feature-list {\n  list-style: none;\n  padding: 0;\n  margin: 0 0 var(--space-8) 0;\n}\n\n.feature-item {\n  font-size: var(--text-base);\n  color: var(--color-text-secondary);\n  padding: var(--space-2) 0;\n  display: flex;\n  align-items: center;\n  gap: var(--space-3);\n}\n\n.cta-button {\n  display: block;\n  width: 100%;\n  padding: var(--space-3) var(--space-6);\n  background: var(--color-accent);\n  color: white;\n  font-size: var(--text-base);\n  font-weight: 600;\n  border: none;\n  border-radius: 8px;\n  cursor: pointer;\n  text-align: center;\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed component with proper design system foundations and says so explicitly",
+        "Praises the CSS custom property (design token) system: spacing scale (--space-1 through --space-12 in steps of 4px), type scale (--text-sm through --text-3xl), and color tokens all follow Refactoring UI principles",
+        "Praises the three-level color hierarchy for text: --color-text-primary (dark), --color-text-secondary (medium), --color-text-tertiary (light) — directly implementing the Refactoring UI color-as-hierarchy approach",
+        "Praises the visual hierarchy of the price card: plan name is small+uppercase+accent (supporting), price is 30px+700 weight (primary), period is small+tertiary (de-emphasized) — excellent three-tier hierarchy",
+        "Praises the shadow: uses a two-layer shadow (diffuse + tight) following the Refactoring UI recommendation for realistic depth",
+        "Praises that plan-name uses color (--color-accent) to create emphasis at a small size rather than making it large — using color+weight as levers, not font-size alone",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional improvements (hover state for cta-button, dark mode token variants, focus ring for accessibility) but clearly frames them as enhancements"
+      ]
+    }
+  ]
+}

package/refactoring-ui/examples/after.md

@@ -0,0 +1,85 @@
+# After
+
+A pricing card with clear visual hierarchy achieved through size scale, weight contrast, and strategic color — the price is immediately scannable and the CTA stands out.
+
+```css
+/* Pricing card — clear hierarchy: plan name → price → description → features → CTA */
+.pricing-card {
+  padding: 32px;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07), 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+/* Primary: the plan name — bold, medium size, dark */
+.plan-name {
+  font-size: 14px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: hsl(217, 71%, 53%);   /* brand accent — signals plan identity */
+  margin-bottom: 12px;
+}
+
+/* Hero element: price — the largest, heaviest thing on the card */
+.plan-price {
+  font-size: 48px;
+  font-weight: 700;
+  color: hsl(222, 47%, 11%);   /* near-black — maximum contrast */
+  line-height: 1;
+  margin-bottom: 4px;
+}
+
+.plan-billing-cycle {
+  font-size: 13px;
+  font-weight: 400;
+  color: hsl(215, 16%, 57%);   /* light grey — tertiary, supporting */
+  margin-bottom: 20px;
+}
+
+/* Secondary: description — readable but not competing with price */
+.plan-description {
+  font-size: 15px;
+  font-weight: 400;
+  color: hsl(215, 16%, 40%);   /* medium grey */
+  line-height: 1.6;
+  margin-bottom: 24px;
+}
+
+/* Tertiary: feature list — smallest, least emphasis */
+.plan-feature {
+  font-size: 14px;
+  font-weight: 400;
+  color: hsl(215, 16%, 47%);
+  margin-bottom: 8px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+/* CTA: high contrast, full width, inviting */
+.cta-button {
+  width: 100%;
+  padding: 14px;
+  font-size: 15px;
+  font-weight: 600;
+  background-color: hsl(217, 71%, 53%);
+  color: #ffffff;
+  border: none;
+  border-radius: 6px;
+  margin-top: 28px;
+  cursor: pointer;
+}
+
+.cta-button:hover {
+  background-color: hsl(217, 71%, 46%);
+}
+```
+
+Key improvements:
+- Three-tier hierarchy established using size (48px → 15px → 14px → 13px), weight (700 → 600 → 400), and color (near-black → medium grey → light grey) — no element competes with the price (Ch 2: Visual Hierarchy)
+- HSL colors replace raw hex — the system is transparent and the grey scale is predictable (Ch 5: Build a color system with HSL)
+- `box-shadow` with two layered shadows replaces the flat `border: 1px solid #ccc` — the card lifts off the page with realistic depth (Ch 6: Depth and shadow elevation)
+- `.plan-name` uses uppercase + letter-spacing as a tertiary-element technique — it occupies a clear role without competing with the price despite appearing first (Ch 2: De-emphasize labels, emphasize values)
+- Consistent spacing from the scale (12, 20, 24, 28px) replaces arbitrary margins — related elements are visually grouped (Ch 3: Spacing and layout)
+- CTA `padding: 14px` and `font-weight: 600` make the button unmistakably actionable, distinct from all other text on the card (Ch 8: Finishing touches)

package/refactoring-ui/examples/before.md

@@ -0,0 +1,58 @@
+# Before
+
+A CSS card component where every text element is the same size and weight, creating no visual hierarchy and making it impossible to scan at a glance.
+
+```css
+/* Pricing card — everything looks equally important */
+.pricing-card {
+  padding: 20px;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+}
+
+.plan-name {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-description {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-price {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-billing-cycle {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 16px;
+}
+
+.plan-feature {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 4px;
+}
+
+.cta-button {
+  width: 100%;
+  padding: 10px;
+  font-size: 16px;
+  font-weight: 400;
+  background-color: #555;
+  color: white;
+  border: none;
+  border-radius: 4px;
+}
+```

package/refactoring-ui/scripts/audit_css.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+audit_css.py — Audit CSS/SCSS/HTML files for Refactoring UI anti-patterns.
+Usage: python audit_css.py <file_or_directory>
+
+Detects:
+  1. One-off hex colors (likely not from a design scale)
+  2. Arbitrary pixel values not on a standard spacing scale
+  3. Flat visual hierarchy (too many elements sharing the same font-size)
+  4. Inline styles in HTML (maintainability anti-pattern)
+"""
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+SPACING_SCALE = {4, 8, 10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 56, 64, 80, 96, 112, 128}
+FLAT_HIERARCHY_THRESHOLD = 3   # more than N elements sharing same font-size
+EXTENSIONS = {".css", ".scss", ".html", ".htm"}
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+RE_HEX_COLOR = re.compile(r"#([0-9a-fA-F]{3,8})\b")
+RE_PX_VALUE = re.compile(r"\b(\d+)px\b")
+RE_FONT_SIZE_PX = re.compile(r"font-size\s*:\s*(\d+)px", re.IGNORECASE)
+RE_INLINE_STYLE = re.compile(r'\bstyle\s*=\s*["\'][^"\']*["\']', re.IGNORECASE)
+RE_CSS_VAR = re.compile(r"var\(--[^)]+\)")
+RE_SCSS_VAR = re.compile(r"\$[a-zA-Z_][\w-]*")
+
+# Pixel properties where arbitrary values matter (spacing/sizing, not borders)
+SPACING_PROPERTIES = re.compile(
+    r"(margin|padding|top|right|bottom|left|width|height|gap|"
+    r"border-radius|letter-spacing|line-height)\s*:",
+    re.IGNORECASE,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+Issue = dict  # {"line": int, "col": int, "code": str, "message": str, "suggestion": str}
+
+
+def read_lines(path: Path) -> list[str]:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as exc:
+        print(f"Warning: cannot read {path}: {exc}")
+        return []
+
+
+def is_in_comment(line: str, col: int) -> bool:
+    """Rough check: is the match inside a CSS/HTML comment on this line?"""
+    before = line[:col]
+    return "/*" in before or "<!--" in before or "//" in before
+
+
+# ---------------------------------------------------------------------------
+# Detectors
+# ---------------------------------------------------------------------------
+
+def detect_one_off_hex_colors(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag hex colors that appear only once in the file — likely not from a scale."""
+    color_locations: dict[str, list[tuple[int, int]]] = defaultdict(list)
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_HEX_COLOR.finditer(line):
+            # Skip if preceded by var( or $ (already a token)
+            prefix = line[max(0, m.start() - 10):m.start()]
+            if "var(" in prefix or "$" in prefix[-1:]:
+                continue
+            normalized = m.group(0).upper()
+            color_locations[normalized].append((lineno, m.start()))
+
+    issues = []
+    for color, locations in color_locations.items():
+        if len(locations) == 1:
+            lineno, col = locations[0]
+            issues.append({
+                "line": lineno, "col": col + 1,
+                "code": "RUI-C01",
+                "message": f"One-off color {color} — not reused anywhere in this file",
+                "suggestion": f"Extract to a CSS variable: --color-name: {color}; and reference via var(--color-name)",
+            })
+    return issues
+
+
+def detect_arbitrary_px_values(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag pixel values on spacing properties that fall outside the spacing scale."""
+    issues = []
+    in_spacing_context = False
+    for lineno, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if SPACING_PROPERTIES.search(stripped):
+            for m in RE_PX_VALUE.finditer(stripped):
+                value = int(m.group(1))
+                if value == 0 or value in SPACING_SCALE:
+                    continue
+                if is_in_comment(line, m.start()):
+                    continue
+                nearest = min(SPACING_SCALE, key=lambda s: abs(s - value))
+                issues.append({
+                    "line": lineno, "col": m.start() + 1,
+                    "code": "RUI-S01",
+                    "message": f"Arbitrary pixel value {value}px not on spacing scale",
+                    "suggestion": f"Nearest scale value: {nearest}px. Consider using a spacing token.",
+                })
+    return issues
+
+
+def detect_flat_hierarchy(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag when many rules share the same font-size — suggests flat visual hierarchy."""
+    size_locations: dict[int, list[tuple[int, int]]] = defaultdict(list)
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_FONT_SIZE_PX.finditer(line):
+            size = int(m.group(1))
+            size_locations[size].append((lineno, m.start()))
+
+    issues = []
+    for size, locations in size_locations.items():
+        if len(locations) > FLAT_HIERARCHY_THRESHOLD:
+            # Report at the first occurrence
+            lineno, col = locations[0]
+            issues.append({
+                "line": lineno, "col": col + 1,
+                "code": "RUI-H01",
+                "message": (
+                    f"font-size: {size}px used {len(locations)} times — "
+                    f"indicates flat visual hierarchy"
+                ),
+                "suggestion": (
+                    "Refactoring UI: vary font sizes more aggressively to create "
+                    "clear hierarchy. Use a type scale (e.g. 12, 14, 16, 20, 24, 32, 48px)."
+                ),
+            })
+    return issues
+
+
+def detect_inline_styles(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag inline style= attributes in HTML files."""
+    if filepath.suffix.lower() not in {".html", ".htm"}:
+        return []
+    issues = []
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_INLINE_STYLE.finditer(line):
+            issues.append({
+                "line": lineno, "col": m.start() + 1,
+                "code": "RUI-M01",
+                "message": f"Inline style attribute — hard to maintain and override",
+                "suggestion": "Move styles to a CSS class. Inline styles defeat cascade and make theming impossible.",
+            })
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Scanner
+# ---------------------------------------------------------------------------
+
+def scan_file(path: Path) -> list[Issue]:
+    lines = read_lines(path)
+    if not lines:
+        return []
+    issues = []
+    issues.extend(detect_one_off_hex_colors(lines, path))
+    issues.extend(detect_arbitrary_px_values(lines, path))
+    issues.extend(detect_flat_hierarchy(lines, path))
+    issues.extend(detect_inline_styles(lines, path))
+    return sorted(issues, key=lambda i: (i["line"], i["col"]))
+
+
+def collect_files(target: Path) -> list[Path]:
+    if target.is_file():
+        return [target] if target.suffix.lower() in EXTENSIONS else []
+    return sorted(p for p in target.rglob("*") if p.suffix.lower() in EXTENSIONS)
+
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+
+def print_report(results: dict[Path, list[Issue]]) -> int:
+    total = sum(len(v) for v in results.values())
+    files_with_issues = sum(1 for v in results.values() if v)
+
+    print("=" * 72)
+    print("REFACTORING UI CSS AUDIT REPORT")
+    print("=" * 72)
+
+    # Group by code across all files for summary
+    by_code: dict[str, list[tuple[Path, Issue]]] = defaultdict(list)
+
+    for path, issues in results.items():
+        if not issues:
+            continue
+        print(f"\n{path}")
+        print("-" * 72)
+        for issue in issues:
+            print(f"  Line {issue['line']:>4}:{issue['col']:<4} [{issue['code']}] {issue['message']}")
+            print(f"           -> {issue['suggestion']}")
+            by_code[issue["code"]].append((path, issue))
+
+    print("\n" + "=" * 72)
+    print("SUMMARY")
+    print("=" * 72)
+    CODE_LABELS = {
+        "RUI-C01": "One-off colors (not from a scale)",
+        "RUI-S01": "Arbitrary pixel values",
+        "RUI-H01": "Flat visual hierarchy",
+        "RUI-M01": "Inline styles in HTML",
+    }
+    for code, label in CODE_LABELS.items():
+        count = len(by_code.get(code, []))
+        marker = "[!]" if count else "[OK]"
+        print(f"  {marker} {label}: {count} issue(s)")
+
+    print(f"\nFiles scanned : {len(results)}")
+    print(f"Files with issues: {files_with_issues}")
+    print(f"Total issues  : {total}")
+    print("=" * 72)
+    return total
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python audit_css.py <file_or_directory>")
+        sys.exit(1)
+
+    target = Path(sys.argv[1])
+    if not target.exists():
+        print(f"Error: path not found: {target}")
+        sys.exit(1)
+
+    files = collect_files(target)
+    if not files:
+        print(f"No CSS/SCSS/HTML files found in: {target}")
+        sys.exit(0)
+
+    results = {f: scan_file(f) for f in files}
+    total = print_report(results)
+    sys.exit(1 if total else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skill-router/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: skill-router
+description: >
+  Select the 1-2 most relevant @booklib/skills for a given file, PR, or task.
+  Use before applying any skill when unsure which book's lens applies, or when
+  multiple skills could apply. Trigger on "which skill", "which book", "route this",
+  "what skill should I use", or whenever a user describes a task without specifying
+  a skill. Returns a ranked recommendation with rationale and anti-triggers.
+---
+
+# Skill Router
+
+You are a skill selector for the `@booklib/skills` library — a collection of 17 book-based AI skills covering code quality, architecture, language best practices, and design. Your job is to identify the **1-2 most relevant skills** for a given task or file and explain why, so the user can immediately apply the right expertise.
+
+## When You're Triggered
+
+- User says "which skill should I use for..."
+- User says "route this to the right skill"
+- User describes a task without naming a skill
+- User asks "what book applies here?"
+- Multiple skills seem to apply and you need to rank them
+
+---
+
+## Routing Process
+
+### Step 1 — Classify the Work Type
+
+Identify what the user is trying to do:
+
+| Work Type | Description | Example |
+|-----------|-------------|---------|
+| **review** | Evaluate existing code for quality, patterns, or correctness | "Review my Python class" |
+| **generate** | Create new code following a book's patterns | "Generate a saga for order processing" |
+| **migrate** | Incrementally improve legacy code toward a better architecture | "Help me ratchet this legacy codebase toward clean code" |
+| **design** | Make architectural or system-level decisions | "How should I decompose this monolith?" |
+| **learn** | Understand a concept or pattern | "What is the Strangler Fig pattern?" |
+| **visualize** | Create or critique data visualizations or UI | "Review my chart / UI component" |
+
+### Step 2 — Identify Language + Domain
+
+From the file extension, imports, description, or code provided:
+
+- **Language signals:** `.py` → Python skills; `.java` → `effective-java` or `clean-code-reviewer`; `.kt` → `effective-kotlin` or `kotlin-in-action`; `.js`/`.ts` → `clean-code-reviewer` or `design-patterns`
+- **Domain signals:** "microservice", "saga" → microservices-patterns; "bounded context", "aggregate" → domain-driven-design; "chart", "visualization" → storytelling-with-data; "UI", "layout", "typography" → refactoring-ui; "web scraping", "BeautifulSoup" → web-scraping-python; "asyncio", "coroutine" → using-asyncio-python; "data pipeline", "ETL" → data-pipelines; "replication", "partitioning", "database internals" → data-intensive-patterns
+- **Architecture signals:** "monolith decomposition", "distributed systems" → microservices-patterns or system-design-interview
+
+Read `references/skill-catalog.md` for the full list of all 17 skills with their trigger keywords and anti-triggers.
+
+### Step 3 — Match to Skill(s)
+
+Apply these primary routing rules:
+
+1. **Code quality review (any language)** → `clean-code-reviewer`
+2. **Java best practices** → `effective-java`
+3. **Kotlin best practices** → `effective-kotlin` or `kotlin-in-action` (see conflict rules)
+4. **Python best practices** → `effective-python`
+5. **Python asyncio/concurrency** → `using-asyncio-python` (overrides effective-python for async topics)
+6. **Python web scraping** → `web-scraping-python`
+7. **OO design patterns (GoF)** → `design-patterns`
+8. **Domain modeling, DDD** → `domain-driven-design`
+9. **Microservices, sagas, decomposition** → `microservices-patterns`
+10. **System scalability, estimation** → `system-design-interview`
+11. **Data storage internals, replication** → `data-intensive-patterns`
+12. **Data pipelines, ETL** → `data-pipelines`
+13. **UI design, visual hierarchy** → `refactoring-ui`
+14. **Charts, data visualization** → `storytelling-with-data`
+15. **Web animation** → `animation-at-work`
+16. **Startup strategy, MVP** → `lean-startup`
+17. **Routing help** → `skill-router` (this skill)
+
+Read `references/routing-heuristics.md` for detailed decision rules and conflict resolution.
+
+### Step 4 — Check for Conflicts
+
+Some skill pairs can conflict. Resolve using these rules:
+
+| Conflict | Resolution |
+|----------|------------|
+| `clean-code-reviewer` vs `effective-java` | Use `effective-java` for Java-specific idioms (generics, enums, builders); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
+| `effective-kotlin` vs `kotlin-in-action` | `effective-kotlin` for best practices and pitfall avoidance; `kotlin-in-action` for learning Kotlin language features |
+| `domain-driven-design` vs `microservices-patterns` | `domain-driven-design` for domain model design; `microservices-patterns` for service decomposition and inter-service communication. Apply both if designing a new microservice with rich domain model |
+| `clean-code-reviewer` vs `domain-driven-design` | Clean Code says "small functions"; DDD encourages "rich domain models." Clean Code wins for code-level review; DDD wins for model design |
+| `data-intensive-patterns` vs `system-design-interview` | `data-intensive-patterns` for storage engine internals, replication, and consistency; `system-design-interview` for scalability estimates and high-level architecture |
+| `effective-python` vs `using-asyncio-python` | `using-asyncio-python` wins for any async/concurrent Python topic; `effective-python` for everything else |
+
+### Step 5 — Return Recommendation
+
+Format your output as:
+
+```
+**Primary skill:** `skill-name`
+**Why:** [1-2 sentence rationale tying the task to the skill's domain]
+**Secondary (optional):** `skill-name` — [brief rationale] OR none
+**Don't apply:** `skill-name` — [why it would produce irrelevant feedback]
+```
+
+If you're genuinely uncertain between two equally applicable skills, say so and recommend applying both in sequence, primary first.
+
+---
+
+## Anti-Trigger Rules
+
+Do NOT route to a skill if:
+- The task is too simple for that skill's complexity (don't route a 5-line script to `domain-driven-design`)
+- The language doesn't match (don't route Python to `effective-java`)
+- The domain doesn't match (don't route UI code to `microservices-patterns`)
+- The user has already specified a skill (respect their choice; only offer alternatives if asked)
+
+---
+
+## Examples
+
+**Example 1 — Clear single-skill case:**
+```
+User: "Review my Python class for code quality"
+
+Primary skill: clean-code-reviewer
+Why: Language-agnostic code quality review is exactly Clean Code's domain — naming, functions, comments, classes.
+Secondary: none
+Don't apply: effective-python — Python-specific idioms are not the concern here; effective-python would focus on list comprehensions and context managers, not the general code quality issues Clean Code addresses.
+```
+
+**Example 2 — Conflict case:**
+```
+User: "I'm building a new microservice for our e-commerce platform. Review the domain model."
+
+Primary skill: domain-driven-design
+Why: The request is about domain model design — Aggregates, Value Objects, Bounded Contexts. DDD is the authoritative source.
+Secondary: microservices-patterns — apply after DDD review to check service boundaries, database ownership, and communication patterns.
+Don't apply: clean-code-reviewer — code quality review is premature at the design stage; apply later when implementation code exists.
+```
+
+**Example 3 — Already routed (positive case):**
+```
+User: "Use the effective-java skill to review my builder pattern"
+
+Primary skill: effective-java (already specified by user — confirm and proceed)
+Why: User correctly identified the skill. effective-java Item 2 covers the Builder pattern directly.
+Secondary: none
+Don't apply: design-patterns — GoF Builder pattern is covered, but Effective Java's opinionated take on Java-specific Builder is more directly applicable.
+```

package/skill-router/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-clear-single-skill",
+      "prompt": "Which skill should I use? I have this Python function and want to make it more Pythonic:\n\n```python\ndef get_items(items_list, filter_value, sort_by_name):\n    result = []\n    for item in items_list:\n        if item['category'] == filter_value:\n            result.append(item)\n    if sort_by_name:\n        result = sorted(result, key=lambda x: x['name'])\n    return result\n```",
+      "expectations": [
+        "Recommends effective-python as primary skill",
+        "Mentions that Pythonic idioms (list comprehensions, key functions, boolean flags) are effective-python's domain",
+        "Does NOT recommend clean-code-reviewer as primary (it's secondary at most)",
+        "Explains why (language-specific Pythonic advice vs general code quality)",
+        "Optionally mentions clean-code-reviewer as secondary for the flag argument (sort_by_name)"
+      ]
+    },
+    {
+      "id": "eval-02-conflict-case",
+      "prompt": "I'm designing a new service for our e-commerce platform. The service will handle order creation and needs to coordinate with the inventory and payment services. Here's a rough sketch:\n\n```python\nclass OrderService:\n    def create_order(self, customer_id, items):\n        # 1. Check inventory availability\n        # 2. Reserve inventory\n        # 3. Charge payment\n        # If payment fails, how do I release the reservation?\n        pass\n\n    def cancel_order(self, order_id):\n        # Need to reverse payment AND release inventory\n        # What if one fails?\n        pass\n```\n\nWhich skill should I use to design this coordination correctly?",
+      "expectations": [
+        "Identifies this as a design task, not a code review task",
+        "Recommends microservices-patterns as primary (service coordination, saga pattern)",
+        "Recommends domain-driven-design as secondary (order domain modeling)",
+        "Explains the distinction: microservices-patterns for inter-service coordination, DDD for domain model design",
+        "Does NOT recommend clean-code-reviewer (no code to review yet)",
+        "Does NOT recommend system-design-interview unless scale/estimation is mentioned"
+      ]
+    },
+    {
+      "id": "eval-03-already-routed",
+      "prompt": "Use the effective-java skill to review my enum usage:\n\n```java\npublic class OrderStatus {\n    public static final int PENDING = 0;\n    public static final int APPROVED = 1;\n    public static final int REJECTED = 2;\n    public static final int CANCELLED = 3;\n}\n```",
+      "expectations": [
+        "Confirms effective-java is the correct skill (already specified by user)",
+        "Does NOT override the user's skill choice",
+        "Optionally notes which Effective Java item applies (Item 34: Use enums instead of int constants)",
+        "May note clean-code-reviewer would also flag this (J3: Constants vs Enums) but defers to user's choice",
+        "Does not second-guess or add unnecessary routing complexity"
+      ]
+    }
+  ]
+}