@booklib/skills 1.5.2 → 1.7.0

package/commands/effective-python.md

@@ -0,0 +1,10 @@
+---
+description: Review Python code against Effective Python practices (Brett Slatkin). Usage: /effective-python [file | path]
+---
+
+Apply the `effective-python` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on Pythonic idioms, list/dict usage, comprehensions, classes, and robustness. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/effective-typescript.md

@@ -0,0 +1,10 @@
+---
+description: Review TypeScript code against Effective TypeScript (Dan Vanderkam). Usage: /effective-typescript [file | path]
+---
+
+Apply the `effective-typescript` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on type design, avoiding `any`, structural typing, and type inference. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/kotlin-in-action.md

@@ -0,0 +1,10 @@
+---
+description: Review Kotlin code using Kotlin in Action patterns (Elizarov, Isakova). Usage: /kotlin-in-action [file | path]
+---
+
+Apply the `kotlin-in-action` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, run `git diff HEAD` and review those changes.
+
+Focus on language features: coroutines, extension functions, sealed classes, delegation, and DSL patterns. Classify each finding as **HIGH** / **MEDIUM** / **LOW** and reference as `file:line`.

package/commands/lean-startup.md

@@ -0,0 +1,10 @@
+---
+description: Evaluate product/feature decisions using The Lean Startup framework (Eric Ries). Usage: /lean-startup [feature description | file]
+---
+
+Apply the `lean-startup` skill.
+
+**Target:** $ARGUMENTS
+If no target was given, describe the feature or product decision you want evaluated.
+
+Focus on validated learning, Build-Measure-Learn cycle, MVP scope, pivot signals, and vanity vs. actionable metrics.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.5.2",
+  "version": "1.7.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.
 ```

package/demo.tape

@@ -1,40 +0,0 @@
-Output demo.gif
-
-Set Shell "bash"
-Set FontSize 15
-Set Width 1100
-Set Height 650
-Set Theme "Dracula"
-Set Padding 24
-Set Framerate 30
-Set PlaybackSpeed 1
-Env PATH "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
-
-Hide
-Type "cd /Users/fvst/other/fp/skills && clear"
-Enter
-Sleep 500ms
-Show
-
-Sleep 500ms
-
-Type "node bin/skills.js list"
-Sleep 300ms
-Enter
-Sleep 5s
-
-Sleep 1500ms
-
-Type "node bin/skills.js info clean-code-reviewer"
-Sleep 300ms
-Enter
-Sleep 3s
-
-Sleep 1500ms
-
-Type "node bin/skills.js demo clean-code-reviewer"
-Sleep 300ms
-Enter
-Sleep 5s
-
-Sleep 3s