skillrepo 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,216 @@
+# skillrepo
+
+Set up SkillRepo in any IDE -- one command.
+
+```
+npx skillrepo init
+```
+
+Auto-detects your IDEs, validates your access key, and writes the correct MCP
+configuration for each one. Safe to run multiple times.
+
+## Quick Start
+
+1. **Create an access key** at [skillrepo.dev/app/settings](https://skillrepo.dev/app/settings) (Settings > Access Keys).
+2. **Run the CLI** in your project directory:
+   ```
+   npx skillrepo init
+   ```
+3. **Done.** Your IDE can now discover and activate skills from your SkillRepo library.
+
+## Usage
+
+```
+npx skillrepo init [options]
+```
+
+### Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--key <key>` | `-k` | Access key. If omitted, the CLI reads `SKILLREPO_ACCESS_KEY` from the environment, then prompts interactively. |
+| `--url <url>` | `-u` | SkillRepo server URL. Defaults to `https://skillrepo.dev`. Use this for self-hosted instances. |
+| `--yes` | `-y` | Non-interactive mode. Skips confirmation prompts. Useful for CI or scripted setups. |
+
+### Examples
+
+```sh
+# Interactive setup (prompts for key and confirms detected IDEs)
+npx skillrepo init
+
+# Pass the key directly
+npx skillrepo init --key sk_live_abc123
+
+# Self-hosted instance, non-interactive
+npx skillrepo init --url https://skillrepo.internal.company.com --yes
+
+# Key from environment variable
+export SKILLREPO_ACCESS_KEY=sk_live_abc123
+npx skillrepo init --yes
+```
+
+## What It Does
+
+The CLI performs four steps:
+
+1. **Detects installed IDEs** by checking for IDE-specific directories in the
+   current project (`.claude/`, `.cursor/`, `.vscode/`) and global paths
+   (`~/.codeium/windsurf/`). If no IDE is detected, it defaults to Claude Code
+   and Cursor.
+
+2. **Validates the access key** against the SkillRepo API and fetches the
+   current skill mapping data for your library.
+
+3. **Writes MCP configuration files** for each detected IDE, using the correct
+   format and environment variable syntax for that IDE.
+
+4. **Writes skill mapping files** that let agents match user requests to the
+   right skill without a network round-trip. For Claude Code, it also installs a
+   SessionStart hook that auto-refreshes the mapping on each session start.
+
+### Files Created or Modified
+
+| File | IDE | Purpose |
+|------|-----|---------|
+| `.mcp.json` | Claude Code | MCP server connection config |
+| `.claude/skillrepo.md` | Claude Code | Skill-to-tool mapping |
+| `.claude/hooks/hooks.json` | Claude Code | SessionStart hook registration |
+| `.claude/hooks/skillrepo-sync.mjs` | Claude Code | Auto-refresh script for skill mappings |
+| `.cursor/mcp.json` | Cursor | MCP server connection config |
+| `.cursor/rules/skillrepo.mdc` | Cursor | Skill-to-tool mapping |
+| `~/.codeium/windsurf/mcp_config.json` | Windsurf | MCP server connection config (global) |
+| `.vscode/mcp.json` | VS Code + Copilot | MCP server connection config |
+| `.env.local` | All | Stores `SKILLREPO_ACCESS_KEY` (gitignored) |
+
+All writes are merge-safe. The CLI reads existing files, adds or updates only
+the `skillrepo` entry, and leaves all other entries untouched. Running `init`
+again with a new key updates the key in `.env.local` without affecting anything
+else.
+
+## IDE-Specific Details
+
+### Claude Code
+
+- Config file: `.mcp.json` with `mcpServers.skillrepo` entry
+- Uses `${SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
+- Includes `"type": "http"` in the server entry
+- Installs a SessionStart hook that refreshes the skill mapping file
+  (`.claude/skillrepo.md`) automatically on every session start
+- Skill mappings are always current without manual intervention
+
+### Cursor
+
+- Config file: `.cursor/mcp.json` with `mcpServers.skillrepo` entry
+- Uses `${env:SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
+- Skill mapping file (`.cursor/rules/skillrepo.mdc`) is static; re-run
+  `npx skillrepo init` or ask your agent to run `update skills from skillrepo`
+  to refresh it after adding or removing skills
+
+### Windsurf
+
+- Config file: `~/.codeium/windsurf/mcp_config.json` (global, not per-project)
+- Uses `serverUrl` instead of `url` in the server entry
+- Uses `${env:SKILLREPO_ACCESS_KEY}` syntax for environment variable expansion
+
+### VS Code + Copilot
+
+- Config file: `.vscode/mcp.json` with `servers.skillrepo` entry (note:
+  `servers`, not `mcpServers`)
+- VS Code does not support environment variable interpolation in MCP config;
+  instead, the CLI creates an `inputs` entry that prompts for the access key on
+  first use
+- Uses `${input:skillrepo-api-key}` syntax to reference the input prompt
+
+## Team Setup
+
+For teams sharing a repository, an admin runs the setup once and commits the
+generated config files. Each developer then clones and adds their own key.
+
+### Admin (one-time)
+
+```sh
+cd your-team-repo
+npx skillrepo init
+git add .mcp.json .claude/ .cursor/ .vscode/
+git commit -m "chore: add SkillRepo integration"
+git push
+```
+
+The `.env.local` file is not committed -- it contains the access key and should
+remain gitignored.
+
+### Each Developer
+
+```sh
+git pull
+npx skillrepo init
+```
+
+The CLI detects the existing config files, merges in any updates, and writes the
+developer's own access key to `.env.local`. Developers can also skip the CLI
+and set the environment variable manually:
+
+```sh
+echo 'SKILLREPO_ACCESS_KEY=sk_live_their_key' >> .env.local
+```
+
+## Self-Hosted Usage
+
+If you run a self-hosted SkillRepo instance, pass the `--url` flag:
+
+```sh
+npx skillrepo init --url https://skillrepo.internal.company.com
+```
+
+The CLI writes the custom URL into all MCP config files. The access key is
+validated against your self-hosted instance instead of skillrepo.dev.
+
+You can also set the URL via the `SKILLREPO_URL` environment variable to avoid
+passing `--url` every time.
+
+## Troubleshooting
+
+### "Invalid key format. Keys start with sk_live_"
+
+Access keys always begin with `sk_live_`. Verify you copied the full key from
+Settings > Access Keys. If the key was created with a different prefix, it may
+be a test key that is not valid for production use.
+
+### "Cannot reach https://skillrepo.dev"
+
+Check your network connection. If you are behind a corporate proxy or firewall,
+ensure HTTPS traffic to `skillrepo.dev` (or your self-hosted URL) is allowed.
+For self-hosted instances, verify the `--url` flag points to the correct address.
+
+### "Cannot parse .mcp.json -- invalid JSON"
+
+The CLI cannot merge into a malformed JSON file. Open the file, fix the syntax
+error (or delete it to start fresh), then run `npx skillrepo init` again.
+
+### "No IDEs detected"
+
+The CLI looks for IDE-specific directories in the current working directory. If
+you are not in a project root, `cd` into your project first. If no IDE
+directories exist yet, the CLI defaults to configuring Claude Code and Cursor.
+
+### VS Code prompts for the access key every time
+
+This is expected. VS Code does not support environment variable expansion in
+MCP config files, so it uses an input prompt instead. The key is cached for the
+duration of your VS Code session. Enter the same key from your `.env.local`
+file.
+
+### Skill mappings are stale
+
+For Claude Code, the SessionStart hook refreshes mappings automatically. For
+Cursor and VS Code + Copilot, re-run `npx skillrepo init` or ask your agent to
+run `update skills from skillrepo` to regenerate the mapping file.
+
+## Requirements
+
+- Node.js 18 or later
+- Zero runtime dependencies (uses built-in `fetch` and `fs`)
+
+## License
+
+AGPL-3.0

package/bin/skillrepo.mjs

@@ -25,7 +25,7 @@ if (!command || command === "init") {
     npx skillrepo init [options]
 
   Options:
-    --key, -k <key>    Access key (or set SKILLREPO_API_KEY env var)
+    --key, -k <key>    Access key (or set SKILLREPO_ACCESS_KEY env var)
     --url, -u <url>    SkillRepo URL (default: https://skillrepo.dev)
     --yes, -y          Non-interactive mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Set up SkillRepo in any IDE — one command",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -32,7 +32,7 @@ const DEFAULT_URL = "https://skillrepo.dev";
  */
 function parseFlags(argv) {
   const flags = {
-    key: process.env.SKILLREPO_API_KEY || null,
+    key: process.env.SKILLREPO_ACCESS_KEY || null,
     url: process.env.SKILLREPO_URL || DEFAULT_URL,
     yes: false,
   };
@@ -167,8 +167,8 @@ export async function runInit(argv) {
   printBlank();
   console.log("  Next steps:");
   console.log("  • Commit the generated config files to git");
-  console.log("  • Each team member runs: npx skillrepo setup");
-  console.log("  • SKILLREPO_API_KEY is in .env.local (gitignored)");
+  console.log("  • Each team member runs: npx skillrepo init");
+  console.log("  • SKILLREPO_ACCESS_KEY is in .env.local (gitignored)");
 
   if (detectedKeys.includes("vscode")) {
     printBlank();

package/src/lib/mergers/claude-mcp.mjs

@@ -17,7 +17,7 @@ export function mergeClaudeMcpConfig(mcpUrl) {
     type: "http",
     url: mcpUrl,
     headers: {
-      Authorization: "Bearer ${SKILLREPO_API_KEY}",
+      Authorization: "Bearer ${SKILLREPO_ACCESS_KEY}",
     },
   };
 

package/src/lib/mergers/cursor-mcp.mjs

@@ -16,7 +16,7 @@ export function mergeCursorMcpConfig(mcpUrl) {
   const serverEntry = {
     url: mcpUrl,
     headers: {
-      Authorization: "Bearer ${env:SKILLREPO_API_KEY}",
+      Authorization: "Bearer ${env:SKILLREPO_ACCESS_KEY}",
     },
   };
 

package/src/lib/mergers/env-local.mjs

@@ -1,12 +1,12 @@
 /**
- * Merge SKILLREPO_API_KEY into .env.local
+ * Merge SKILLREPO_ACCESS_KEY into .env.local
  * Append-only — never overwrite existing keys unless the value differs.
  */
 
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
 import { envLocal } from "../paths.mjs";
 
-const KEY_NAME = "SKILLREPO_API_KEY";
+const KEY_NAME = "SKILLREPO_ACCESS_KEY";
 
 /**
  * @param {string} apiKey

package/src/lib/mergers/hooks-json.mjs

@@ -1,29 +1,56 @@
 /**
  * Merger for Claude Code .claude/hooks/hooks.json
- * Also writes the skillrepo-sync.mjs hook script.
+ * Writes hook scripts and merges hook entries into hooks.json.
  *
- * Merge strategy: add a SessionStart entry without destroying existing hooks.
- * Idempotent — if the hook is already installed, skip.
+ * Merge strategy: add SessionStart and UserPromptSubmit entries
+ * without destroying existing hooks. Idempotent — skips if already installed.
  */
 
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { claudeHooksJson, claudeSyncHook } from "../paths.mjs";
+import { claudeHooksJson, claudeSyncHook, claudePromptHook } from "../paths.mjs";
 
-const TARGET_COMMAND = "node .claude/hooks/skillrepo-sync.mjs";
+const SYNC_COMMAND = "node .claude/hooks/skillrepo-sync.mjs";
+const PROMPT_COMMAND = "node .claude/hooks/skillrepo-prompt-match.mjs";
 
 /**
- * Merge the SkillRepo SessionStart hook into hooks.json.
+ * Check if a command is already installed in a hook group array.
+ * @param {Array} groups
+ * @param {string} command
+ * @returns {boolean}
+ */
+function hasCommand(groups, command) {
+  if (!Array.isArray(groups)) return false;
+  return groups.some(
+    (group) =>
+      Array.isArray(group.hooks) &&
+      group.hooks.some((h) => h.command === command)
+  );
+}
+
+/**
+ * Merge SkillRepo hooks into hooks.json and write hook scripts.
  * @param {string} hooksJsonContent - The canonical hooks.json content from the API
- * @param {string} syncHookContent - The sync hook script content from the API
+ * @param {string} syncHookContent - The sync hook script content
+ * @param {string} promptHookContent - The prompt-match hook script content
  * @returns {{ results: { path: string; action: string }[] }}
  */
-export function mergeHooksConfig(hooksJsonContent, syncHookContent) {
+export function mergeHooksConfig(hooksJsonContent, syncHookContent, promptHookContent) {
   const results = [];
 
-  // Always write the sync hook script (latest version from server)
-  const hookExisted = readFileSafe(claudeSyncHook()) !== null;
+  // Always write hook scripts (latest version from server)
+  const syncExisted = readFileSafe(claudeSyncHook()) !== null;
   writeFileSafe(claudeSyncHook(), syncHookContent);
-  results.push({ path: ".claude/hooks/skillrepo-sync.mjs", action: hookExisted ? "updated" : "created" });
+  results.push({
+    path: ".claude/hooks/skillrepo-sync.mjs",
+    action: syncExisted ? "updated" : "created",
+  });
+
+  const promptExisted = readFileSafe(claudePromptHook()) !== null;
+  writeFileSafe(claudePromptHook(), promptHookContent);
+  results.push({
+    path: ".claude/hooks/skillrepo-prompt-match.mjs",
+    action: promptExisted ? "updated" : "created",
+  });
 
   // Merge hooks.json
   const filePath = claudeHooksJson();
@@ -39,31 +66,39 @@ export function mergeHooksConfig(hooksJsonContent, syncHookContent) {
   try {
     config = JSON.parse(existing);
   } catch {
-    throw new Error(`Cannot parse .claude/hooks/hooks.json — invalid JSON. Fix or delete it, then run setup again.`);
+    throw new Error(
+      "Cannot parse .claude/hooks/hooks.json — invalid JSON. Fix or delete it, then run setup again."
+    );
   }
 
-  // Navigate to hooks.SessionStart
   if (!config.hooks) config.hooks = {};
+  let changed = false;
+
+  // Merge SessionStart
   if (!Array.isArray(config.hooks.SessionStart)) config.hooks.SessionStart = [];
+  if (!hasCommand(config.hooks.SessionStart, SYNC_COMMAND)) {
+    config.hooks.SessionStart.push({
+      matcher: "startup|resume",
+      hooks: [{ type: "command", command: SYNC_COMMAND }],
+    });
+    changed = true;
+  }
 
-  // Check if already installed
-  const found = config.hooks.SessionStart.some((group) =>
-    Array.isArray(group.hooks) &&
-    group.hooks.some((h) => h.command === TARGET_COMMAND)
-  );
+  // Merge UserPromptSubmit
+  if (!Array.isArray(config.hooks.UserPromptSubmit)) config.hooks.UserPromptSubmit = [];
+  if (!hasCommand(config.hooks.UserPromptSubmit, PROMPT_COMMAND)) {
+    config.hooks.UserPromptSubmit.push({
+      hooks: [{ type: "command", command: PROMPT_COMMAND }],
+    });
+    changed = true;
+  }
 
-  if (found) {
+  if (changed) {
+    writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+    results.push({ path: ".claude/hooks/hooks.json", action: "merged" });
+  } else {
     results.push({ path: ".claude/hooks/hooks.json", action: "skipped" });
-    return { results };
   }
 
-  // Append new entry
-  config.hooks.SessionStart.push({
-    matcher: "startup|resume",
-    hooks: [{ type: "command", command: TARGET_COMMAND }],
-  });
-
-  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
-  results.push({ path: ".claude/hooks/hooks.json", action: "merged" });
   return { results };
 }

package/src/lib/mergers/windsurf-mcp.mjs

@@ -17,7 +17,7 @@ export function mergeWindsurfMcpConfig(mcpUrl) {
   const serverEntry = {
     serverUrl: mcpUrl,
     headers: {
-      Authorization: "Bearer ${env:SKILLREPO_API_KEY}",
+      Authorization: "Bearer ${env:SKILLREPO_ACCESS_KEY}",
     },
   };
 

package/src/lib/paths.mjs

@@ -14,7 +14,9 @@ export const claudeDir = () => join(cwd(), ".claude");
 export const claudeHooksDir = () => join(cwd(), ".claude", "hooks");
 export const claudeHooksJson = () => join(cwd(), ".claude", "hooks", "hooks.json");
 export const claudeSyncHook = () => join(cwd(), ".claude", "hooks", "skillrepo-sync.mjs");
+export const claudePromptHook = () => join(cwd(), ".claude", "hooks", "skillrepo-prompt-match.mjs");
 export const claudeSkillrepoMd = () => join(cwd(), ".claude", "skillrepo.md");
+export const claudeSkillrepoIndex = () => join(cwd(), ".claude", "skillrepo-index.json");
 
 // Cursor
 export const cursorDir = () => join(cwd(), ".cursor");

package/src/lib/write-configs.mjs

@@ -4,7 +4,7 @@
  */
 
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
-import { claudeSkillrepoMd, cursorSkillrepoMdc } from "./paths.mjs";
+import { claudeSkillrepoMd, claudeSkillrepoIndex, cursorSkillrepoMdc } from "./paths.mjs";
 import { mergeClaudeMcpConfig } from "./mergers/claude-mcp.mjs";
 import { mergeCursorMcpConfig } from "./mergers/cursor-mcp.mjs";
 import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
@@ -33,10 +33,16 @@ export function writeAllConfigs({ ides, mcpUrl, apiKey, payload }) {
     writeFileSafe(claudeSkillrepoMd(), payload.claudeCode.skillrepoMd.content);
     results.push({ path: ".claude/skillrepo.md", action: claudeMdExisted ? "updated" : "created" });
 
-    // SessionStart hook
+    // JSON skill index for prompt matching
+    const indexExisted = readFileSafe(claudeSkillrepoIndex()) !== null;
+    writeFileSafe(claudeSkillrepoIndex(), payload.claudeCode.skillIndex.content);
+    results.push({ path: ".claude/skillrepo-index.json", action: indexExisted ? "updated" : "created" });
+
+    // Hooks (SessionStart sync + UserPromptSubmit prompt-match)
     const hookResults = mergeHooksConfig(
       payload.claudeCode.hooksJson.content,
-      payload.claudeCode.syncHook.content
+      payload.claudeCode.syncHook.content,
+      payload.claudeCode.promptHook.content
     );
     results.push(...hookResults.results);
   }

package/src/test/env-local.test.mjs

@@ -25,12 +25,12 @@ describe(".env.local merger", () => {
 
     assert.equal(result.action, "created");
     const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
-    assert.equal(content, "SKILLREPO_API_KEY=sk_live_test123\n");
+    assert.equal(content, "SKILLREPO_ACCESS_KEY=sk_live_test123\n");
   });
 
   it("skips when key already exists with same value", async () => {
     const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
-    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_API_KEY=sk_live_test123\n");
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_ACCESS_KEY=sk_live_test123\n");
 
     const result = mergeEnvLocal("sk_live_test123");
     assert.equal(result.action, "skipped");
@@ -38,13 +38,13 @@ describe(".env.local merger", () => {
 
   it("updates when key exists with different value", async () => {
     const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
-    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_API_KEY=sk_live_old\n");
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_ACCESS_KEY=sk_live_old\n");
 
     const result = mergeEnvLocal("sk_live_new");
     assert.equal(result.action, "updated");
 
     const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
-    assert.ok(content.includes("SKILLREPO_API_KEY=sk_live_new"));
+    assert.ok(content.includes("SKILLREPO_ACCESS_KEY=sk_live_new"));
     assert.ok(!content.includes("sk_live_old"));
   });
 
@@ -57,7 +57,7 @@ describe(".env.local merger", () => {
 
     const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
     assert.ok(content.includes("OTHER_VAR=value"));
-    assert.ok(content.includes("SKILLREPO_API_KEY=sk_live_test123"));
+    assert.ok(content.includes("SKILLREPO_ACCESS_KEY=sk_live_test123"));
   });
 
   it("preserves CRLF line endings", async () => {

package/src/test/mergers/claude-mcp.test.mjs

@@ -30,7 +30,7 @@ describe("Claude Code MCP config merger", () => {
     const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
     assert.equal(content.mcpServers.skillrepo.type, "http");
     assert.equal(content.mcpServers.skillrepo.url, "https://skillrepo.dev/api/mcp");
-    assert.equal(content.mcpServers.skillrepo.headers.Authorization, "Bearer ${SKILLREPO_API_KEY}");
+    assert.equal(content.mcpServers.skillrepo.headers.Authorization, "Bearer ${SKILLREPO_ACCESS_KEY}");
   });
 
   it("merges into existing config without destroying other servers", async () => {

package/src/test/mergers/hooks-json.test.mjs

@@ -0,0 +1,151 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let originalCwd;
+let tempDir;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-hooks-test-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+const SYNC_CONTENT = "// sync hook";
+const PROMPT_CONTENT = "// prompt hook";
+const HOOKS_JSON = JSON.stringify({
+  hooks: {
+    SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
+    UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
+  },
+}, null, 2) + "\n";
+
+describe("Hooks JSON merger", () => {
+  it("creates all files when nothing exists", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+
+    // Check sync hook written
+    const syncResult = results.find((r) => r.path.includes("sync"));
+    assert.equal(syncResult.action, "created");
+    assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "utf-8"), SYNC_CONTENT);
+
+    // Check prompt hook written
+    const promptResult = results.find((r) => r.path.includes("prompt"));
+    assert.equal(promptResult.action, "created");
+    assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "utf-8"), PROMPT_CONTENT);
+
+    // Check hooks.json created
+    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
+    assert.equal(jsonResult.action, "created");
+  });
+
+  it("merges into existing hooks.json without destroying other hooks", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Pre-existing hooks.json with a different hook
+    const existing = {
+      hooks: {
+        PreToolUse: [{ hooks: [{ type: "command", command: "node other-hook.mjs" }] }],
+      },
+    };
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+
+    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+
+    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
+    assert.equal(jsonResult.action, "merged");
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/hooks/hooks.json"), "utf-8"));
+    // Original hook preserved
+    assert.equal(config.hooks.PreToolUse.length, 1);
+    // New hooks added
+    assert.equal(config.hooks.SessionStart.length, 1);
+    assert.equal(config.hooks.UserPromptSubmit.length, 1);
+  });
+
+  it("skips merge when hooks are already installed", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Pre-existing with both hooks already
+    const existing = {
+      hooks: {
+        SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-prompt-match.mjs" }] }],
+      },
+    };
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+
+    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+
+    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
+    assert.equal(jsonResult.action, "skipped");
+  });
+
+  it("adds missing UserPromptSubmit when only SessionStart exists", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Only SessionStart installed (pre-existing v1.1 setup)
+    const existing = {
+      hooks: {
+        SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: "node .claude/hooks/skillrepo-sync.mjs" }] }],
+      },
+    };
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), JSON.stringify(existing, null, 2));
+
+    const { results } = mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT);
+
+    const jsonResult = results.find((r) => r.path.includes("hooks.json"));
+    assert.equal(jsonResult.action, "merged");
+
+    const config = JSON.parse(readFileSync(join(tempDir, ".claude/hooks/hooks.json"), "utf-8"));
+    // SessionStart unchanged
+    assert.equal(config.hooks.SessionStart.length, 1);
+    // UserPromptSubmit added
+    assert.equal(config.hooks.UserPromptSubmit.length, 1);
+    assert.equal(config.hooks.UserPromptSubmit[0].hooks[0].command, "node .claude/hooks/skillrepo-prompt-match.mjs");
+  });
+
+  it("always updates hook scripts even when hooks.json is skipped", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    // Install once
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "// old sync");
+    writeFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "// old prompt");
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), HOOKS_JSON);
+
+    const { results } = mergeHooksConfig(HOOKS_JSON, "// new sync", "// new prompt");
+
+    // Scripts updated
+    const syncResult = results.find((r) => r.path.includes("sync.mjs"));
+    assert.equal(syncResult.action, "updated");
+    assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-sync.mjs"), "utf-8"), "// new sync");
+
+    const promptResult = results.find((r) => r.path.includes("prompt-match"));
+    assert.equal(promptResult.action, "updated");
+    assert.equal(readFileSync(join(tempDir, ".claude/hooks/skillrepo-prompt-match.mjs"), "utf-8"), "// new prompt");
+  });
+
+  it("throws on invalid JSON in hooks.json", async () => {
+    const { mergeHooksConfig } = await import("../../lib/mergers/hooks-json.mjs");
+
+    mkdirSync(join(tempDir, ".claude/hooks"), { recursive: true });
+    writeFileSync(join(tempDir, ".claude/hooks/hooks.json"), "not json{");
+
+    assert.throws(
+      () => mergeHooksConfig(HOOKS_JSON, SYNC_CONTENT, PROMPT_CONTENT),
+      /Cannot parse/
+    );
+  });
+});