@booklib/skills 1.3.2 → 1.5.0

package/AGENTS.md

@@ -0,0 +1,108 @@
+# Agent Integration
+
+How to install and use booklib-ai/skills with different AI coding assistants.
+
+## Claude Code
+
+Install all skills globally:
+
+```bash
+npx skills add booklib-ai/skills --all -g
+```
+
+Install a single skill:
+
+```bash
+npx skills add booklib-ai/skills --skill clean-code-reviewer
+```
+
+Skills are placed in `~/.claude/skills/` and available in every project. Claude Code picks them up automatically based on the `description` field in each `SKILL.md`.
+
+To invoke a skill explicitly, use a slash command:
+
+```
+/clean-code-reviewer
+```
+
+## Cursor
+
+Install skills into your project:
+
+```bash
+npx skills add booklib-ai/skills --all
+```
+
+Skills are placed in `.claude/skills/` in your project root. Cursor reads these when Agent mode is active.
+
+To trigger a skill, reference it by name in your prompt:
+
+```
+Apply the effective-python skill to refactor this module.
+```
+
+## GitHub Copilot (VS Code)
+
+Install skills globally:
+
+```bash
+npx skills add booklib-ai/skills --all -g
+```
+
+In VS Code with Copilot Chat, skills in `~/.claude/skills/` are available as context. Reference them explicitly in chat:
+
+```
+Using the design-patterns skill, review this class for pattern opportunities.
+```
+
+## Windsurf
+
+Install skills into your project:
+
+```bash
+npx skills add booklib-ai/skills --all
+```
+
+Skills are placed in `.claude/skills/`. In Windsurf's Cascade mode, you can reference a skill by name in your instructions or let the `skill-router` meta-skill select the right one automatically.
+
+## skill-router — automatic routing
+
+Instead of choosing a skill manually, install the `skill-router` meta-skill and let it pick:
+
+```bash
+npx skills add booklib-ai/skills --skill skill-router -g
+```
+
+Then prefix any task with:
+
+```
+Route this task to the right skill, then apply it: [your request]
+```
+
+The router returns a ranked recommendation (primary + optional secondary) and applies it.
+
+## Manual installation
+
+If your agent isn't listed above, copy skills directly:
+
+```bash
+# Single skill
+cp -r skills/effective-kotlin /path/to/project/.claude/skills/
+
+# All skills
+cp -r skills/* /path/to/project/.claude/skills/
+```
+
+Any agent that reads `.claude/skills/` will pick them up.
+
+## Supported agents
+
+| Agent | Install path | Auto-trigger | Manual trigger |
+|-------|-------------|--------------|----------------|
+| Claude Code | `~/.claude/skills/` or `.claude/skills/` | Yes | `/skill-name` |
+| Cursor | `.claude/skills/` | Partial | Reference by name |
+| GitHub Copilot | `~/.claude/skills/` | No | Reference by name |
+| Windsurf | `.claude/skills/` | Partial | Reference by name |
+
+## Requesting support for a new agent
+
+Open an issue titled **"Agent Support: [Agent Name]"** and describe how the agent loads context files. We'll add installation instructions here.

package/CLAUDE.md

@@ -0,0 +1,58 @@
+# booklib-ai/skills
+
+22 AI agent skills grounded in canonical programming books. Each skill packages expert practices from a specific book into reusable instructions that Claude and other AI agents can apply to code generation, code review, and design decisions.
+
+## Quick Install
+
+```bash
+npx skills add booklib-ai/skills --all -g
+```
+
+## Available Skills
+
+| Skill | Book |
+|-------|------|
+| `animation-at-work` | Animation at Work — Rachel Nabors |
+| `clean-code-reviewer` | Clean Code — Robert C. Martin |
+| `data-intensive-patterns` | Designing Data-Intensive Applications — Martin Kleppmann |
+| `data-pipelines` | Data Pipelines Pocket Reference — James Densmore |
+| `design-patterns` | Head First Design Patterns |
+| `domain-driven-design` | Domain-Driven Design — Eric Evans |
+| `effective-java` | Effective Java — Joshua Bloch |
+| `effective-kotlin` | Effective Kotlin — Marcin Moskała |
+| `effective-python` | Effective Python — Brett Slatkin |
+| `effective-typescript` | Effective TypeScript — Dan Vanderkam |
+| `kotlin-in-action` | Kotlin in Action |
+| `programming-with-rust` | Programming with Rust — Donis Marshall |
+| `rust-in-action` | Rust in Action — Tim McNamara |
+| `spring-boot-in-action` | Spring Boot in Action — Craig Walls |
+| `lean-startup` | The Lean Startup — Eric Ries |
+| `microservices-patterns` | Microservices Patterns — Chris Richardson |
+| `refactoring-ui` | Refactoring UI — Adam Wathan & Steve Schoger |
+| `skill-router` | Meta-skill — routes to the right skill automatically |
+| `storytelling-with-data` | Storytelling with Data — Cole Nussbaumer Knaflic |
+| `system-design-interview` | System Design Interview — Alex Xu |
+| `using-asyncio-python` | Using Asyncio in Python — Caleb Hattingh |
+| `web-scraping-python` | Web Scraping with Python — Ryan Mitchell |
+
+## Project Structure
+
+```
+skills/
+├── <skill-name>/
+│   ├── SKILL.md          # Required — instructions + YAML frontmatter
+│   ├── examples/         # before.md and after.md
+│   ├── references/       # Deep reference material
+│   ├── scripts/          # Executable Python/Bash scripts
+│   └── evals/            # evals.json test cases
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to add a new skill. Each skill must pass Bronze quality checks at minimum:
+
+```bash
+npx @booklib/skills check <skill-name>
+```
+
+All 22 existing skills are at Platinum (13/13 checks).

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -117,6 +117,19 @@ PR checklist:
 
 Open an issue titled **"Skill Request: [Book Name]"** and describe why the book would make a good skill. Community members can then pick it up.
 
+## AI disclosure
+
+If you used an AI tool to help write or review your contribution, disclose it in your PR description. This is required — not optional.
+
+**Acceptable examples:**
+- "Written primarily with Claude Code; I reviewed and tested each section manually."
+- "I used Copilot for boilerplate; the examples and evals are hand-written."
+- "No AI tools used."
+
+**Not acceptable:** submitting AI-generated content without reviewing it yourself. Skills are grounded in specific books — the AI can hallucinate citations, misattribute principles, or invent heuristic codes. You are responsible for accuracy.
+
+Trivial fixes (typos, formatting) don't need a disclosure.
+
 ## Questions
 
 Use [GitHub Discussions](../../discussions) for questions, ideas, and feedback.

package/README.md

@@ -1,30 +1,41 @@
-# 🧠 Skills
+# Skills
 
-Book knowledge distilled into structured AI skills — each skill packages expert practices from a specific book into a reusable prompt that AI agents can apply to code generation, code review, and design decisions.
+<p align="center">
+  <img src="assets/logo.svg" width="120" alt="booklib-ai skills logo"/>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@booklib/skills.svg)](https://www.npmjs.com/package/@booklib/skills)
+[![npm downloads](https://img.shields.io/npm/dw/@booklib/skills.svg)](https://www.npmjs.com/package/@booklib/skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/booklib-ai/skills?style=flat)](https://github.com/booklib-ai/skills/stargazers)
+[![Website](https://img.shields.io/badge/website-booklib--ai.github.io%2Fskills-6366f1)](https://booklib-ai.github.io/skills/)
+
+Book-grounded AI agent skills — each skill packages expert practices from a canonical programming book into reusable instructions that Claude and other AI agents can apply to code generation, code review, and design decisions.
+
+```bash
+npx skills add booklib-ai/skills
+```
+
+![Demo](demo.gif)
 
 Each skill is a self-contained folder with a `SKILL.md` file containing instructions and metadata that AI agents use to perform specialized tasks.
 
 ## Structure
 
 ```
-skills/
-├── README.md
-├── LICENSE
+booklib-ai/skills (repo root)
 ├── skills/
-│   ├── clean-code-reviewer/          # Code review using Clean Code principles
-│   │   ├── SKILL.md
+│   ├── clean-code-reviewer/
+│   │   ├── SKILL.md          # Required
+│   │   ├── examples/
+│   │   ├── references/
+│   │   ├── scripts/
 │   │   └── evals/
-│   │       └── evals.json
-│   ├── [future-skill]/
-│   │   ├── SKILL.md
-│   │   ├── scripts/                  # Executable code (Python/Bash)
-│   │   ├── references/               # Documentation loaded into context as needed
-│   │   ├── assets/                   # Templates, icons, fonts
-│   │   └── evals/                    # Test cases for the skill
-│   │       ├── evals.json
-│   │       └── files/                # Input files for evals
-│   └── ...
-└── ...
+│   └── [skill-name]/         # One folder per book
+│       └── ...
+├── README.md
+├── LICENSE
+└── package.json
 ```
 
 ## Skill Format
@@ -55,17 +66,27 @@ Instructions for the AI agent...
 
 ## Installation
 
-### via npm (recommended)
+### via skills CLI (recommended)
 
 ```bash
-# Add a single skill to your current project
-npx @booklib/skills add effective-kotlin
+# Install all skills globally
+npx skills add booklib-ai/skills --all -g
+
+# Install a specific skill
+npx skills add booklib-ai/skills --skill effective-kotlin
+
+# List available skills without installing
+npx skills add booklib-ai/skills --list
+```
+
+### via npm
 
-# Add all skills to your current project
-npx @booklib/skills add --all
+```bash
+# Install all skills globally
+npx @booklib/skills add --all --global
 
-# Add globally (available in all projects)
-npx @booklib/skills add --all --globalcl
+# Install a single skill
+npx @booklib/skills add effective-kotlin
 
 # List available skills
 npx @booklib/skills list
@@ -76,9 +97,8 @@ Skills are installed to `.claude/skills/` in your project (or `~/.claude/skills/
 ### Manual
 
 ```bash
-# Clone and copy a skill directly
 git clone https://github.com/booklib-ai/skills.git
-cp -r skills/skills/effective-kotlin /path/to/project/.claude/skills/
+cp -r booklib-ai-skills/skills/effective-kotlin /path/to/project/.claude/skills/
 ```
 
 ## Automatic Skill Routing
@@ -102,24 +122,28 @@ This means skills compose: `skill-router` acts as an orchestrator that picks the
 
 | Skill | Description |
 |-------|-------------|
-| [animation-at-work](./skills/animation-at-work/) | Apply web animation principles from Rachel Nabors' *Animation at Work* — human perception of motion, 12 principles of animation, and performance |
-| [clean-code-reviewer](./skills/clean-code-reviewer/) | Reviews code against Robert C. Martin's *Clean Code* principles with heuristic codes (C1–C5, G1–G36, N1–N7, T1–T9) |
-| [data-intensive-patterns](./skills/data-intensive-patterns/) | Patterns for reliable, scalable, and maintainable systems from Martin Kleppmann's *Designing Data-Intensive Applications* — storage engines, replication, partitioning, and transactions |
-| [data-pipelines](./skills/data-pipelines/) | Data pipeline practices from James Densmore's *Data Pipelines Pocket Reference* — ingestion, streaming, transformation, and orchestration |
-| [design-patterns](./skills/design-patterns/) | Apply and review GoF design patterns from *Head First Design Patterns* — creational, structural, and behavioral patterns |
-| [domain-driven-design](./skills/domain-driven-design/) | Design and review software using patterns from Eric Evans' *Domain-Driven Design* — tactical and strategic patterns, and Ubiquitous Language |
-| [effective-python](./skills/effective-python/) | Python best practices from Brett Slatkin's *Effective Python* (2nd Edition) — Pythonic thinking, functions, classes, concurrency, and testing |
-| [effective-java](./skills/effective-java/) | Java best practices from Joshua Bloch's *Effective Java* (3rd Edition) — object creation, generics, enums, lambdas, and concurrency |
-| [effective-kotlin](./skills/effective-kotlin/) | Best practices from Marcin Moskała's *Effective Kotlin* (2nd Ed) — safety, readability, reusability, and abstraction |
-| [kotlin-in-action](./skills/kotlin-in-action/) | Practices from *Kotlin in Action* (2nd Ed) — functions, classes, lambdas, nullability, and coroutines |
-| [lean-startup](./skills/lean-startup/) | Practices from Eric Ries' *The Lean Startup* — MVP testing, validated learning, Build-Measure-Learn loop, and pivots |
-| [microservices-patterns](./skills/microservices-patterns/) | Expert guidance on microservices patterns from Chris Richardson's *Microservices Patterns* — decomposition, sagas, API gateways, event sourcing, CQRS, and service mesh |
-| [refactoring-ui](./skills/refactoring-ui/) | UI design principles from *Refactoring UI* by Adam Wathan & Steve Schoger — visual hierarchy, layout, typography, and color |
-| [skill-router](./skills/skill-router/) | **Meta-skill.** Automatically selects the 1–2 most relevant skills for a given file, PR, or task — routes by language, domain, and work type with conflict resolution. Use this when the right skill isn't obvious, or let the AI invoke it automatically before applying any skill |
-| [storytelling-with-data](./skills/storytelling-with-data/) | Data visualization and storytelling from Cole Nussbaumer Knaflic's *Storytelling with Data* — effective visuals, decluttering, and narrative structure |
-| [system-design-interview](./skills/system-design-interview/) | System design principles from Alex Xu's *System Design Interview* — scaling, estimation, and real-world system designs |
-| [using-asyncio-python](./skills/using-asyncio-python/) | Asyncio practices from Caleb Hattingh's *Using Asyncio in Python* — coroutines, event loop, tasks, and signal handling |
-| [web-scraping-python](./skills/web-scraping-python/) | Web scraping practices from Ryan Mitchell's *Web Scraping with Python* — BeautifulSoup, Scrapy, and data storage |
+| 🎬 [animation-at-work](./skills/animation-at-work/) | Apply web animation principles from Rachel Nabors' *Animation at Work* — human perception of motion, 12 principles of animation, and performance |
+| 🧹 [clean-code-reviewer](./skills/clean-code-reviewer/) | Reviews code against Robert C. Martin's *Clean Code* principles with heuristic codes (C1–C5, G1–G36, N1–N7, T1–T9) |
+| 🗄️ [data-intensive-patterns](./skills/data-intensive-patterns/) | Patterns for reliable, scalable, and maintainable systems from Martin Kleppmann's *Designing Data-Intensive Applications* — storage engines, replication, partitioning, and transactions |
+| 🔀 [data-pipelines](./skills/data-pipelines/) | Data pipeline practices from James Densmore's *Data Pipelines Pocket Reference* — ingestion, streaming, transformation, and orchestration |
+| 🏗️ [design-patterns](./skills/design-patterns/) | Apply and review GoF design patterns from *Head First Design Patterns* — creational, structural, and behavioral patterns |
+| 🧩 [domain-driven-design](./skills/domain-driven-design/) | Design and review software using patterns from Eric Evans' *Domain-Driven Design* — tactical and strategic patterns, and Ubiquitous Language |
+| ☕ [effective-java](./skills/effective-java/) | Java best practices from Joshua Bloch's *Effective Java* (3rd Edition) — object creation, generics, enums, lambdas, and concurrency |
+| 🛡️ [effective-kotlin](./skills/effective-kotlin/) | Best practices from Marcin Moskała's *Effective Kotlin* (2nd Ed) — safety, readability, reusability, and abstraction |
+| 🐍 [effective-python](./skills/effective-python/) | Python best practices from Brett Slatkin's *Effective Python* (2nd Edition) — Pythonic thinking, functions, classes, concurrency, and testing |
+| 🔷 [effective-typescript](./skills/effective-typescript/) | TypeScript best practices from Dan Vanderkam's *Effective TypeScript* — type system, type design, avoiding any, type declarations, and migration |
+| 🦀 [programming-with-rust](./skills/programming-with-rust/) | Rust practices from Donis Marshall's *Programming with Rust* — ownership, borrowing, lifetimes, error handling, traits, and fearless concurrency |
+| ⚙️ [rust-in-action](./skills/rust-in-action/) | Systems programming from Tim McNamara's *Rust in Action* — smart pointers, endianness, memory, file formats, TCP networking, concurrency, and OS fundamentals |
+| 🌱 [spring-boot-in-action](./skills/spring-boot-in-action/) | Spring Boot best practices from Craig Walls' *Spring Boot in Action* — auto-configuration, starters, externalized config, profiles, testing with MockMvc, Actuator, and deployment |
+| ⚡ [kotlin-in-action](./skills/kotlin-in-action/) | Practices from *Kotlin in Action* (2nd Ed) — functions, classes, lambdas, nullability, and coroutines |
+| 🚀 [lean-startup](./skills/lean-startup/) | Practices from Eric Ries' *The Lean Startup* — MVP testing, validated learning, Build-Measure-Learn loop, and pivots |
+| 🔧 [microservices-patterns](./skills/microservices-patterns/) | Expert guidance on microservices patterns from Chris Richardson's *Microservices Patterns* — decomposition, sagas, API gateways, event sourcing, CQRS, and service mesh |
+| 🎨 [refactoring-ui](./skills/refactoring-ui/) | UI design principles from *Refactoring UI* by Adam Wathan & Steve Schoger — visual hierarchy, layout, typography, and color |
+| 🗺️ [skill-router](./skills/skill-router/) | **Meta-skill.** Automatically selects the 1–2 most relevant skills for a given file, PR, or task — routes by language, domain, and work type with conflict resolution. Use this when the right skill isn't obvious, or let the AI invoke it automatically before applying any skill |
+| 📊 [storytelling-with-data](./skills/storytelling-with-data/) | Data visualization and storytelling from Cole Nussbaumer Knaflic's *Storytelling with Data* — effective visuals, decluttering, and narrative structure |
+| 🏛️ [system-design-interview](./skills/system-design-interview/) | System design principles from Alex Xu's *System Design Interview* — scaling, estimation, and real-world system designs |
+| 🔄 [using-asyncio-python](./skills/using-asyncio-python/) | Asyncio practices from Caleb Hattingh's *Using Asyncio in Python* — coroutines, event loop, tasks, and signal handling |
+| 🕷️ [web-scraping-python](./skills/web-scraping-python/) | Web scraping practices from Ryan Mitchell's *Web Scraping with Python* — BeautifulSoup, Scrapy, and data storage |
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Skills in this repository are markdown instruction files — they contain no executable code that runs on install. However, if you discover a skill that contains malicious instructions or attempts to exfiltrate data, please report it responsibly.
+
+**Do not open a public issue.** Instead, report security concerns via [GitHub's private vulnerability reporting](https://github.com/booklib-ai/skills/security/advisories/new).
+
+We will respond within 48 hours and issue a fix promptly.

package/assets/logo.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
+  <!-- Background -->
+  <rect width="400" height="400" rx="72" fill="#0d1117"/>
+
+  <!-- Left book page -->
+  <path d="M88 120 L88 300 Q88 316 104 316 L192 316 L192 104 Q160 88 112 92 Q88 96 88 120Z" fill="#1f6feb"/>
+
+  <!-- Right book page -->
+  <path d="M208 104 L208 316 L296 316 Q312 316 312 300 L312 120 Q312 96 288 92 Q240 88 208 104Z" fill="#2d84f5"/>
+
+  <!-- Spine -->
+  <rect x="192" y="100" width="16" height="216" fill="#58a6ff"/>
+
+  <!-- Left page lines -->
+  <rect x="112" y="155" width="64" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="112" y="175" width="52" height="8" rx="4" fill="white" opacity="0.40"/>
+  <rect x="112" y="195" width="68" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="112" y="215" width="44" height="8" rx="4" fill="white" opacity="0.35"/>
+  <rect x="112" y="235" width="60" height="8" rx="4" fill="white" opacity="0.50"/>
+  <rect x="112" y="255" width="48" height="8" rx="4" fill="white" opacity="0.35"/>
+
+  <!-- Right page lines -->
+  <rect x="224" y="155" width="64" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="224" y="175" width="52" height="8" rx="4" fill="white" opacity="0.40"/>
+  <rect x="224" y="195" width="68" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="224" y="215" width="44" height="8" rx="4" fill="white" opacity="0.35"/>
+  <rect x="224" y="235" width="60" height="8" rx="4" fill="white" opacity="0.50"/>
+  <rect x="224" y="255" width="48" height="8" rx="4" fill="white" opacity="0.35"/>
+
+  <!-- AI sparkle (4-pointed star) -->
+  <path d="M316 82 L322 66 L328 82 L344 88 L328 94 L322 110 L316 94 L300 88 Z" fill="#f0883e"/>
+
+  <!-- Accent dots -->
+  <circle cx="348" cy="60" r="5" fill="#f0883e" opacity="0.6"/>
+  <circle cx="296" cy="58" r="4" fill="#f0883e" opacity="0.4"/>
+</svg>

package/demo.tape

@@ -0,0 +1,40 @@
+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