@booklib/skills 1.8.0 → 1.10.0

package/AGENTS.md

@@ -1,108 +1,166 @@
 # Agent Integration
 
-How to install and use booklib-ai/skills with different AI coding assistants.
+How to install and use `@booklib/skills` with different AI coding assistants.
 
-## Claude Code
+## What gets installed
+
+Each install creates up to three things in your project (or globally with `--global`):
+
+| Directory | Contents | Purpose |
+|-----------|----------|---------|
+| `.claude/skills/` | 22 book-grounded skills | Auto-triggered by context |
+| `.claude/commands/` | 22 slash commands | Explicit invocation (`/effective-python`) |
+| `.claude/agents/` | 8 reviewer agents | Autonomous end-to-end reviews |
 
-Install all skills globally:
+The fastest way to install is by **profile** — one command installs the right skills, commands, and agent for your language or domain:
 
 ```bash
-npx skills add booklib-ai/skills --all -g
+npx @booklib/skills add --profile=python        # Python
+npx @booklib/skills add --profile=ts            # TypeScript / JavaScript
+npx @booklib/skills add --profile=jvm           # Java + Kotlin + Spring Boot
+npx @booklib/skills add --profile=rust          # Rust
+npx @booklib/skills add --profile=architecture  # DDD, microservices, system design
+npx @booklib/skills add --profile=data          # Pipelines, ETL, storage
+npx @booklib/skills add --profile=ui            # UI design, charts, animations
+npx @booklib/skills add --profile=lean          # Lean Startup practices
+npx @booklib/skills add --profile=core          # Routing + general quality (good default)
+
+# Or install everything
+npx @booklib/skills add --all
 ```
 
-Install a single skill:
+Add `--global` to any command to install to `~/.claude/` instead of the project directory.
+
+---
+
+## Claude Code
+
+### Install
 
 ```bash
-npx skills add booklib-ai/skills --skill clean-code-reviewer
+# Recommended — install by profile
+npx @booklib/skills add --profile=ts --global
+
+# Everything
+npx @booklib/skills add --all --global
+
+# Single skill
+npx @booklib/skills add effective-typescript
 ```
 
-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`.
+### How skills trigger
+
+Claude Code reads skills from `.claude/skills/` (project) or `~/.claude/skills/` (global) and loads them based on the `description` field in each `SKILL.md`. Skills activate automatically when the context matches.
+
+### Slash commands
 
-To invoke a skill explicitly, use a slash command:
+Each profile also installs companion slash commands:
 
 ```
-/clean-code-reviewer
+/effective-typescript     # runs the effective-typescript skill explicitly
+/clean-code-reviewer      # reviews against Clean Code principles
+/skill-router             # routes automatically to the best skill
 ```
 
-## Cursor
+### Agents
 
-Install skills into your project:
+Agents are autonomous reviewers installed to `.claude/agents/`. Invoke with `@`:
 
-```bash
-npx skills add booklib-ai/skills --all
+```
+@booklib-reviewer         # auto-routes to the right skill
+@python-reviewer          # Python: effective-python + asyncio + scraping
+@ts-reviewer              # TypeScript: effective-typescript + clean-code
+@jvm-reviewer             # Java/Kotlin: effective-java + kotlin + spring-boot
+@rust-reviewer            # Rust: programming-with-rust + rust-in-action
+@architecture-reviewer    # DDD + microservices + system-design + DDIA
+@data-reviewer            # data-intensive-patterns + data-pipelines
+@ui-reviewer              # refactoring-ui + storytelling + animation
 ```
 
-Skills are placed in `.claude/skills/` in your project root. Cursor reads these when Agent mode is active.
+### Skill suggestion hook
 
-To trigger a skill, reference it by name in your prompt:
+`add --all` also installs a `UserPromptSubmit` hook (`booklib-suggest.js`) that detects when you're asking to review code and suggests the relevant skill — without firing on every message.
 
-```
-Apply the effective-python skill to refactor this module.
+To activate it, add the hook config to your Claude Code settings:
+```json
+{
+  "UserPromptSubmit": [{
+    "hooks": [{ "type": "command", "command": "node \"$HOME/.claude/booklib-suggest.js\"" }]
+  }]
+}
 ```
 
-## GitHub Copilot (VS Code)
+---
+
+## Cursor
 
-Install skills globally:
+Cursor reads rules from `.cursor/rules/`. Use `--target=cursor` to install there:
 
 ```bash
-npx skills add booklib-ai/skills --all -g
-```
+# Install to Cursor only
+npx @booklib/skills add --profile=ts --target=cursor
 
-In VS Code with Copilot Chat, skills in `~/.claude/skills/` are available as context. Reference them explicitly in chat:
+# Install to both Claude Code and Cursor
+npx @booklib/skills add --profile=ts --target=all
 
-```
-Using the design-patterns skill, review this class for pattern opportunities.
+# Single skill to Cursor
+npx @booklib/skills add effective-typescript --target=cursor
 ```
 
-## Windsurf
+Skills are written as `.cursor/rules/<skill-name>.md`. Cursor loads them in Agent mode. Agents are not applicable to Cursor (no native agent system).
 
-Install skills into your project:
+---
 
-```bash
-npx skills add booklib-ai/skills --all
+## GitHub Copilot (VS Code)
+
+Copilot Chat doesn't load `.claude/skills/` natively. Reference skills explicitly in chat:
+
+```
+Using the effective-typescript skill, review this file for type safety issues.
+Apply the clean-code-reviewer skill to the current diff.
 ```
 
-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.
+Or install globally and reference by name — some Copilot extensions pick up `.claude/skills/` as context.
 
-## skill-router — automatic routing
+---
 
-Instead of choosing a skill manually, install the `skill-router` meta-skill and let it pick:
+## Windsurf
+
+Install into your project:
 
 ```bash
-npx skills add booklib-ai/skills --skill skill-router -g
+npx @booklib/skills add --profile=ts
 ```
 
-Then prefix any task with:
+Skills go to `.claude/skills/`. In Windsurf's Cascade mode, reference a skill by name or use `@booklib-reviewer` if agents are supported. The `skill-router` skill selects the right skill automatically when you describe your task.
 
-```
-Route this task to the right skill, then apply it: [your request]
-```
+---
 
-The router returns a ranked recommendation (primary + optional secondary) and applies it.
+## Supported platforms
 
-## Manual installation
+| Platform | Skills | Commands | Agents | Auto-trigger |
+|----------|--------|----------|--------|--------------|
+| Claude Code | `.claude/skills/` | `.claude/commands/` | `.claude/agents/` | Yes |
+| Cursor | `.cursor/rules/` (`--target=cursor`) | — | — | Partial |
+| GitHub Copilot | Manual reference | — | — | No |
+| Windsurf | `.claude/skills/` | — | Partial | Partial |
 
-If your agent isn't listed above, copy skills directly:
+---
+
+## Manual installation
 
 ```bash
-# Single skill
-cp -r skills/effective-kotlin /path/to/project/.claude/skills/
+# Single skill to any path
+cp -r skills/effective-kotlin /path/to/.claude/skills/
 
 # All skills
-cp -r skills/* /path/to/project/.claude/skills/
+cp -r skills/* /path/to/.claude/skills/
 ```
 
-Any agent that reads `.claude/skills/` will pick them up.
-
-## Supported agents
+Any agent that reads `.claude/skills/` picks them up automatically.
 
-| 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
+## Requesting support for a new platform
 
-Open an issue titled **"Agent Support: [Agent Name]"** and describe how the agent loads context files. We'll add installation instructions here.
+Open an issue titled **"Platform Support: [Name]"** and describe how the platform loads context files. We'll add installation instructions here.

package/CONTRIBUTING.md

@@ -135,6 +135,153 @@ PR checklist:
 - [ ] Pass rate ≥ 80% and delta ≥ 20pp in results.json
 - [ ] README.md skills table updated
 
+## Adding an Agent
+
+An agent is a multi-step autonomous reviewer that orchestrates one or more skills. If you are packaging a single book's principles, write a skill. If you need to combine multiple skills, detect code patterns to route between them, or run a full review pipeline across a whole codebase, write an agent.
+
+| Write a skill when... | Write an agent when... |
+|-----------------------|------------------------|
+| You are packaging one book's principles | You need two or more skills applied together |
+| The logic is a single lens on code | You need routing logic (detect language → pick skill) |
+| Instructions fit in one SKILL.md | You need a multi-step process (diff → detect → review → output) |
+
+### 1. Create the file
+
+Agents live in a flat directory at the repo root:
+
+```
+agents/<agent-name>.md
+```
+
+The filename must be lowercase and hyphen-separated. It does not need a matching folder — unlike skills, agents have no `examples/` or `evals/` subdirectories.
+
+### 2. Write the frontmatter
+
+Every agent file starts with YAML frontmatter:
+
+```markdown
+---
+name: agent-name
+description: >
+  When to invoke this agent and what it does. Include language names,
+  domain terms, and trigger conditions. Claude Code uses this field
+  for auto-invocation, so make it specific. Max 1024 characters.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+```
+
+**Required fields:**
+
+- `name` — lowercase, hyphens only, matches filename exactly (without `.md`)
+- `description` — used by Claude Code to decide when to invoke the agent automatically; include what it does, which skills it applies, and when to use it over alternatives
+- `tools` — list of Claude Code tools the agent may call; `["Read", "Grep", "Glob", "Bash"]` covers most reviewers
+- `model` — controls cost and capability (see model selection below)
+
+### 3. Write the body
+
+A good agent body has five parts:
+
+**Opening sentence** — one sentence identifying what the agent is, which books it draws from, and its scope.
+
+**Process** — numbered steps the agent follows every time it runs:
+
+1. **Get the scope** — how to determine what to review (e.g., `git diff HEAD`, specific files passed by the user, or a directory scan)
+2. **Detect signals** — bash commands or grep patterns that route to the right skill(s)
+3. **Apply skill(s)** — one `### Step N` section per skill, each with `HIGH`/`MEDIUM`/`LOW` focus areas
+4. **Output** — the standard output format
+
+**Detection table** — a Markdown table mapping code signals to skills:
+
+```markdown
+| Code contains | Apply |
+|---------------|-------|
+| `async def`, `await`, `asyncio` | `using-asyncio-python` |
+| `BeautifulSoup`, `scrapy` | `web-scraping-python` |
+| General Python | `effective-python` |
+```
+
+**Per-skill focus areas** — for each skill applied, list what to look for under `HIGH`, `MEDIUM`, and `LOW` headings. Pull these from the skills' own SKILL.md files, but trim to what is relevant for this agent's scope.
+
+**Output format** — end the body with the standard output block:
+
+```markdown
+### Step N — Output format
+
+​```
+**Skills applied:** `skill-name(s)`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+​```
+```
+
+### 4. Choose the right model
+
+| Model | When to use |
+|-------|-------------|
+| `haiku` | Fast, cheap; use for simple or narrow tasks with a single skill and little routing logic |
+| `sonnet` | Default for most reviewers; handles multi-skill routing and structured output well |
+| `opus` | Only for architecture or reasoning-heavy agents where depth matters more than cost (e.g., `architecture-reviewer`) |
+
+When in doubt, use `sonnet`.
+
+### 5. Follow naming conventions
+
+| Pattern | Examples | Use for |
+|---------|----------|---------|
+| `<language>-reviewer` | `python-reviewer`, `jvm-reviewer`, `ts-reviewer` | Language-cluster agents combining all relevant skills for a language |
+| `<domain>-reviewer` | `architecture-reviewer`, `data-reviewer`, `ui-reviewer` | Domain-cluster agents cutting across languages |
+| Descriptive name | `booklib-reviewer` | Meta or router agents that don't fit a single language or domain |
+
+### 6. Installation
+
+Agents install to `.claude/agents/` alongside skills:
+
+```bash
+# Install one agent
+npx skills add booklib-ai/skills --agent=python-reviewer
+
+# Install everything (skills + agents)
+npx skills add booklib-ai/skills --all
+```
+
+Once installed, Claude Code reads the agent's `description` field and auto-invokes it when a matching request arrives — no slash command needed.
+
+### 7. No eval system (yet)
+
+There is no `evals/` system for agents. Instead:
+
+- Make the `description` accurate — it controls when the agent auto-invokes
+- Check that every `### Step N` section has a clear, testable action
+- Test manually: install the agent locally and run it against a real codebase
+
+### 8. Submit a PR
+
+```bash
+git checkout -b agent/agent-name
+git add agents/agent-name.md
+git commit -m "feat: add agent-name agent"
+gh pr create --title "feat: add agent-name agent" --body "..."
+```
+
+PR checklist:
+- [ ] Filename matches `name` in frontmatter
+- [ ] `description` is under 1024 characters and describes when to invoke it
+- [ ] `model` is appropriate for the agent's complexity
+- [ ] Process steps are numbered and each has a clear action
+- [ ] Detection table covers the signals the agent handles
+- [ ] Output format section matches the standard `HIGH`/`MEDIUM`/`LOW` format
+
 ## Requesting a skill
 
 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.

package/PLAN.md

@@ -0,0 +1,28 @@
+# Implementation Plan
+
+Current version: **1.10.0**
+
+## Completed in 1.9.0
+
+- `skills agents` list command
+- Cursor support (`--target=cursor` / `--target=all`)
+- Hooks: `hooks/suggest.js` + `hooks/hooks.json`
+- README overhaul (three-tier architecture)
+- AGENTS.md rewrite
+
+## Completed in 1.10.0
+
+- Rules system: `rules/{language}/*.md` always-on standards files
+- `skills add --rules` / `skills add --rules=<language>` installs to `.claude/rules/`
+- `skills rules` list command
+- `skills add --hooks` standalone flag (previously hooks only installed via `--all`)
+- CONTRIBUTING.md: "Adding an Agent" section
+- `--all` now also installs all rules
+
+## Possible next steps
+
+- `skills add --profile=<name> --rules` to install profile + relevant rules together
+- Profile-aware rules: each profile installs matching rules automatically
+- `skills rules --info=<language>` for detailed view
+- Rules for more languages (Go, Swift, C++)
+- Agent evals system