@booklib/skills 1.9.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

@@ -1,100 +1,28 @@
 # Implementation Plan
 
-Current version: **1.8.0**
-Next release: **1.9.0**
+Current version: **1.10.0**
 
-## Remaining features (priority order)
+## 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
 
-### 1. `skills agents` list command
-**File:** `bin/skills.js`
-**What:** New `agents` command that lists all agents from `agents/` with name + description (parsed from frontmatter). Mirrors `skills list`.
-**Usage:**
-```bash
-skills agents
-skills agents --info booklib-reviewer
-```
+## 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
 
-### 2. Cursor support (`--target`)
-**File:** `bin/skills.js`
-**What:** `--target` flag on `add` that writes skills to `.cursor/rules/` (Cursor's rule system). Skills install as rule files; agents not applicable to Cursor (no native agent system).
-**Usage:**
-```bash
-skills add --profile=ts --target cursor      # writes to .cursor/rules/
-skills add --profile=ts --target all         # writes to both .claude/ and .cursor/rules/
-skills add effective-python --target cursor
-```
-**Cursor paths:**
-- Skills → `.cursor/rules/<skill-name>.md` (copy of SKILL.md)
-- Commands → not applicable
-- Agents → not applicable
+## Possible next steps
 
----
-
-### 3. `hooks/` — UserPromptSubmit skill suggestion
-**Files:** `hooks/hooks.json`, `hooks/suggest.js`
-**What:** A single `UserPromptSubmit` hook. Reads the user's prompt, detects language + "review/check/improve/refactor" intent, outputs a one-line skill suggestion. Only fires when both intent AND a language signal are present — not on every message.
-
-**Hook config:**
-```json
-{
-  "UserPromptSubmit": [{
-    "matcher": ".*",
-    "hooks": [{ "type": "command", "command": "node ~/.claude/skills/booklib-suggest.js" }]
-  }]
-}
-```
-
-**suggest.js logic:**
-- Read prompt from stdin (JSON event from Claude Code)
-- Check for review intent: `review|check|improve|refactor|fix|audit`
-- Check for language signals: `.py`, `.ts`, `.tsx`, `.java`, `.kt`, `.rs`, etc.
-- Output one-line suggestion or nothing
-
-**Install path:** `hooks/suggest.js` in repo → installed to `.claude/` root as `booklib-suggest.js` via `skills add --all` or `skills add --hooks`.
-
----
-
-### 4. README overhaul
-**File:** `README.md`
-**What:** Rewrite to document the full three-tier architecture. Current README only describes skills. Needs: profiles section, agents section, commands section, architecture diagram.
-
-**New structure:**
-```
-1. Tagline + install
-2. Three-tier architecture diagram (skills → commands → agents → profiles)
-3. Quick start (pick a profile)
-4. Skills list (existing)
-5. Agents (new section)
-6. Profiles (new section)
-7. Commands (new section — brief, link to commands/)
-8. Quality / evals (existing, improved)
-9. Contributing
-```
-
----
-
-## Parallel implementation tracks
-
-| Track | Files touched | Depends on |
-|-------|--------------|------------|
-| A | `bin/skills.js` | — |
-| B | `hooks/hooks.json`, `hooks/suggest.js` | — |
-| C | `README.md` | — |
-
-Tracks B and C are independent and can be implemented simultaneously.
-Track A (`bin/skills.js`) has no file conflicts with B or C.
-All three can be implemented in parallel.
-
----
-
-## Release checklist
-
-- [ ] Track A: `skills agents` command + Cursor support in bin/skills.js
-- [ ] Track B: hooks/hooks.json + hooks/suggest.js
-- [ ] Track C: README overhaul
-- [ ] Bump version to 1.9.0
-- [ ] Commit + tag v1.9.0 + push
+- `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

package/bin/skills.js

@@ -12,6 +12,7 @@ const command = args[0];
 const skillsRoot    = path.join(__dirname, '..', 'skills');
 const commandsRoot  = path.join(__dirname, '..', 'commands');
 const agentsRoot    = path.join(__dirname, '..', 'agents');
+const rulesRoot     = path.join(__dirname, '..', 'rules');
 
 // ─── Installation profiles ────────────────────────────────────────────────────
 const PROFILES = {
@@ -149,6 +150,9 @@ const commandsTargetDir = isGlobal
 const agentsTargetDir = isGlobal
   ? path.join(os.homedir(), '.claude', 'agents')
   : path.join(process.cwd(), '.claude', 'agents');
+const rulesTargetDir = isGlobal
+  ? path.join(os.homedir(), '.claude', 'rules')
+  : path.join(process.cwd(), '.claude', 'rules');
 
 function copyCommand(skillName) {
   const src = path.join(commandsRoot, `${skillName}.md`);
@@ -221,6 +225,42 @@ function copyHooks() {
   }
 }
 
+function getAvailableRules() {
+  // Returns [{language, name, file}] for each rule file found under rules/
+  if (!fs.existsSync(rulesRoot)) return [];
+  const result = [];
+  for (const lang of fs.readdirSync(rulesRoot).sort()) {
+    const langDir = path.join(rulesRoot, lang);
+    if (!fs.statSync(langDir).isDirectory()) continue;
+    for (const file of fs.readdirSync(langDir).filter(f => f.endsWith('.md')).sort()) {
+      result.push({ language: lang, name: file.replace(/\.md$/, ''), file: path.join(langDir, file) });
+    }
+  }
+  return result;
+}
+
+function copyRules(language) {
+  // Copies all rule files for a given language (or 'common') to rulesTargetDir
+  const langDir = path.join(rulesRoot, language);
+  if (!fs.existsSync(langDir)) {
+    console.error(c.red(`✗ No rules for language "${language}".`) + ' Run ' + c.cyan('skills rules') + ' to see available rules.');
+    process.exit(1);
+  }
+  const destDir = path.join(rulesTargetDir, language);
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const file of fs.readdirSync(langDir).filter(f => f.endsWith('.md'))) {
+    const dest = path.join(destDir, file);
+    fs.copyFileSync(path.join(langDir, file), dest);
+    console.log(c.green('✓') + ` ${c.bold(language + '/' + file.replace(/\.md$/, ''))} rule → ${c.dim(dest)}`);
+  }
+}
+
+function copyAllRules() {
+  const rules = getAvailableRules();
+  const languages = [...new Set(rules.map(r => r.language))];
+  for (const lang of languages) copyRules(lang);
+}
+
 function copySkillToCursor(skillName) {
   const src = path.join(skillsRoot, skillName, 'SKILL.md');
   if (!fs.existsSync(src)) return;
@@ -825,15 +865,18 @@ async function main() {
     }
 
     case 'add': {
-      const addAll     = args.includes('--all');
-      const noCommands = args.includes('--no-commands');
-      const noAgents   = args.includes('--no-agents');
-      const agentArg   = args.find(a => a.startsWith('--agent='))?.split('=')[1];
-      const profileArg = args.find(a => a.startsWith('--profile='))?.split('=')[1];
-      const targetArg  = (args.find(a => a.startsWith('--target='))?.split('=')[1] ?? 'claude').toLowerCase();
-      const toClaude   = targetArg === 'claude' || targetArg === 'all';
-      const toCursor   = targetArg === 'cursor'  || targetArg === 'all';
-      const skillName  = args.find(a => !a.startsWith('--') && a !== 'add');
+      const addAll      = args.includes('--all');
+      const addHooks    = args.includes('--hooks');
+      const noCommands  = args.includes('--no-commands');
+      const noAgents    = args.includes('--no-agents');
+      const agentArg    = args.find(a => a.startsWith('--agent='))?.split('=')[1];
+      const profileArg  = args.find(a => a.startsWith('--profile='))?.split('=')[1];
+      const rulesArg    = args.find(a => a === '--rules' || a.startsWith('--rules='));
+      const rulesLang   = rulesArg?.includes('=') ? rulesArg.split('=')[1] : null;
+      const targetArg   = (args.find(a => a.startsWith('--target='))?.split('=')[1] ?? 'claude').toLowerCase();
+      const toClaude    = targetArg === 'claude' || targetArg === 'all';
+      const toCursor    = targetArg === 'cursor'  || targetArg === 'all';
+      const skillName   = args.find(a => !a.startsWith('--') && a !== 'add');
 
       const installSkills = (list) => {
         if (toClaude) list.forEach(s => copySkill(s, targetDir));
@@ -868,12 +911,25 @@ async function main() {
         console.log(c.dim(`\nInstalled to ${agentsTargetDir}`));
       } else if (addAll) {
         const skills = getAvailableSkills();
+        const agents = getAvailableAgents();
         installSkills(skills);
-        installAgents(getAvailableAgents());
-        if (toClaude) copyHooks();
-        const agentCount = (!noAgents && toClaude) ? getAvailableAgents().length : 0;
+        installAgents(agents);
+        if (toClaude) { copyHooks(); copyAllRules(); }
+        const agentCount = (!noAgents && toClaude) ? agents.length : 0;
         const targets = [toClaude && '.claude', toCursor && '.cursor/rules'].filter(Boolean).join(' + ');
-        console.log(c.dim(`\nInstalled ${skills.length} skills, ${agentCount} agents → ${targets}`));
+        console.log(c.dim(`\nInstalled ${skills.length} skills, ${agentCount} agents, ${getAvailableRules().length} rules → ${targets}`));
+      } else if (addHooks) {
+        if (toClaude) copyHooks();
+        else console.log(c.yellow('  --hooks only applies to Claude targets. Use without --target=cursor.'));
+        break;
+      } else if (rulesArg) {
+        if (!toClaude) {
+          console.log(c.yellow('  --rules only applies to Claude targets (.claude/rules/).'));
+          break;
+        }
+        if (rulesLang) copyRules(rulesLang);
+        else copyAllRules();
+        console.log(c.dim(`\nInstalled rules → ${rulesTargetDir}`));
       } else if (skillName) {
         installSkills([skillName]);
         console.log(c.dim(`\nInstalled to ${targetDir}`));
@@ -1019,6 +1075,37 @@ async function main() {
       break;
     }
 
+    case 'rules': {
+      const available = getAvailableRules();
+      if (!available.length) {
+        console.log(c.yellow('  No rules found.'));
+        break;
+      }
+      // Group by language
+      const byLang = {};
+      for (const r of available) {
+        if (!byLang[r.language]) byLang[r.language] = [];
+        byLang[r.language].push(r);
+      }
+      console.log('');
+      console.log(c.bold('  @booklib/skills — rules') + c.dim(` (${available.length} always-on)`));
+      console.log('  ' + c.line(60));
+      for (const [lang, rules] of Object.entries(byLang)) {
+        console.log(`  ${c.bold(lang)}`);
+        for (const r of rules) {
+          const content = fs.readFileSync(r.file, 'utf8');
+          const descMatch = content.match(/^description:\s*(.+)$/m);
+          const desc = descMatch ? descMatch[1].trim().replace(/^>$/, '') : '';
+          console.log(`    ${c.cyan(r.name.padEnd(28))}${c.dim(firstSentence(desc, 55))}`);
+        }
+        console.log('');
+      }
+      console.log(c.dim(`  skills add --rules               install all rules → .claude/rules/`));
+      console.log(c.dim(`  skills add --rules=<language>    install rules for one language`));
+      console.log('');
+      break;
+    }
+
     case 'profiles': {
       const nameW = Math.max(...Object.keys(PROFILES).map(k => k.length)) + 2;
       console.log('');
@@ -1045,13 +1132,17 @@ ${c.bold('  Usage:')}
     ${c.cyan('skills agents')}                     list all available agents
     ${c.cyan('skills agents')}  ${c.dim('--info=<name>')}       full description of an agent
     ${c.cyan('skills profiles')}                   list available profiles
+    ${c.cyan('skills rules')}                      list always-on rule files
     ${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('--profile=<name>')}     install a profile (skills + commands + agent)
     ${c.cyan('skills add')}   ${c.dim('<name>')}               install a single skill + /command
-    ${c.cyan('skills add --all')}                  install everything (skills + commands + agents)
+    ${c.cyan('skills add --all')}                  install everything (skills + agents + rules + hooks)
     ${c.cyan('skills add')}   ${c.dim('<name> --global')}      install globally (~/.claude/)
     ${c.cyan('skills add')}   ${c.dim('--agent=<name>')}       install a single agent to .claude/agents/
+    ${c.cyan('skills add --rules')}                install always-on rules to .claude/rules/
+    ${c.cyan('skills add')}   ${c.dim('--rules=<language>')}   install rules for one language
+    ${c.cyan('skills add --hooks')}                install the UserPromptSubmit suggestion hook
     ${c.cyan('skills add')}   ${c.dim('--target=cursor')}      install to .cursor/rules/ (Cursor IDE)
     ${c.cyan('skills add')}   ${c.dim('--target=all')}         install to both .claude/ and .cursor/
     ${c.cyan('skills add')}   ${c.dim('--no-commands')}        skip /command installation

package/package.json

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

package/rules/common/clean-code.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Clean Code standards from Robert C. Martin. Apply to all code regardless of language.
+---
+
+# Clean Code Standards
+
+Apply these principles from *Clean Code* (Robert C. Martin) to all code you write or review.
+
+## Names
+
+- Use intention-revealing names — if the name needs a comment to explain it, rename it
+- Avoid abbreviations unless universally understood (`url`, `id`, `ctx` are fine; `mgr`, `proc` are not)
+- Classes and types are nouns; methods and functions are verb phrases
+- Avoid noise words that add no meaning: `Manager`, `Data`, `Info`, `Handler` in type names usually signal a missing concept
+- Boolean variables and functions read as assertions: `isEnabled`, `hasPermission`, `canRetry`
+
+## Functions
+
+- Functions do one thing; if you can extract a meaningful sub-function with a non-trivial name, the function does too much
+- Keep functions short — aim for under 20 lines; over 40 is a smell
+- Max 3 parameters; group related parameters into a value object when you need more
+- Avoid boolean flag parameters — they signal the function does two things; split it
+- No side effects in functions that return values
+
+## Comments
+
+- Comments compensate for failure to express intent in code — prefer renaming over commenting
+- Never commit commented-out code; use version control
+- `// TODO:` is acceptable only when tracked in an issue; delete stale TODOs
+- Document *why*, not *what* — the code shows what; the comment explains a non-obvious reason
+
+## Structure
+
+- Group related code together; put high-level concepts at the top, details below
+- Functions in a file should be ordered so callers appear before callees
+- Avoid deep nesting — if `if`/`else` chains exceed 3 levels, extract or invert conditions
+
+## Error handling
+
+- Prefer exceptions over error codes for exceptional conditions
+- Handle errors at the appropriate abstraction level — don't catch and re-throw unless you add context
+- Never swallow exceptions silently; at minimum log before ignoring

package/rules/java/effective-java.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective Java standards from Joshua Bloch. Apply when writing or reviewing Java code.
+---
+
+# Effective Java Standards
+
+Apply these principles from *Effective Java* (Joshua Bloch, 3rd edition) to all Java code.
+
+## Object creation
+
+- Prefer static factory methods over constructors — they have names, can return subtypes, and can cache instances
+- Use a builder when a constructor or factory would have more than 3 parameters
+- Never create unnecessary objects; reuse `String` literals, prefer `Boolean.valueOf(x)` over `new Boolean(x)`
+
+## Classes and mutability
+
+- Minimize mutability — all fields `private final` by default; add setters only when needed
+- Favor composition over inheritance; explicitly document classes designed for extension or mark them `final`
+- Override `@Override` on every method that overrides or implements; the annotation catches typos at compile time
+
+## Methods
+
+- Validate parameters at entry; throw `IllegalArgumentException`, `NullPointerException`, or `IndexOutOfBoundsException` with a message
+- Return empty collections or `Optional`, never `null`, from methods with a non-primitive return type
+- Use `Optional` for return values that may be absent; don't use it for fields or parameters
+
+## Exceptions
+
+- Use checked exceptions for recoverable conditions; unchecked (`RuntimeException`) for programming errors
+- Prefer standard exceptions: `IllegalArgumentException`, `IllegalStateException`, `UnsupportedOperationException`, `NullPointerException`
+- Don't swallow exceptions — at minimum log with context before ignoring; never `catch (Exception e) {}`
+
+## Generics and collections
+
+- Use generic types and methods; avoid raw types (`List` → `List<E>`)
+- Use bounded wildcards (`? extends T` for producers, `? super T` for consumers — PECS)
+- Prefer `List` over arrays for type safety; use arrays only for performance-sensitive low-level code
+
+## Concurrency
+
+- Synchronize all accesses to shared mutable state; prefer `java.util.concurrent` utilities over `synchronized`
+- Prefer immutable objects and thread confinement over shared mutable state

package/rules/kotlin/effective-kotlin.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Effective Kotlin standards from Marcin Moskała. Apply when writing or reviewing Kotlin code.
+---
+
+# Effective Kotlin Standards
+
+Apply these principles from *Effective Kotlin* (Marcin Moskała, 2nd edition) to all Kotlin code.
+
+## Safety
+
+- Prefer `val` over `var`; use `var` only when mutation is genuinely required
+- Use nullable types explicitly (`T?`); avoid `!!` — narrow with `?.`, `?:`, `let`, or `checkNotNull()`
+- Use `require()` for argument preconditions and `check()` for state preconditions at function entry
+
+## Functions
+
+- Use named arguments when passing more than 2 parameters, especially when they share the same type
+- Use default arguments instead of overloads for optional behavior
+- Prefer extension functions over utility classes for domain operations on a type you own
+
+## Classes and design
+
+- Use data classes for value objects — they get `equals`, `hashCode`, `copy`, and `toString` for free
+- Prefer sealed classes over open hierarchies when the set of subtypes is finite and known
+- Use `object` for singletons, `companion object` for factory methods and class-level constants
+
+## Collections
+
+- Use functional operators (`map`, `filter`, `fold`, `groupBy`) over manual loops
+- Prefer `Sequence` for large collections or multi-step pipelines — avoids intermediate lists
+- Use `buildList { }` / `buildMap { }` instead of a mutable variable followed by `.toList()`
+
+## Coroutines
+
+- Launch coroutines in a structured `CoroutineScope`; never use `GlobalScope` in production
+- Use `withContext(Dispatchers.IO)` for blocking I/O; never block the main/UI thread
+- Prefer `Flow` over callbacks for asynchronous streams; use `StateFlow` for observable state

package/rules/python/effective-python.md

@@ -0,0 +1,38 @@
+---
+description: Always-on Effective Python standards from Brett Slatkin. Apply when writing or reviewing Python code.
+---
+
+# Effective Python Standards
+
+Apply these principles from *Effective Python* (Brett Slatkin, 3rd edition) to all Python code.
+
+## Pythonic style
+
+- Use `enumerate()` over `range(len(...))` for indexed iteration
+- Use f-strings for interpolation; avoid `%` formatting and `.format()`
+- Prefer unpacking over indexing: `first, *rest = items` instead of `items[0]` and `items[1:]`
+- Use `zip()` to iterate two sequences together; use `zip(strict=True)` when lengths must match
+
+## Data structures
+
+- Use `list` for ordered mutable sequences, `tuple` for immutable positional data, `set` for membership tests
+- Use `collections.defaultdict` or `Counter` instead of manual dict initialization
+- Prefer `dataclasses` over plain dicts or namedtuples for structured data with methods
+
+## Functions
+
+- Use keyword-only arguments (`def f(a, *, b)`) for optional parameters that benefit from names at the call site
+- Never use mutable default arguments — use `None` and assign inside the function body
+- Prefer generator expressions `(x for x in ...)` over list comprehensions when you don't need the full list in memory
+
+## Type annotations
+
+- Annotate all public functions and class attributes
+- Use `X | None` (Python 3.10+) or `Optional[X]` for nullable types; never return `None` silently from a typed function
+- Avoid `Any` except at system boundaries (external APIs, deserialized JSON)
+
+## Error handling
+
+- Catch specific exception types; never use bare `except:`
+- Use `contextlib.suppress(ExceptionType)` for intentionally ignored exceptions — makes the intent explicit
+- Use `__all__` in every module to declare its public API

package/rules/rust/rust.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Rust standards from Programming with Rust and Rust in Action. Apply when writing or reviewing Rust code.
+---
+
+# Rust Standards
+
+Apply these principles from *Programming with Rust* (Donis Marshall) and *Rust in Action* (Tim McNamara) to all Rust code.
+
+## Ownership and borrowing
+
+- Use owned values (`String`, `Vec<T>`) for data you own; borrow (`&str`, `&[T]`) when you only need to read
+- Prefer passing `&T` or `&mut T` over cloning; clone only when ownership transfer is required
+- Use `Rc<T>` for single-threaded shared ownership, `Arc<T>` for multi-threaded; use `RefCell<T>` / `Mutex<T>` for interior mutability
+
+## Error handling
+
+- Return `Result<T, E>` from all fallible functions; propagate with `?`
+- Use `thiserror` to define library errors with `#[derive(Error)]`; use `anyhow` for application-level error context
+- Avoid `.unwrap()` in library code; use `.expect("clear message")` in application code where panicking is intentional
+
+## Types and traits
+
+- Use `struct` for data, `enum` for variants with payloads, `trait` for shared behaviour
+- Implement standard traits where appropriate: `Debug` always, `Display` for user-facing types, `Clone`, `PartialEq`, `Hash` as needed
+- Use `impl Trait` in argument position for static dispatch; `Box<dyn Trait>` only when you need runtime dispatch
+
+## Idiomatic patterns
+
+- Use `Iterator` adapters (`map`, `filter`, `flat_map`, `collect`) over manual loops — the compiler optimizes them equally
+- Use `Option` methods (`map`, `unwrap_or`, `and_then`, `ok_or`) over `match` for simple transformations
+- Use `if let` for single-variant matching; use `match` for exhaustive handling
+
+## Naming and style
+
+- Types: `PascalCase`; functions, variables, modules: `snake_case`; constants and statics: `SCREAMING_SNAKE_CASE`
+- Lifetime names: `'a`, `'b` for simple cases; descriptive names (`'arena`, `'cx`) for complex lifetimes
+- Mark all public items in a library crate with doc comments (`///`)

package/rules/typescript/effective-typescript.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective TypeScript standards from Dan Vanderkam. Apply when writing or reviewing TypeScript or JavaScript code.
+---
+
+# Effective TypeScript Standards
+
+Apply these principles from *Effective TypeScript* (Dan Vanderkam, 2nd edition) to all TypeScript code.
+
+## Types
+
+- Prefer union types over enums for simple sets of values: `type Direction = 'N' | 'S' | 'E' | 'W'`
+- Use `interface` for extensible object shapes that others may augment; use `type` for unions, intersections, and computed types
+- Avoid `any`; use `unknown` when the type is genuinely unknown, then narrow with guards before use
+- Avoid type assertions (`as T`) — prefer type narrowing, overloads, or generics
+
+## Type inference
+
+- Let TypeScript infer return types on internal functions; explicitly annotate public API return types
+- Annotate a variable at declaration if it cannot be initialized immediately
+- Use `as const` to preserve literal types; don't use it just to silence widening errors
+
+## Null safety
+
+- Enable `strict` mode (which includes `strictNullChecks`) — treat every `T | undefined` as requiring explicit handling
+- Use optional chaining `?.` and nullish coalescing `??` over `&&` and `||` chains
+- Never use non-null assertion (`!`) — narrow instead
+
+## Structural typing
+
+- TypeScript checks shapes, not nominal types — understand that duck typing applies
+- Use discriminated unions with a `kind` or `type` literal field for exhaustive `switch` / narrowing
+- Avoid class hierarchies for data shapes — prefer interfaces and composition
+
+## Generics
+
+- Constrain generics to the minimum required: `<T extends string>` not `<T>`
+- Use descriptive generic names for complex types (`<TItem, TKey>`) and single letters for simple transforms (`<T>`, `<K, V>`)
+
+## Functions
+
+- Prefer function overloads over union parameter types to express the relationship between input and output
+- Keep functions pure where possible; extract side effects to the call site