@booklib/skills 1.5.2 → 1.6.0

package/commands/microservices-patterns.md

@@ -0,0 +1,10 @@
+---
+description: Review microservice architecture using patterns from Chris Richardson. Usage: /microservices-patterns [file | path | description]
+---
+
+Apply the `microservices-patterns` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on service decomposition, sagas, event sourcing, API gateways, and inter-service communication. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/programming-with-rust.md

@@ -0,0 +1,10 @@
+---
+description: Review Rust code against Programming with Rust (Donis Marshall). Usage: /programming-with-rust [file | path]
+---
+
+Apply the `programming-with-rust` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on ownership, borrowing, lifetimes, traits, and safe concurrency patterns. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/refactoring-ui.md

@@ -0,0 +1,10 @@
+---
+description: Review UI design against Refactoring UI principles (Wathan & Schoger). Usage: /refactoring-ui [file | component | screenshot path]
+---
+
+Apply the `refactoring-ui` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review changed UI components.
+
+Focus on visual hierarchy, spacing, typography, color, and component composition. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/rust-in-action.md

@@ -0,0 +1,10 @@
+---
+description: Review Rust code using Rust in Action patterns (Tim McNamara). Usage: /rust-in-action [file | path]
+---
+
+Apply the `rust-in-action` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on systems programming idioms: memory layout, unsafe code, FFI, and OS interaction. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/skill-router.md

@@ -0,0 +1,10 @@
+---
+description: Route your task to the most relevant @booklib/skills skill. Usage: /skill-router [file | task description]
+---
+
+Apply the `skill-router` skill to recommend the best @booklib skill for this task.
+
+**Input:** $ARGUMENTS
+If no input was given, use `git diff HEAD` as the scope.
+
+Return a ranked recommendation with rationale and anti-triggers. Then ask if you should apply the recommended skill immediately.

package/commands/spring-boot-in-action.md

@@ -0,0 +1,10 @@
+---
+description: Review Spring Boot code using Spring Boot in Action patterns (Craig Walls). Usage: /spring-boot-in-action [file | path]
+---
+
+Apply the `spring-boot-in-action` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on auto-configuration, dependency injection, REST endpoints, data access, and testing. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/storytelling-with-data.md

@@ -0,0 +1,10 @@
+---
+description: Review data visualizations and charts using Storytelling with Data (Cole Nussbaumer Knaflic). Usage: /storytelling-with-data [file | chart description]
+---
+
+Apply the `storytelling-with-data` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, describe the chart or run `git diff HEAD` to review changed visualization code.
+
+Focus on chart type choice, data-ink ratio, clutter removal, audience, and narrative. Classify each finding as **HIGH** / **MEDIUM** / **LOW**.

package/commands/system-design-interview.md

@@ -0,0 +1,10 @@
+---
+description: Review system design using Alex Xu's framework (scalability, estimation, trade-offs). Usage: /system-design-interview [description | file]
+---
+
+Apply the `system-design-interview` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, describe the system you want reviewed or run `git diff HEAD`.
+
+Cover requirements clarification, capacity estimation, high-level design, component deep-dive, and trade-offs. Classify each finding as **HIGH** / **MEDIUM** / **LOW**.

package/commands/using-asyncio-python.md

@@ -0,0 +1,10 @@
+---
+description: Review Python async/concurrent code using Using Asyncio in Python (Caleb Hattingh). Usage: /using-asyncio-python [file | path]
+---
+
+Apply the `using-asyncio-python` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on event loop usage, coroutine patterns, task management, cancellation, and common asyncio pitfalls. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/web-scraping-python.md

@@ -0,0 +1,10 @@
+---
+description: Review Python web scraping code using Web Scraping with Python (Ryan Mitchell). Usage: /web-scraping-python [file | path]
+---
+
+Apply the `web-scraping-python` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on selector robustness, rate limiting, error handling, anti-bot evasion, and data storage. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/docs/index.html

@@ -7,7 +7,11 @@
   <meta name="description" content="22 AI agent skills grounded in canonical programming books. Give your AI coding assistant expert knowledge from Clean Code, Effective Java, DDD, and more."/>
   <meta property="og:title" content="booklib-ai/skills"/>
   <meta property="og:description" content="Book-grounded AI agent skills for Claude Code, Cursor, Copilot, and Windsurf."/>
-  <meta property="og:image" content="https://booklib-ai.github.io/skills/logo.png"/>
+  <meta property="og:image" content="https://booklib-ai.github.io/skills/og.png"/>
+  <meta property="og:image:width" content="1200"/>
+  <meta property="og:image:height" content="630"/>
+  <meta name="twitter:card" content="summary_large_image"/>
+  <meta name="twitter:image" content="https://booklib-ai.github.io/skills/og.png"/>
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
 
@@ -108,8 +112,8 @@
     }
     .skills-grid {
       display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
-      gap: 20px;
+      grid-template-columns: repeat(auto-fill, minmax(130px, 1fr));
+      gap: 14px;
     }
 
     /* Card */
@@ -153,6 +157,15 @@
       object-fit: cover;
       display: block;
     }
+    .cover-wrap img.loading {
+      background: linear-gradient(90deg, #161625 25%, #1e1e38 50%, #161625 75%);
+      background-size: 200% 100%;
+      animation: shimmer 1.5s infinite linear;
+    }
+    @keyframes shimmer {
+      0%   { background-position: 200% 0; }
+      100% { background-position: -200% 0; }
+    }
     .cover-fallback {
       width: 100%;
       height: 100%;
@@ -178,35 +191,35 @@
 
     /* Card body */
     .card-body {
-      padding: 14px 16px 16px;
+      padding: 10px 12px 12px;
       flex: 1;
       display: flex;
       flex-direction: column;
-      gap: 4px;
+      gap: 3px;
     }
     .card-body .skill-name {
-      font-size: 0.8rem;
+      font-size: 0.7rem;
       font-weight: 700;
       color: #a5b4fc;
       font-family: "SF Mono", "Fira Code", monospace;
       word-break: break-all;
     }
     .card-body .book-title {
-      font-size: 0.82rem;
+      font-size: 0.75rem;
       font-weight: 600;
       color: #e2e8f0;
       line-height: 1.3;
       margin-top: 2px;
     }
     .card-body .book-author {
-      font-size: 0.75rem;
+      font-size: 0.68rem;
       color: #64748b;
     }
     .card-body .card-desc {
-      font-size: 0.775rem;
+      font-size: 0.68rem;
       color: #475569;
-      line-height: 1.45;
-      margin-top: 6px;
+      line-height: 1.4;
+      margin-top: 4px;
     }
 
     /* Footer */
@@ -283,6 +296,40 @@
     return name.split(/[\s-]+/).map(w => w[0]).join("").toUpperCase().slice(0, 3);
   }
 
+  // Fetch cover URL from Google Books JSON API.
+  // Using the API (not direct hotlinking) avoids false-positive placeholder images
+  // ("No preview available" hatch / "image not available" text) that Google returns
+  // as HTTP 200 responses — the API simply omits imageLinks when no cover exists.
+  function showFb(img) {
+    img.style.display = "none";
+    const fb = img.nextElementSibling;
+    if (fb) fb.style.display = "flex";
+  }
+
+  async function loadCover(img) {
+    const isbn = img.dataset.isbn;
+    try {
+      const url = `https://www.googleapis.com/books/v1/volumes?q=isbn:${isbn}&fields=items(volumeInfo(imageLinks))&maxResults=1`;
+      const d = await fetch(url).then(r => r.json());
+      const links = d.items?.[0]?.volumeInfo?.imageLinks;
+      // thumbnail/smallThumbnail are the only sizes returned by a search query.
+      // Replacing zoom=1 with zoom=0 fetches the largest available version of the same image.
+      const src = (links?.thumbnail || links?.smallThumbnail || "")
+        .replace(/^http:/, "https:")
+        .replace("zoom=1", "zoom=5")
+        .replace("&edge=curl", "");
+      if (src) {
+        img.onload = () => img.classList.remove("loading");
+        img.onerror = () => showFb(img);
+        img.src = src;
+      } else {
+        showFb(img);
+      }
+    } catch {
+      showFb(img);
+    }
+  }
+
   function buildCard(skill) {
     const card = document.createElement("a");
     card.className = "skill-card";
@@ -292,9 +339,9 @@
 
     const coverHtml = skill.isbn
       ? `<img
-           src="https://covers.openlibrary.org/b/isbn/${skill.isbn}-M.jpg"
+           class="loading"
+           data-isbn="${skill.isbn}"
            alt="${skill.book} cover"
-           onerror="this.style.display='none';this.nextElementSibling.style.display='flex'"
          />
          <div class="cover-fallback" style="display:none">
            <div class="initials">${initials(skill.book)}</div>
@@ -356,6 +403,8 @@
   // Build grid
   const grid = document.getElementById("grid");
   SKILLS.forEach(skill => grid.appendChild(buildCard(skill)));
+  // Kick off async cover loading after DOM is populated
+  document.querySelectorAll("img[data-isbn]").forEach(loadCover);
 </script>
 
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
   "bin": {
     "skills": "bin/skills.js"
@@ -20,5 +20,8 @@
   },
   "engines": {
     "node": ">=16"
+  },
+  "devDependencies": {
+    "puppeteer": "^24.39.1"
   }
 }

package/scripts/gen-og.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * gen-og.mjs — generates docs/og.png (1200×630) for GitHub Pages OG preview.
+ * Usage: node scripts/gen-og.mjs
+ * Requires: npm install -g puppeteer  OR  npx puppeteer is available
+ */
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUT = join(__dirname, "../docs/og.png");
+
+const HTML = `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="UTF-8"/>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    width: 1200px; height: 630px; overflow: hidden;
+    background: #0d0d1a;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 80px;
+    position: relative;
+  }
+
+  /* Left: text content */
+  .left { flex: 0 0 auto; max-width: 540px; z-index: 2; }
+
+  .org {
+    font-size: 22px; font-weight: 500; color: #6366f1;
+    letter-spacing: 0.04em; margin-bottom: 16px;
+    font-family: "SF Mono", "Fira Code", monospace;
+  }
+  h1 {
+    font-size: 72px; font-weight: 800; color: #f1f5f9;
+    line-height: 1; letter-spacing: -0.04em; margin-bottom: 20px;
+  }
+  .tagline {
+    font-size: 24px; color: #64748b; line-height: 1.4; margin-bottom: 40px;
+    max-width: 460px;
+  }
+  .pills { display: flex; gap: 12px; flex-wrap: wrap; }
+  .pill {
+    background: #161625; border: 1px solid #2d2d4a;
+    border-radius: 999px; padding: 8px 20px;
+    font-size: 15px; color: #a5b4fc; font-weight: 600;
+  }
+
+  /* Right: book grid */
+  .books {
+    display: grid;
+    grid-template-columns: repeat(5, 1fr);
+    gap: 8px;
+    width: 420px;
+    flex-shrink: 0;
+    opacity: 0.92;
+  }
+  .book {
+    aspect-ratio: 2/3;
+    border-radius: 5px;
+    background: var(--c);
+    position: relative;
+    overflow: hidden;
+  }
+  .book::after {
+    content: "";
+    position: absolute; inset: 0;
+    background: linear-gradient(135deg, rgba(255,255,255,0.08) 0%, transparent 60%);
+  }
+  /* Spine line */
+  .book::before {
+    content: "";
+    position: absolute; top: 0; bottom: 0; left: 8px;
+    width: 2px; background: rgba(0,0,0,0.2);
+  }
+
+  /* Fade edge on left side of book grid */
+  .books-wrap {
+    position: relative;
+    flex-shrink: 0;
+  }
+  .books-wrap::before {
+    content: "";
+    position: absolute; top: 0; bottom: 0; left: -60px;
+    width: 80px;
+    background: linear-gradient(to right, #0d0d1a, transparent);
+    z-index: 1;
+    pointer-events: none;
+  }
+</style>
+</head>
+<body>
+<div class="left">
+  <div class="org">booklib-ai / skills</div>
+  <h1>Skills</h1>
+  <p class="tagline">Expert knowledge from 22 canonical programming books — packaged as AI agent skills.</p>
+  <div class="pills">
+    <span class="pill">22 skills</span>
+    <span class="pill">Claude Code</span>
+    <span class="pill">Cursor</span>
+    <span class="pill">Copilot</span>
+  </div>
+</div>
+
+<div class="books-wrap">
+  <div class="books">
+    ${[
+      "#1e3a5f","#5f1e1e","#1e5f2a","#5f4a1e","#2a1e5f",
+      "#1e4d5f","#5f1e4a","#3d5f1e","#5f3d1e","#1e5f5f",
+      "#4a1e5f","#1e5f3d","#5f5f1e","#1e2a5f","#5f1e2a",
+      "#2a5f1e","#5f2a1e","#1e5f4a","#4a5f1e","#1e4a5f",
+      "#5f1e5f","#3d1e5f","#1e5f1e","#5f3d3d","#1e3d5f",
+      "#5f4d1e","#1e4d3d","#4d1e1e","#1e1e4d","#3d5f3d",
+    ].map(c => `<div class="book" style="--c:${c}"></div>`).join("")}
+  </div>
+</div>
+</body>
+</html>`;
+
+let puppeteer;
+try {
+  puppeteer = await import("puppeteer");
+} catch {
+  // Try puppeteer-core as fallback
+  puppeteer = await import("puppeteer-core");
+}
+
+const browser = await puppeteer.default.launch({ headless: true });
+const page = await browser.newPage();
+await page.setViewport({ width: 1200, height: 630, deviceScaleFactor: 2 });
+await page.setContent(HTML, { waitUntil: "networkidle0" });
+const buf = await page.screenshot({ type: "png" });
+await browser.close();
+
+mkdirSync(dirname(OUT), { recursive: true });
+writeFileSync(OUT, buf);
+console.log(`Written: ${OUT} (${(buf.length / 1024).toFixed(0)} KB)`);

package/skills/skill-router/SKILL.md

@@ -24,6 +24,14 @@ You are a skill selector for the `@booklib/skills` library — a collection of 1
 
 ## Routing Process
 
+### Step 0 — Establish Input Scope
+
+Before routing, pin what you're actually reviewing:
+
+1. **Prefer `git diff` as default scope.** If the user asks to review code without specifying files, default to the current diff — not the entire codebase. Routing a skill against 10,000 lines of unchanged code wastes context and dilutes findings.
+2. **Check for a CLAUDE.md.** If one exists, read it before routing. Project conventions (language standards, test requirements, banned patterns) affect which skill is most relevant and what the selected skill should prioritize.
+3. **Identify the specific files or scope** from the user's message. If genuinely ambiguous, ask before routing.
+
 ### Step 1 — Classify the Work Type
 
 Identify what the user is trying to do:
@@ -92,12 +100,18 @@ Some skill pairs can conflict. Resolve using these rules:
 Format your output as:
 
 ```
+**Scope:** [files or git diff being reviewed]
 **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]
 ```
 
+When instructing the selected skill(s), tell them to:
+- Classify each finding as **HIGH** (correctness/security/data loss), **MEDIUM** (design/maintainability), or **LOW** (style/naming)
+- Reference findings as `file.ext:line` — not just "line 42" or "the function"
+- Skip findings below the threshold for the work type: **review** → HIGH + MEDIUM; **migrate/design** → all tiers
+
 If you're genuinely uncertain between two equally applicable skills, say so and recommend applying both in sequence, primary first.
 
 ---
@@ -118,28 +132,37 @@ Do NOT route to a skill if:
 ```
 User: "Review my Python class for code quality"
 
+Scope: orders/service.py (specified file)
 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.
+
+→ Instruct clean-code-reviewer to classify findings as HIGH/MEDIUM/LOW and reference each as orders/service.py:line.
 ```
 
 **Example 2 — Conflict case:**
 ```
 User: "I'm building a new microservice for our e-commerce platform. Review the domain model."
 
+Scope: git diff (new files in src/domain/)
 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.
+
+→ Instruct both skills to classify findings as HIGH/MEDIUM/LOW and reference each as file:line.
 ```
 
 **Example 3 — Already routed (positive case):**
 ```
 User: "Use the effective-java skill to review my builder pattern"
 
+Scope: user specified — confirm with them if files aren't clear
 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.
+
+→ Instruct effective-java to classify findings as HIGH/MEDIUM/LOW and reference each as file:line.
 ```