@booklib/skills 1.6.0 → 1.7.0

package/agents/rust-reviewer.md

@@ -0,0 +1,115 @@
+---
+name: rust-reviewer
+description: >
+  Expert Rust reviewer applying @booklib/skills book-grounded expertise.
+  Combines programming-with-rust and rust-in-action for ownership, safety,
+  systems programming, and idiomatic patterns. Use for all Rust code reviews.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a Rust code reviewer with expertise from two canonical books: *Programming with Rust* (Marshall) and *Rust in Action* (McNamara).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.rs'` to see changed Rust files. Check for `CLAUDE.md` at project root.
+
+Run available Rust tools (skip silently if not installed):
+```bash
+cargo check 2>&1 | grep -E "^error|^warning" | head -20
+cargo clippy 2>&1 | grep -E "^error|^warning" | head -20
+cargo fmt --check 2>&1 | head -10
+```
+
+### Step 2 — Detect which skill emphasis to apply
+
+Both skills apply to all Rust code, but emphasise differently:
+
+- **programming-with-rust** → ownership model, borrowing, lifetimes, traits, safe concurrency
+- **rust-in-action** → systems programming idioms, `unsafe`, memory layout, OS interaction, FFI
+
+Check for systems-level signals:
+```bash
+git diff HEAD -- '*.rs' | grep -E "unsafe|extern \"C\"|std::mem::|raw pointer|\*mut|\*const|libc::" | head -5
+```
+
+If systems signals present, lean into `rust-in-action` patterns. Otherwise lead with `programming-with-rust`.
+
+### Step 3 — Apply programming-with-rust
+
+Focus areas from *Programming with Rust*:
+
+**HIGH — Ownership and borrowing**
+- `.clone()` used to work around borrow checker instead of restructuring — flag each
+- `Rc<RefCell<T>>` in code that could use ownership or references — smell of design issue
+- `unwrap()` / `expect()` in library code — return `Result` instead
+- Shared mutable state via `Arc<Mutex<T>>` where ownership transfer would suffice
+
+**HIGH — Error handling**
+- `unwrap()` in code paths that can fail at runtime — use `?` operator
+- `Box<dyn Error>` in library return types — define a concrete error enum
+- Missing error context — use `.map_err(|e| MyError::from(e))` or `anyhow::Context`
+- `panic!` for recoverable errors — return `Result`
+
+**MEDIUM — Traits and generics**
+- Concrete types where trait bounds would make the function more reusable
+- Missing `Send + Sync` bounds on types used across threads
+- Lifetime annotations more complex than necessary — simplify or restructure
+- `impl Trait` in return position hiding type info that callers need
+
+**MEDIUM — Idiomatic patterns**
+- `&String` parameter where `&str` would accept both `String` and `&str`
+- `&Vec<T>` parameter where `&[T]` is more general
+- Iterator chains that could replace explicit loops (`map`, `filter`, `fold`)
+- `match` with `_ =>` arm hiding exhaustiveness — be explicit
+
+**LOW — Style**
+- `#[allow(dead_code)]` or `#[allow(unused)]` without comment explaining why
+- Missing `#[must_use]` on functions whose return value should not be ignored
+- Derive order not following Rust convention (`Debug, Clone, PartialEq, Eq, Hash`)
+
+### Step 4 — Apply rust-in-action (for systems code)
+
+Focus areas from *Rust in Action*:
+
+**HIGH — Unsafe code**
+- `unsafe` block without `// SAFETY:` comment explaining invariants upheld
+- Dereferencing raw pointers without null/alignment check
+- FFI functions that assume C types without `#[repr(C)]` on structs
+- Use-after-free risk: raw pointer kept after owning value dropped
+
+**HIGH — Memory and layout**
+- `std::mem::transmute` without proof types are layout-compatible
+- Uninitialized memory via `MaybeUninit` without completing initialization
+- Stack allocation of large types that should be heap-allocated (`Box<[u8; 1_000_000]>`)
+
+**MEDIUM — Systems patterns**
+- Busy-wait loop where `std::thread::yield_now()` or a channel would work
+- `std::process::exit()` called without flushing buffers — use `Drop` impls
+- Signal handling with non-async-signal-safe operations inside handler
+
+**LOW — FFI**
+- Missing `#[no_mangle]` on functions exported to C
+- C string handling without `CString`/`CStr` — risk of missing null terminator
+
+### Step 5 — Output format
+
+```
+**Skills applied:** `programming-with-rust` + `rust-in-action`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/agents/ts-reviewer.md

@@ -0,0 +1,110 @@
+---
+name: ts-reviewer
+description: >
+  Expert TypeScript reviewer applying @booklib/skills book-grounded expertise.
+  Combines effective-typescript for type system issues and clean-code-reviewer
+  for readability and structure. Use for all TypeScript and TSX code reviews.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a TypeScript code reviewer with expertise from two canonical books: *Effective TypeScript* (Vanderkam) and *Clean Code* (Martin).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.ts' '*.tsx'` to see changed TypeScript files. Check for `CLAUDE.md` at project root.
+
+Run available tools (skip silently if not installed):
+```bash
+npx tsc --noEmit 2>&1 | head -20
+npx eslint . --ext .ts,.tsx 2>&1 | head -20
+```
+
+### Step 2 — Triage the code
+
+Check what kind of TypeScript is in scope:
+```bash
+git diff HEAD -- '*.ts' '*.tsx' | grep -E "any|as unknown|@ts-ignore|@ts-expect-error" | head -5
+git diff HEAD -- '*.tsx' | wc -l  # React components present?
+```
+
+Apply both skills to all TypeScript. `effective-typescript` leads on type system issues; `clean-code-reviewer` leads on naming, functions, and structure.
+
+### Step 3 — Apply effective-typescript
+
+Focus areas from *Effective TypeScript*:
+
+**HIGH — Type safety**
+- `any` used without justification — narrow to specific type or use `unknown` (Item 5)
+- `as` type assertion without a guard or comment — unsafe cast (Item 9)
+- `@ts-ignore` suppressing a real error — fix the underlying type (Item 19)
+- `object` or `{}` type where a specific interface would be safer (Item 18)
+- Mutating a parameter typed as `readonly` — violates contract (Item 17)
+
+**HIGH — Type design**
+- `null | undefined` mixed in a union without clear intent — pick one (Item 31)
+- Boolean blindness: `(boolean, boolean)` tuple where a typed object with named fields would be clear (Item 34)
+- Invalid states representable in the type — redesign so invalid states are unrepresentable (Item 28)
+- `string` used for IDs/statuses where a branded type or union of literals would prevent mixing (Item 35)
+
+**MEDIUM — Type inference**
+- Unnecessary explicit type annotation where inference is clear (Item 19)
+- `return` type annotation missing on exported functions — aids documentation and catches errors (Item 19)
+- Type widened to `string[]` where `readonly string[]` would express intent (Item 17)
+- `typeof` guard where `instanceof` or a discriminated union would be more reliable (Item 22)
+
+**MEDIUM — Generics**
+- Generic constraint `<T extends object>` where `<T extends Record<string, unknown>>` is safer
+- Generic type parameter used only once — probably not needed (Item 50)
+- Missing `infer` in conditional types that extract sub-types (Item 50)
+
+**LOW — Structural typing**
+- Surprise excess property checks missed because of intermediate assignment — use direct object literal (Item 11)
+- Iterating `Object.keys()` with `as` cast — use `Object.entries()` with typed tuple (Item 54)
+
+### Step 4 — Apply clean-code-reviewer
+
+Focus areas from *Clean Code* applied to TypeScript:
+
+**HIGH — Naming**
+- Single-letter variable names outside of trivial loop counters or math
+- Boolean variables not phrased as predicates (`isLoading`, `hasError`, `canSubmit`)
+- Functions named with nouns instead of verbs (`dataProcessor` → `processData`)
+- Misleading names that don't match what the function does
+
+**MEDIUM — Functions**
+- Function over 20 lines — extract cohesive sub-functions
+- More than 3 parameters — group related params into an options object
+- Function does more than one thing — name reveals it (e.g., `fetchAndSave`)
+- Deep nesting over 3 levels — invert conditions / extract early returns
+
+**MEDIUM — Structure**
+- Comment explaining *what* the code does instead of *why* — rewrite as self-documenting code
+- Dead code: commented-out blocks, unused imports, unreachable branches
+- Magic numbers/strings — extract to named constants
+
+**LOW — Readability**
+- Negative conditionals (`if (!isNotReady)`) — invert
+- Inconsistent naming convention within a file (camelCase vs snake_case)
+
+### Step 5 — Output format
+
+```
+**Skills applied:** `effective-typescript` + `clean-code-reviewer`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/agents/ui-reviewer.md

@@ -0,0 +1,117 @@
+---
+name: ui-reviewer
+description: >
+  Expert UI and visual design reviewer applying @booklib/skills book-grounded
+  expertise. Combines refactoring-ui, storytelling-with-data, and animation-at-work.
+  Use when reviewing UI components, dashboards, data visualizations, or animations.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a UI design reviewer with expertise from three canonical books: *Refactoring UI* (Wathan & Schoger), *Storytelling with Data* (Knaflic), and *Animation at Work* (Nabors).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.tsx' '*.jsx' '*.css' '*.scss' '*.svg'` to see changed UI files. Read the full component files for changed components — don't review diffs in isolation.
+
+Check for `CLAUDE.md` at project root.
+
+### Step 2 — Detect which skill(s) apply
+
+| Signal | Apply |
+|--------|-------|
+| Components, layout, spacing, typography, color | `refactoring-ui` |
+| Charts, graphs, tables, data dashboards | `storytelling-with-data` |
+| `transition`, `animation`, `@keyframes`, `motion` | `animation-at-work` |
+
+### Step 3 — Apply refactoring-ui
+
+Focus areas from *Refactoring UI*:
+
+**HIGH — Hierarchy and clarity**
+- All text the same size and weight — no visual hierarchy guiding the eye
+- Too many competing accent colors — use one primary, one semantic (error/success), one neutral
+- Backgrounds creating contrast problems — text failing WCAG AA (4.5:1 ratio for body text)
+- Spacing inconsistent — mixing arbitrary pixel values instead of a consistent scale (4/8/12/16/24/32/48...)
+
+**MEDIUM — Typography**
+- Line length over 75 characters for body text — add `max-width` to prose containers
+- Line height too tight for body text (needs 1.5–1.6 for readability)
+- All-caps used for long text — reserved for short labels and badges only
+- Font weight below 400 on body copy — hard to read at small sizes
+
+**MEDIUM — Component design**
+- Borders used to separate sections that spacing alone would separate — reduces visual noise
+- Empty state missing — component shows broken UI with no data instead of a placeholder
+- Loading state missing — component snaps in or shows raw skeleton without intent
+- Button using border-only style for primary action — primary should use filled background
+
+**LOW — Spacing and layout**
+- Icon and label not aligned on the same baseline
+- Inconsistent border-radius across similar components (some pill, some sharp)
+- Hover state color identical to pressed state — can't distinguish interaction phases
+
+### Step 4 — Apply storytelling-with-data (for charts/visualizations)
+
+Focus areas from *Storytelling with Data*:
+
+**HIGH — Chart type**
+- Pie/donut chart with more than 3 segments — use a bar chart (humans can't compare angles)
+- 3D chart used — depth distorts data and adds no information
+- Dual-axis chart without clear explanation — readers misinterpret the relationship
+- Area chart comparing multiple series where lines would be cleaner
+
+**HIGH — Data integrity**
+- Y-axis not starting at zero for a bar chart — exaggerates differences
+- Missing data points interpolated without disclosure
+- Aggregated metric (average) presented without variance or distribution context
+
+**MEDIUM — Clutter**
+- Gridlines darker than necessary — they should fade to background
+- Data labels on every point when a clear trend is the message — remove most, highlight one
+- Legend placed far from the data it labels — embed labels directly on series
+- Chart title restates the axis labels instead of stating the insight
+
+**LOW — Focus**
+- No visual emphasis on the key data point or trend — everything equal weight
+- Color used for decoration not for encoding meaning — pick one signal color
+
+### Step 5 — Apply animation-at-work (for motion)
+
+Focus areas from *Animation at Work*:
+
+**HIGH — Accessibility**
+- Animation missing `prefers-reduced-motion` media query — will trigger for vestibular users
+- `animation-duration` over 500ms for UI feedback (button press, toggle) — feels sluggish
+- Infinite animation with no pause mechanism — distracting and inaccessible
+
+**MEDIUM — Purpose**
+- Animation present but serves no functional purpose (doesn't aid comprehension or wayfinding)
+- Easing is linear — use `ease-out` for elements entering, `ease-in` for elements leaving
+- Multiple simultaneous animations competing for attention — sequence or simplify
+
+**LOW — Performance**
+- Animating `width`, `height`, `top`, `left` — triggers layout; use `transform` and `opacity` instead
+- `transition` on `all` — will animate unintended properties on state change; be explicit
+
+### Step 6 — Output format
+
+```
+**Skills applied:** [skills used]
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+For UI findings without a clear line number, reference the component name and prop/class. Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/bin/skills.js

@@ -11,6 +11,7 @@ const args = process.argv.slice(2);
 const command = args[0];
 const skillsRoot    = path.join(__dirname, '..', 'skills');
 const commandsRoot  = path.join(__dirname, '..', 'commands');
+const agentsRoot    = path.join(__dirname, '..', 'agents');
 
 // ─── ANSI helpers ─────────────────────────────────────────────────────────────
 const c = {
@@ -96,6 +97,9 @@ const targetDir        = isGlobal
 const commandsTargetDir = isGlobal
   ? path.join(os.homedir(), '.claude', 'commands')
   : path.join(process.cwd(), '.claude', 'commands');
+const agentsTargetDir = isGlobal
+  ? path.join(os.homedir(), '.claude', 'agents')
+  : path.join(process.cwd(), '.claude', 'agents');
 
 function copyCommand(skillName) {
   const src = path.join(commandsRoot, `${skillName}.md`);
@@ -106,6 +110,23 @@ function copyCommand(skillName) {
   console.log(c.green('✓') + ` /${skillName} command → ${c.dim(dest)}`);
 }
 
+function getAvailableAgents() {
+  if (!fs.existsSync(agentsRoot)) return [];
+  return fs.readdirSync(agentsRoot)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+function copyAgent(agentName) {
+  const src = path.join(agentsRoot, `${agentName}.md`);
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(agentsTargetDir, { recursive: true });
+  const dest = path.join(agentsTargetDir, `${agentName}.md`);
+  fs.copyFileSync(src, dest);
+  console.log(c.green('✓') + ` @${agentName} agent → ${c.dim(dest)}`);
+}
+
 // ─── CHECK command ────────────────────────────────────────────────────────────
 function checkSkill(skillName) {
   const skillDir = path.join(skillsRoot, skillName);
@@ -701,20 +722,34 @@ async function main() {
     }
 
     case 'add': {
-      const addAll    = args.includes('--all');
+      const addAll     = args.includes('--all');
       const noCommands = args.includes('--no-commands');
-      const skillName = args.find(a => !a.startsWith('--') && a !== 'add');
-      if (addAll) {
+      const noAgents   = args.includes('--no-agents');
+      const agentArg   = args.find(a => a.startsWith('--agent='))?.split('=')[1];
+      const skillName  = args.find(a => !a.startsWith('--') && a !== 'add');
+
+      if (agentArg) {
+        // explicit: skills add --agent=booklib-reviewer
+        const agents = getAvailableAgents();
+        if (!agents.includes(agentArg)) {
+          console.error(c.red(`✗ Agent "${agentArg}" not found.`) + ' Available: ' + c.dim(agents.join(', ')));
+          process.exit(1);
+        }
+        copyAgent(agentArg);
+        console.log(c.dim(`\nInstalled to ${agentsTargetDir}`));
+      } else if (addAll) {
         const skills = getAvailableSkills();
         skills.forEach(s => copySkill(s, targetDir));
         if (!noCommands) skills.forEach(s => copyCommand(s));
-        console.log(c.dim(`\nInstalled ${skills.length} skills to ${targetDir}`));
+        if (!noAgents) getAvailableAgents().forEach(a => copyAgent(a));
+        const agentCount = noAgents ? 0 : getAvailableAgents().length;
+        console.log(c.dim(`\nInstalled ${skills.length} skills, ${agentCount} agents to .claude/`));
       } else if (skillName) {
         copySkill(skillName, targetDir);
         if (!noCommands) copyCommand(skillName);
         console.log(c.dim(`\nInstalled to ${targetDir}`));
       } else {
-        console.error(c.red('Usage: skills add <skill-name> | skills add --all'));
+        console.error(c.red('Usage: skills add <skill-name> | skills add --all | skills add --agent=<name>'));
         process.exit(1);
       }
       break;
@@ -827,9 +862,11 @@ ${c.bold('  Usage:')}
     ${c.cyan('skills info')}  ${c.dim('<name>')}               full description of a skill
     ${c.cyan('skills demo')}  ${c.dim('<name>')}               before/after example
     ${c.cyan('skills add')}   ${c.dim('<name>')}               install skill + /command to .claude/
-    ${c.cyan('skills add --all')}                  install all skills + commands
+    ${c.cyan('skills add --all')}                  install all skills + commands + agents
     ${c.cyan('skills add')}   ${c.dim('<name> --global')}      install globally (~/.claude/)
     ${c.cyan('skills add')}   ${c.dim('<name> --no-commands')} install skill only, skip command
+    ${c.cyan('skills add')}   ${c.dim('--agent=<name>')}       install a single agent to .claude/agents/
+    ${c.cyan('skills add --all --no-agents')}      install skills + commands, skip agents
     ${c.cyan('skills check')} ${c.dim('<name>')}               quality check (Bronze/Silver/Gold/Platinum)
     ${c.cyan('skills check --all')}                quality summary for all skills
     ${c.cyan('skills update-readme')}              refresh README quality table from results.json files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
   "bin": {
     "skills": "bin/skills.js"

package/benchmark/devto-post.md

@@ -1,178 +0,0 @@
-# How I Route AI Agents to the Right Code Review Context
-
-You gave Claude Code a Clean Code checklist. It reviewed your order processing service and told you to rename `proc` to `processOrder` and split a 22-line function into three.
-
-Meanwhile, the actual problem — your aggregate boundary is wrong and you're leaking domain logic into the API layer — went completely unnoticed.
-
-This isn't an AI failure. It's a routing failure. The agent applied the wrong lens.
-
-## The Problem: Context Collapse
-
-If you give an AI agent a broad set of review instructions, two things happen:
-
-**Token waste** — the agent reads through hundreds of lines of principles that don't apply to the file at hand.
-
-**Wrong focus** — a Clean Code reviewer will nitpick naming on a file where the real issue is a broken domain model. A DDD reviewer will talk about bounded contexts on a utility function that just needs cleaner variable names.
-
-This is what one Hacker News commenter called context collapse: "Clean Code was written for Java in 2008. DDIA is about distributed systems at scale. If you apply the Clean Code reviewer to a 50-line Python script, you'll get pedantic nonsense about function length when the actual problem might be that the data model is wrong."
-
-The criticism is valid. The fix isn't to abandon structured review — it's to pick the right structure for the file in front of you.
-
-## The Approach: A Router That Picks the Reviewer
-
-I've been building a collection of "skills" — structured instruction sets distilled from classic software engineering books (Clean Code, DDIA, Effective Java, DDD, etc.). Each one is a focused lens that an AI agent uses during code review or code generation.
-
-The key piece is a `skill-router`: a meta-skill that runs before any review happens. It inspects:
-
-- File type and language — Kotlin? Python? Infrastructure config?
-- Domain signals — is this a service layer? A repository? A controller?
-- Work type — code review, refactoring, greenfield design, or bug fix?
-
-Based on that, it selects the 1–2 most relevant skills and explicitly skips the rest.
-
-## Example in Practice
-
-User: "Review my order processing service"
-
-```
-Router decision:
-  ✅ Primary:   domain-driven-design    — domain model design (Aggregates, Value Objects)
-  ✅ Secondary: microservices-patterns  — service boundaries and inter-service communication
-  ⛔ Skip:      clean-code-reviewer     — premature at design stage; apply later on implementation code
-```
-
-The router doesn't just pick — it explains why it skipped alternatives. That rationale is important: it makes the selection auditable, and you can override it if you disagree.
-
-## Why Not Just Use One Giant Prompt?
-
-You could stuff everything into one system prompt. I tried. Here's what happens:
-
-**Attention dilution** — the model tries to apply everything at once and produces shallow, generic feedback.
-
-**Conflicting advice** — Clean Code says "extract small functions." Some microservices patterns say "prefer cohesive, slightly larger functions over deep call stacks." The model hedges between both.
-
-**Token budget** — if you're working in Claude Code or Cursor, every token of instructions competes with your actual code context.
-
-Routing means the agent reads ~200 focused lines of instructions instead of ~2000 unfocused ones.
-
-## The Alternative Criticism: "LLMs Already Know These Books"
-
-This is the most common pushback I get. And it's partially true — LLMs have read Clean Code. But they apply that knowledge inconsistently and at low confidence.
-
-Giving the model an explicit lens — "review this against Clean Code heuristics C1–C36" — concentrates attention and dramatically reduces hallucinated or off-topic feedback. It's the difference between asking someone "what do you think?" vs. "evaluate this against these specific criteria."
-
-Think of it like unit tests: the runtime can execute your code correctly without them. But tests make correctness explicit, repeatable, and auditable. Skills do the same for AI review.
-
-## How the Routing Actually Works
-
-The router skill is a structured prompt with a decision tree:
-
-1. Parse the request — what file(s), what task
-2. Match against skill metadata — each skill declares its applicable languages, domains, and work types
-3. Rank by relevance — primary (strongest match) and secondary (complementary perspective)
-4. Conflict resolution — if two skills would give contradictory advice, prefer the one matching the higher abstraction level of the task
-5. Return selection with rationale
-
-There's no ML model or embedding search involved. It's structured prompting — the LLM acts as the routing engine using routing rules baked into the router's own instructions. Language signals, domain signals, and conflict resolution are all declared explicitly inside the router skill, not inferred at runtime. The trade-off: it's fast and predictable, but adding a new skill requires updating the router manually.
-
-## Levels of Review (a Pattern Worth Stealing)
-
-One of the most useful ideas that came from community feedback: separate your review into levels of critique:
-
-1. A fast "lint" pass — formatting, obvious bugs, missing tests
-2. A domain pass — does the code correctly model the business logic?
-3. A "counterexample" pass — propose at least one concrete failing scenario and how to reproduce it
-
-The skill library maps roughly to these levels — Clean Code for level 1, DDD for level 2 — but you have to invoke them separately with the right framing. The router picks based on what the code *is*, not which level you're at. Explicit level-based routing isn't built yet. The counterexample pass is harder and something I'm still figuring out.
-
-## Try It Yourself
-
-The skills and the router are open source: [github.com/booklib-ai/skills](https://github.com/booklib-ai/skills)
-
-You can use them with Claude Code, Cursor, or any agent that supports SKILL.md files. The quickest way to try it — install everything and let the router decide:
-
-```bash
-npx @booklib/skills add --all
-```
-
-Or globally, so it's available in every project:
-
-```bash
-npx @booklib/skills add --all --global
-```
-
-Then just ask your agent to review a file — the router picks the right skill automatically. You don't need to know the library upfront.
-
-## Benchmark: Routed Skills vs. Native Review
-
-Theory is nice. Does it actually find more issues?
-
-I took a deliberately terrible 157-line Node.js order processing module — god function, SQL injection on every query, global mutable state, `eval()` for no reason — and ran it through two pipelines in parallel:
-
-- **Native:** Claude's built-in `pr-review-toolkit:code-reviewer`
-- **skill-router:** `skill-router` → `clean-code-reviewer` + `design-patterns`
-
-### What the router chose
-
-```
-Primary:    clean-code-reviewer  — god function, cryptic names, magic numbers
-Secondary:  design-patterns      — duplicated payment blocks → Strategy pattern
-Skipped:    domain-driven-design — implementation level, not model design stage
-```
-
-### Issue detection
-
-|  | Native | skill-router |
-|---|---|---|
-| Critical/High issues | 7 | 8 |
-| Important/Improvement | 10 | 14 |
-| Suggestions | 0 | 5 |
-| **Total unique issues** | **19** | **~28** |
-
-~89% of what Claude's native reviewer found, skill-router also found. But skill-router found ~9 additional issues that the native reviewer missed entirely.
-
-A few that stood out:
-
-> **`formatMoney` has a floating-point rounding bug** — `0.1 + 0.2` arithmetic, not `Math.round`. Native didn't flag it; clean-code-reviewer caught it via the G-series heuristics.
-
-> **The stubs always return `true`** — they're lying to callers. Native missed it; clean-code-reviewer flagged it as a lying comment / false contract.
-
-> **skill-router surfaced 7 pattern opportunities** — places where a known pattern could reduce complexity (Strategy for payments, State for order lifecycle, Singleton for the broken global state). It explains the problem each one solves and suggests a fix sequence, but leaves the decision to you. Native produced no architectural guidance at all.
-
-### Where each approach wins
-
-| Situation | Use |
-|---|---|
-| Pre-merge PR review, security audit | **Native** — pre-merge gate: fast, confidence-filtered, adapts to your CLAUDE.md project conventions |
-| Larger refactor, architecture planning | **skill-router** — patterns, principles, refactor roadmap |
-| Both together | ~95% total issue coverage vs. ~80% for either alone |
-
-**One honest loss for skill-router:** Card data was being logged to stdout — a clear PCI violation. Claude's built-in reviewer flagged it at 92% confidence. skill-router didn't. Security compliance isn't in any book-based skill's scope, and the router has no way to know it should care. If compliance is the priority, the native reviewer is the right tool.
-
-After looking closely at how both tools are built, the difference in purpose becomes clear.
-
-The native reviewer runs **6 parallel sub-agents**, each focused on one category: code quality, silent failures, type design, test coverage, comment accuracy, and security. It defaults to reviewing only the current `git diff` — not the whole file. Before starting, it reads your `CLAUDE.md` to pick up project conventions. And it discards any finding below 80% confidence, so output arrives pre-filtered. That's a purpose-built pre-merge gate: narrow scope, parallel specialists, high signal-to-noise.
-
-skill-router does the opposite: one agent, one deeply focused skill, applied to the whole module. It trades breadth and speed for depth and principle grounding.
-
-They target different moments in the development lifecycle, which is why using both gives ~95% coverage.
-
-One gap this benchmark exposed was the noise filtering: Claude's native reviewer discards anything below 80% confidence; skill-router had no equivalent. Since writing this, the router has been updated to instruct selected skills to classify every finding as HIGH / MEDIUM / LOW and skip LOW-tier findings on standard reviews — same idea, book-grounded framing instead of a confidence score.
-
-The full before/after code and comparison report are in the repo under [`/benchmark/`](https://github.com/booklib-ai/skills/tree/main/benchmark).
-
-## Open Questions
-
-I don't have everything figured out. A few things I'm still exploring:
-
-**Sub-agent architecture** — the native pr-review-toolkit runs 6 parallel sub-agents (tests, types, silent failures, comments, etc.), each a focused specialist. skill-router takes the opposite approach: one agent, one focused skill, narrow scope. Both work, but for different reasons. The open question is whether a *generate-then-evaluate* loop — one agent produces code using a skill's patterns, a second agent checks it against the same skill's rubric — would catch more issues than a single-pass review. My current answer is no for code review, maybe for code generation. If you've tried this pattern, I'd like to know what you found.
-
-**Feedback loops** — the benchmark above is one data point. How do you systematically measure whether routing improves review quality across different codebases and languages?
-
-**Domain-specific routing** — healthcare code, fintech code, and game code each have very different "what matters most" priorities. Should routing consider the project domain, not just the file?
-
-If you've been working on similar problems — structured AI review, skill selection, multi-agent evaluation — I'd love to hear what's working for you.
-
----
-
-*Currently covering: Clean Code, Domain-Driven Design, Effective Java, Effective Kotlin, Microservices Patterns, System Design Interview, Storytelling with Data, and more. Skills are community-contributed and new books are welcome.*