skillrepo 1.7.1 → 1.9.0

package/package.json

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

package/src/commands/init.mjs

@@ -155,6 +155,7 @@ export async function runInit(argv) {
       mcpUrl,
       apiKey,
       serverUrl: flags.url,
+      userId: payload.userId,
     });
   } catch (err) {
     printError(err.message);

package/src/hooks/skillrepo-pretool-activation.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * SkillRepo PreToolUse hook — detects when skills are actually USED during a
+ * coding session by matching tool/command patterns against skill-declared
+ * `contextSignals.toolPatterns`. Telemetry-only: no content injection, no blocking.
+ *
+ * Standalone script: no npm dependencies, Node.js built-ins only.
+ * Installed by `npx skillrepo init` to `.claude/hooks/skillrepo-pretool-activation.mjs`.
+ *
+ * Part of #569 (PreToolUse hook for tool fingerprinting activation telemetry).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_SERVER_URL = "https://skillrepo.dev";
+const MAX_EVENTS_PER_BATCH = 50;
+
+// ---------------------------------------------------------------------------
+// Config resolution (lightweight — only needs API key and server URL)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read config from ~/.claude/skillrepo/config.json with fallbacks.
+ * Returns { apiKey, serverUrl, userId } or null.
+ */
+export function readConfig() {
+  const configPath = join(homedir(), ".claude", "skillrepo", "config.json");
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+    if (cfg.apiKey) {
+      return {
+        apiKey: cfg.apiKey,
+        serverUrl: cfg.serverUrl || DEFAULT_SERVER_URL,
+        userId: cfg.userId || null,
+      };
+    }
+  } catch { /* not found */ }
+
+  const envKey = process.env.SKILLREPO_ACCESS_KEY;
+  if (envKey) {
+    return { apiKey: envKey, serverUrl: process.env.SKILLREPO_SERVER_URL || DEFAULT_SERVER_URL, userId: null };
+  }
+
+  // .env.local fallback
+  for (const file of [".env.local", ".env"]) {
+    try {
+      const lines = readFileSync(join(process.cwd(), file), "utf-8").split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (trimmed.slice(0, eqIdx).trim() === "SKILLREPO_ACCESS_KEY") {
+          let val = trimmed.slice(eqIdx + 1).trim();
+          if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+          }
+          val = val.replace(/\s+#.*$/, "");
+          if (val) return { apiKey: val, serverUrl: DEFAULT_SERVER_URL, userId: null };
+        }
+      }
+    } catch { /* file doesn't exist */ }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Tool pattern matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a tool invocation against all skills' contextSignals.toolPatterns.
+ *
+ * For Bash tools: prefix-match tool_input.command against each pattern.
+ * For non-Bash tools: match tool_name against patterns.
+ *
+ * Pattern matching rules:
+ * - Case-insensitive
+ * - Prefix match: pattern "gh issue" matches command "gh issue create --title ..."
+ * - Pattern must match at a word boundary (don't match "npm" against "npmx")
+ *
+ * Returns array of { skill, pattern } matches.
+ */
+export function matchToolPatterns(toolName, toolInput, skills) {
+  if (!toolName || !skills?.length) return [];
+
+  const isBash = toolName.toLowerCase() === "bash";
+  const matches = [];
+
+  for (const skill of skills) {
+    const patterns = skill.contextSignals?.toolPatterns;
+    if (!patterns?.length) continue;
+
+    for (const pattern of patterns) {
+      if (!pattern) continue;
+      const patternLower = pattern.toLowerCase();
+
+      if (isBash) {
+        // Bash tool: prefix-match against command
+        const command = (toolInput?.command ?? "").trim();
+        if (!command) continue;
+        const commandLower = command.toLowerCase();
+
+        if (commandLower.startsWith(patternLower)) {
+          // Word boundary check: the character after the pattern must be
+          // end-of-string, whitespace, or a non-alphanumeric character
+          const afterIdx = patternLower.length;
+          if (afterIdx >= commandLower.length || /[^a-z0-9_]/i.test(commandLower[afterIdx])) {
+            matches.push({ skill, pattern });
+            break; // one match per skill is enough
+          }
+        }
+      } else {
+        // Non-Bash tool: match tool_name against patterns
+        const toolNameLower = toolName.toLowerCase();
+        if (toolNameLower === patternLower) {
+          matches.push({ skill, pattern });
+          break; // one match per skill is enough
+        }
+      }
+    }
+  }
+
+  return matches;
+}
+
+// ---------------------------------------------------------------------------
+// Session dedup
+// ---------------------------------------------------------------------------
+
+/**
+ * Read activation state for deduplication.
+ * State is stored in tmpdir keyed by session hash.
+ */
+export function readActivationState(sessionId) {
+  const hash = createHash("sha256").update(sessionId || "default").digest("hex").slice(0, 16);
+  const statePath = join(tmpdir(), `skillrepo-activation-${hash}.json`);
+
+  try {
+    return { path: statePath, state: JSON.parse(readFileSync(statePath, "utf-8")) };
+  } catch {
+    return { path: statePath, state: { reported: {} } };
+  }
+}
+
+/**
+ * Filter matches to exclude skills already reported in this session.
+ */
+export function deduplicateActivations(matches, sessionState) {
+  return matches.filter(m => {
+    const key = `${m.skill.owner}/${m.skill.name}`;
+    return !sessionState.reported[key];
+  });
+}
+
+/**
+ * Mark skills as reported in session state.
+ */
+export function updateActivationState(statePath, state, reportedMatches) {
+  for (const m of reportedMatches) {
+    const key = `${m.skill.owner}/${m.skill.name}`;
+    state.reported[key] = new Date().toISOString();
+  }
+  try { writeFileSync(statePath, JSON.stringify(state), "utf-8"); }
+  catch { /* non-critical */ }
+}
+
+// ---------------------------------------------------------------------------
+// Telemetry payload
+// ---------------------------------------------------------------------------
+
+/**
+ * Build telemetry payload for tool-pattern-activated skills.
+ */
+export function buildTelemetryPayload(matches, sessionInfo) {
+  const events = matches.slice(0, MAX_EVENTS_PER_BATCH).map(m => ({
+    skillOwner: m.skill.owner,
+    skillName: m.skill.name,
+    skillVersion: m.skill.version || undefined,
+    activatedAt: new Date().toISOString(),
+    ide: sessionInfo.ide || "claude-code",
+    sessionHash: sessionInfo.sessionHash,
+    userId: sessionInfo.userId || undefined,
+    source: "pretool_hook",
+    toolPattern: m.pattern,
+  }));
+
+  return { events };
+}
+
+/**
+ * Fire-and-forget POST to telemetry endpoint.
+ *
+ * NOT awaited — the spec requires "do NOT block the agent" and Claude Code
+ * waits for hook process exit. The OS TCP stack flushes small payloads after
+ * process exit, so delivery reliability is ~99%+ for responsive servers.
+ * Occasional loss on slow/unreachable servers is acceptable for non-critical
+ * telemetry.
+ */
+export function sendTelemetry(config, payload) {
+  const url = `${config.serverUrl}/api/v1/telemetry/activation`;
+
+  fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  }).catch(() => { /* telemetry errors are non-critical */ });
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function main(input) {
+  const indexPath = join(homedir(), ".claude", "skillrepo", "index.json");
+
+  // -- Read index --
+  let index;
+  try {
+    index = JSON.parse(readFileSync(indexPath, "utf-8"));
+  } catch {
+    // No index -> nothing to match. Exit cleanly.
+    process.stdout.write("{}");
+    return;
+  }
+
+  if (!index.skills?.length) {
+    process.stdout.write("{}");
+    return;
+  }
+
+  // -- Read config (needed for telemetry POST) --
+  const config = readConfig();
+  if (!config) {
+    process.stdout.write("{}");
+    return;
+  }
+
+  // -- Match tool against skills --
+  const toolName = input.tool_name ?? "";
+  const toolInput = input.tool_input ?? {};
+  const matches = matchToolPatterns(toolName, toolInput, index.skills);
+
+  if (matches.length === 0) {
+    process.stdout.write("{}");
+    return;
+  }
+
+  // -- Session dedup --
+  const sessionId = input.session_id ?? "default";
+  const { path: statePath, state } = readActivationState(sessionId);
+  const newMatches = deduplicateActivations(matches, state);
+
+  if (newMatches.length === 0) {
+    process.stdout.write("{}");
+    return;
+  }
+
+  // -- Build and send telemetry --
+  const sessionHash = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+
+  const payload = buildTelemetryPayload(newMatches, {
+    ide: "claude-code",
+    sessionHash,
+    userId: config.userId,
+  });
+
+  sendTelemetry(config, payload); // fire-and-forget -- do NOT await
+
+  // -- Update session state --
+  updateActivationState(statePath, state, newMatches);
+
+  // -- Output: NO additionalContext --
+  process.stdout.write("{}");
+}
+
+// -- Run --
+const __filename = fileURLToPath(import.meta.url);
+const isMainModule = process.argv[1] === __filename;
+
+if (isMainModule) {
+  let inputBuf = "";
+  for await (const chunk of process.stdin) inputBuf += chunk;
+
+  let input;
+  try { input = JSON.parse(inputBuf); }
+  catch { process.stdout.write("{}"); process.exit(0); }
+
+  main(input).catch(() => {
+    process.stdout.write("{}");
+    process.exit(0);
+  });
+}

package/src/hooks/skillrepo-prompt-match.mjs

@@ -14,7 +14,6 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir, tmpdir } from "node:os";
 import { createHash } from "node:crypto";
-import { execSync } from "node:child_process";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -29,20 +28,24 @@ const MAX_EVENTS_PER_BATCH = 50;
 
 /**
  * Read config from ~/.claude/skillrepo/config.json with fallbacks.
- * Returns { apiKey, serverUrl } or null.
+ * Returns { apiKey, serverUrl, userId } or null.
  */
 export function readConfig() {
   const configPath = join(homedir(), ".claude", "skillrepo", "config.json");
   try {
     const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
     if (cfg.apiKey) {
-      return { apiKey: cfg.apiKey, serverUrl: cfg.serverUrl || DEFAULT_SERVER_URL };
+      return {
+        apiKey: cfg.apiKey,
+        serverUrl: cfg.serverUrl || DEFAULT_SERVER_URL,
+        userId: cfg.userId || null,
+      };
     }
   } catch { /* not found */ }
 
   const envKey = process.env.SKILLREPO_ACCESS_KEY;
   if (envKey) {
-    return { apiKey: envKey, serverUrl: process.env.SKILLREPO_SERVER_URL || DEFAULT_SERVER_URL };
+    return { apiKey: envKey, serverUrl: process.env.SKILLREPO_SERVER_URL || DEFAULT_SERVER_URL, userId: null };
   }
 
   // .env.local fallback
@@ -59,7 +62,7 @@ export function readConfig() {
             val = val.slice(1, -1);
           }
           val = val.replace(/\s+#.*$/, "");
-          if (val) return { apiKey: val, serverUrl: DEFAULT_SERVER_URL };
+          if (val) return { apiKey: val, serverUrl: DEFAULT_SERVER_URL, userId: null };
         }
       }
     } catch { /* file doesn't exist */ }
@@ -175,45 +178,6 @@ export function updateSessionState(statePath, state, reportedMatches) {
   catch { /* non-critical */ }
 }
 
-// ---------------------------------------------------------------------------
-// GitHub username resolution
-// ---------------------------------------------------------------------------
-
-const GITHUB_USERNAME_CACHE_PATH = join(tmpdir(), "skillrepo-gh-user.json");
-
-/**
- * Resolve GitHub username via `gh api user`. Cached per session.
- */
-export function resolveGithubUsername() {
-  // Check cache first
-  try {
-    const cached = JSON.parse(readFileSync(GITHUB_USERNAME_CACHE_PATH, "utf-8"));
-    if (cached.username && cached.expiresAt > Date.now()) return cached.username;
-  } catch { /* no cache */ }
-
-  // Resolve via gh CLI
-  try {
-    const result = execSync("gh api user --jq .login", {
-      encoding: "utf-8",
-      timeout: 3_000,
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-
-    if (result) {
-      // Cache for 1 hour
-      try {
-        writeFileSync(GITHUB_USERNAME_CACHE_PATH, JSON.stringify({
-          username: result,
-          expiresAt: Date.now() + 3_600_000,
-        }), "utf-8");
-      } catch { /* non-critical */ }
-      return result;
-    }
-  } catch { /* gh not installed or not authed */ }
-
-  return null;
-}
-
 // ---------------------------------------------------------------------------
 // Telemetry payload
 // ---------------------------------------------------------------------------
@@ -229,7 +193,7 @@ export function buildTelemetryPayload(matches, sessionInfo) {
     matchedAt: new Date().toISOString(),
     ide: sessionInfo.ide || "claude-code",
     sessionHash: sessionInfo.sessionHash,
-    githubUsername: sessionInfo.githubUsername || "",
+    userId: sessionInfo.userId || undefined,
     wasRulesDelivered: m.skill.isRulesDelivered ?? false,
   }));
 
@@ -308,12 +272,11 @@ export async function main(input) {
 
   // ── Build and send telemetry ────────────────────────────────
   const sessionHash = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
-  const githubUsername = resolveGithubUsername();
 
   const payload = buildTelemetryPayload(newMatches, {
     ide: "claude-code",
     sessionHash,
-    githubUsername,
+    userId: config.userId,
   });
 
   sendTelemetry(config, payload); // fire-and-forget — do NOT await

package/src/hooks/skillrepo-sync.mjs

@@ -441,7 +441,10 @@ export function writeRulesFiles(selectedSkills, projectDir) {
     written.add(baseName);
 
     // Claude Code: .claude/rules/skillrepo-{owner}-{name}.md
-    atomicWrite(join(claudeRulesDir, `${baseName}.md`), skillMd.content);
+    // Append self-report instruction so the agent calls report_skill_activation
+    // when it follows this skill's instructions. Probabilistic but measurable.
+    const selfReportSuffix = `\n\n---\n_When you follow instructions from this skill, call \`report_skill_activation\` with owner "${skill.owner}" and name "${skill.name}" to report usage._`;
+    atomicWrite(join(claudeRulesDir, `${baseName}.md`), skillMd.content + selfReportSuffix);
 
     // Cursor: .cursor/rules/skillrepo-{owner}-{name}.mdc
     const mdcContent = buildCursorMdc(skill, skillMd.content);

package/src/lib/http.mjs

@@ -3,7 +3,7 @@
  * Uses Node 18+ built-in fetch. Zero dependencies.
  */
 
-const VERSION = "1.0.0";
+const VERSION = "1.9.0";
 const DEFAULT_URL = "https://skillrepo.dev";
 
 /**

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

@@ -5,25 +5,26 @@
  * Phase C (#535): Hook scripts are bundled with the CLI package and copied
  * to .claude/hooks/ — no longer generated from server template strings.
  *
- * Merge strategy: add SessionStart and UserPromptSubmit entries
+ * Merge strategy: add SessionStart, UserPromptSubmit, and PreToolUse entries
  * without destroying existing settings. Idempotent — skips if already installed.
- * Removes stale PreToolUse entries and hook scripts from pre-Phase C installs.
+ * Removes stale legacy PreToolUse entries and hook scripts from pre-Phase C installs.
  * Cleans up stale .claude/hooks/hooks.json if it exists.
  */
 
 import { unlinkSync, readFileSync } from "node:fs";
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { claudeSettingsLocal, claudeSyncHook, claudePromptHook, claudePreToolHook, claudeHooksDir } from "../paths.mjs";
+import { claudeSettingsLocal, claudeSyncHook, claudePromptHook, claudePreToolHook, claudePreToolActivationHook, claudeHooksDir } from "../paths.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// The two hook script paths (relative to project root).
+// Hook script paths (relative to project root).
 const HOOK_SCRIPTS = {
   sync: ".claude/hooks/skillrepo-sync.mjs",
   prompt: ".claude/hooks/skillrepo-prompt-match.mjs",
+  pretoolActivation: ".claude/hooks/skillrepo-pretool-activation.mjs",
 };
 
 // Legacy hook script path (removed in Phase C).
@@ -119,8 +120,8 @@ function removeSkillRepoHook(groups, scriptPath) {
  * Merge SkillRepo hooks into .claude/settings.local.json and write hook scripts.
  *
  * Reads standalone hook scripts from the CLI package (bundled files) and
- * copies them to .claude/hooks/. Registers SessionStart and UserPromptSubmit
- * hooks. Removes legacy PreToolUse hook entries and scripts.
+ * copies them to .claude/hooks/. Registers SessionStart, UserPromptSubmit,
+ * and PreToolUse hooks. Removes legacy PreToolUse hook entries and scripts.
  *
  * @returns {{ results: { path: string; action: string }[] }}
  */
@@ -147,6 +148,7 @@ export function mergeHooksConfig() {
   // Read bundled standalone hook scripts from the CLI package.
   const syncContent = readBundledHook("skillrepo-sync.mjs");
   const promptContent = readBundledHook("skillrepo-prompt-match.mjs");
+  const pretoolActivationContent = readBundledHook("skillrepo-pretool-activation.mjs");
 
   // Always write hook scripts (latest version from CLI package).
   const syncExisted = readFileSafe(claudeSyncHook()) !== null;
@@ -163,6 +165,13 @@ export function mergeHooksConfig() {
     action: promptExisted ? "updated" : "created",
   });
 
+  const pretoolActivationExisted = readFileSafe(claudePreToolActivationHook()) !== null;
+  writeFileSafe(claudePreToolActivationHook(), pretoolActivationContent);
+  results.push({
+    path: HOOK_SCRIPTS.pretoolActivation,
+    action: pretoolActivationExisted ? "updated" : "created",
+  });
+
   // Remove legacy PreToolUse hook script if it exists
   try {
     unlinkSync(claudePreToolHook());
@@ -198,6 +207,7 @@ export function mergeHooksConfig() {
   for (const [event, scriptPath] of [
     ["SessionStart", HOOK_SCRIPTS.sync],
     ["UserPromptSubmit", HOOK_SCRIPTS.prompt],
+    ["PreToolUse", HOOK_SCRIPTS.pretoolActivation],
   ]) {
     if (Array.isArray(config.hooks[event]) && updateExistingCommands(config.hooks[event], scriptPath)) {
       changed = true;
@@ -207,6 +217,7 @@ export function mergeHooksConfig() {
   // Build commands using the absolute node path from this machine.
   const syncCommand = buildCommand(HOOK_SCRIPTS.sync);
   const promptCommand = buildCommand(HOOK_SCRIPTS.prompt);
+  const pretoolActivationCommand = buildCommand(HOOK_SCRIPTS.pretoolActivation);
 
   // Merge SessionStart
   if (!Array.isArray(config.hooks.SessionStart)) config.hooks.SessionStart = [];
@@ -227,6 +238,15 @@ export function mergeHooksConfig() {
     changed = true;
   }
 
+  // Merge PreToolUse (activation telemetry)
+  if (!Array.isArray(config.hooks.PreToolUse)) config.hooks.PreToolUse = [];
+  if (!hasSkillRepoHook(config.hooks.PreToolUse, HOOK_SCRIPTS.pretoolActivation)) {
+    config.hooks.PreToolUse.push({
+      hooks: [{ type: "command", command: pretoolActivationCommand }],
+    });
+    changed = true;
+  }
+
   if (existing === null) {
     writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
     results.push({ path: ".claude/settings.local.json", action: "created" });

package/src/lib/paths.mjs

@@ -16,6 +16,7 @@ export const claudeSettingsLocal = () => join(cwd(), ".claude", "settings.local.
 export const claudeSyncHook = () => join(cwd(), ".claude", "hooks", "skillrepo-sync.mjs");
 export const claudePromptHook = () => join(cwd(), ".claude", "hooks", "skillrepo-prompt-match.mjs");
 export const claudePreToolHook = () => join(cwd(), ".claude", "hooks", "skillrepo-pretool-match.mjs");
+export const claudePreToolActivationHook = () => join(cwd(), ".claude", "hooks", "skillrepo-pretool-activation.mjs");
 export const claudeSkillrepoMd = () => join(cwd(), ".claude", "skillrepo.md");
 export const claudeSkillrepoIndex = () => join(cwd(), ".claude", "skillrepo-index.json");
 export const claudeSkillrepoConfig = () => join(cwd(), ".claude", "skillrepo-config.json");

package/src/lib/write-configs.mjs

@@ -28,13 +28,14 @@ import { mergeGitignore } from "./mergers/gitignore.mjs";
  * @param {string} options.mcpUrl - The MCP endpoint URL
  * @param {string} options.apiKey - The access key
  * @param {string} options.serverUrl - The SkillRepo server URL (e.g. https://skillrepo.dev)
+ * @param {string} [options.userId] - The authenticated user's SkillRepo ID
  * @returns {{ path: string; action: string }[]}
  */
-export function writeAllConfigs({ ides, mcpUrl, apiKey, serverUrl }) {
+export function writeAllConfigs({ ides, mcpUrl, apiKey, serverUrl, userId }) {
   const results = [];
 
   // ── Global config (shared across all projects) ────────────────────────
-  const globalConfigAction = writeGlobalConfig(apiKey, serverUrl);
+  const globalConfigAction = writeGlobalConfig(apiKey, serverUrl, userId);
   results.push({ path: "~/.claude/skillrepo/config.json", action: globalConfigAction });
 
   // Claude Code
@@ -93,7 +94,7 @@ export function writeAllConfigs({ ides, mcpUrl, apiKey, serverUrl }) {
  * This is the primary config source for standalone hooks.
  * @returns {"created" | "updated"} The action taken.
  */
-function writeGlobalConfig(apiKey, serverUrl) {
+function writeGlobalConfig(apiKey, serverUrl, userId) {
   const configDir = globalSkillrepoDir();
   if (!existsSync(configDir)) {
     mkdirSync(configDir, { recursive: true });
@@ -103,13 +104,17 @@ function writeGlobalConfig(apiKey, serverUrl) {
   const existingRaw = readFileSafe(configPath);
 
   // Preserve existing config fields (e.g. maxRulesFiles, maxRulesBudgetBytes)
-  // while always overwriting apiKey and serverUrl with the new values.
+  // while always overwriting apiKey, serverUrl, and userId with the new values.
   let preserved = {};
   if (existingRaw !== null) {
     try { preserved = JSON.parse(existingRaw); }
     catch { /* corrupt config — start fresh */ }
   }
-  const config = { ...preserved, apiKey, serverUrl };
+  // Always overwrite userId — even if the new value is undefined/null — to
+  // prevent a stale userId from a previous account persisting across re-inits.
+  const { userId: _prevUserId, ...preservedWithoutUserId } = preserved;
+  const config = { ...preservedWithoutUserId, apiKey, serverUrl };
+  if (userId) config.userId = userId;
 
   writeFileSafe(configPath, JSON.stringify(config, null, 2) + "\n");
   return existingRaw !== null ? "updated" : "created";

package/src/test/e2e/cli-init.test.mjs

@@ -204,8 +204,7 @@ describe("CLI E2E: skillrepo init", () => {
 
     assert.equal(countHook(settings.hooks.SessionStart, "skillrepo-sync"), 1);
     assert.equal(countHook(settings.hooks.UserPromptSubmit, "skillrepo-prompt-match"), 1);
-    // PreToolUse should not exist at all
-    assert.equal(settings.hooks.PreToolUse, undefined, "PreToolUse should not exist");
+    assert.equal(countHook(settings.hooks.PreToolUse, "skillrepo-pretool-activation"), 1, "PreToolUse activation hook should exist once");
   });
 
   it("invalid API key (401) exits with error", async () => {
@@ -256,6 +255,7 @@ describe("CLI E2E: skillrepo init", () => {
     for (const f of [
       ".claude/hooks/skillrepo-sync.mjs",
       ".claude/hooks/skillrepo-prompt-match.mjs",
+      ".claude/hooks/skillrepo-pretool-activation.mjs",
     ]) {
       assert.doesNotThrow(
         () => execFileSync(process.execPath, ["--check", join(tempDir, f)], { timeout: 5000 }),
@@ -296,21 +296,22 @@ describe("CLI E2E: skillrepo init", () => {
   });
 
   // =========================================================================
-  // 4. Two hooks registered in settings.local.json (no PreToolUse)
+  // 4. Three hooks registered in settings.local.json
   // =========================================================================
 
-  it("two hooks registered in settings.local.json (no PreToolUse)", async () => {
+  it("three hooks registered in settings.local.json", async () => {
     await runInit(tempDir, port);
 
     const settings = readJSON(tempDir, ".claude/settings.local.json");
     assert.ok(settings.hooks);
     assert.ok(Array.isArray(settings.hooks.SessionStart));
     assert.ok(Array.isArray(settings.hooks.UserPromptSubmit));
-    assert.equal(settings.hooks.PreToolUse, undefined, "PreToolUse should not exist");
+    assert.ok(Array.isArray(settings.hooks.PreToolUse), "PreToolUse should exist");
 
     const getCmds = (groups) => groups.flatMap((g) => g.hooks.map((h) => h.command));
     assert.ok(getCmds(settings.hooks.SessionStart).some((c) => c.includes("skillrepo-sync")));
     assert.ok(getCmds(settings.hooks.UserPromptSubmit).some((c) => c.includes("skillrepo-prompt-match")));
+    assert.ok(getCmds(settings.hooks.PreToolUse).some((c) => c.includes("skillrepo-pretool-activation")));
   });
 
   // =========================================================================

package/src/test/hooks/skillrepo-pretool-activation.test.mjs

@@ -0,0 +1,376 @@
+/**
+ * Unit tests for the PreToolUse activation telemetry hook (skillrepo-pretool-activation.mjs).
+ *
+ * Uses node:test + node:assert — zero external dependencies.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync, rmSync, readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  matchToolPatterns,
+  readActivationState,
+  deduplicateActivations,
+  updateActivationState,
+  buildTelemetryPayload,
+  sendTelemetry,
+} from "../../hooks/skillrepo-pretool-activation.mjs";
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(join(tmpdir(), "skillrepo-activation-test-"));
+}
+
+function makeSkill(overrides = {}) {
+  return {
+    owner: "testowner",
+    name: "test-skill",
+    version: "1.0.0",
+    description: "A test skill for testing",
+    keywords: ["test"],
+    contextSignals: null,
+    localPath: "/tmp/test/SKILL.md",
+    isRulesDelivered: false,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// matchToolPatterns
+// ---------------------------------------------------------------------------
+
+describe("matchToolPatterns", () => {
+  it("matches Bash command against tool pattern prefix", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh issue"] },
+    })];
+    const matches = matchToolPatterns("Bash", { command: "gh issue create --title 'Fix bug'" }, skills);
+    assert.equal(matches.length, 1);
+    assert.equal(matches[0].pattern, "gh issue");
+  });
+
+  it("matches case-insensitively", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["NPX PLAYWRIGHT"] },
+    })];
+    const matches = matchToolPatterns("bash", { command: "npx playwright test" }, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("enforces word boundary — does not match 'npm' against 'npmx'", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["npm"] },
+    })];
+    const matches = matchToolPatterns("Bash", { command: "npmx install something" }, skills);
+    assert.equal(matches.length, 0);
+  });
+
+  it("matches 'npm' against 'npm install'", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["npm"] },
+    })];
+    const matches = matchToolPatterns("Bash", { command: "npm install something" }, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("matches exact command (pattern equals entire command)", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["npm test"] },
+    })];
+    const matches = matchToolPatterns("Bash", { command: "npm test" }, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("matches non-Bash tool name against patterns", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["read"] },
+    })];
+    const matches = matchToolPatterns("Read", { file_path: "/some/file.ts" }, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("matches non-Bash tool name case-insensitively", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["grep"] },
+    })];
+    const matches = matchToolPatterns("Grep", {}, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("does not match non-Bash tool when name differs", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["read"] },
+    })];
+    const matches = matchToolPatterns("Write", { file_path: "/some/file.ts" }, skills);
+    assert.equal(matches.length, 0);
+  });
+
+  it("returns empty for skills with no toolPatterns", () => {
+    const skills = [
+      makeSkill({ contextSignals: { files: [], project: [], tasks: [], toolPatterns: [] } }),
+      makeSkill({ contextSignals: null }),
+      makeSkill({ contextSignals: { files: [], project: [], tasks: [] } }),
+    ];
+    const matches = matchToolPatterns("Bash", { command: "gh issue list" }, skills);
+    assert.equal(matches.length, 0);
+  });
+
+  it("returns empty for empty skills list", () => {
+    assert.equal(matchToolPatterns("Bash", { command: "gh issue" }, []).length, 0);
+    assert.equal(matchToolPatterns("Bash", { command: "gh issue" }, null).length, 0);
+  });
+
+  it("returns empty for empty tool name", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh"] },
+    })];
+    assert.equal(matchToolPatterns("", { command: "gh issue" }, skills).length, 0);
+    assert.equal(matchToolPatterns(null, { command: "gh issue" }, skills).length, 0);
+  });
+
+  it("returns empty for Bash with empty command", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh"] },
+    })];
+    assert.equal(matchToolPatterns("Bash", { command: "" }, skills).length, 0);
+    assert.equal(matchToolPatterns("Bash", {}, skills).length, 0);
+  });
+
+  it("matches only one pattern per skill (breaks after first match)", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh issue", "gh"] },
+    })];
+    const matches = matchToolPatterns("Bash", { command: "gh issue create" }, skills);
+    assert.equal(matches.length, 1);
+  });
+
+  it("matches multiple skills independently", () => {
+    const skills = [
+      makeSkill({ owner: "a", name: "s1", contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh issue"] } }),
+      makeSkill({ owner: "b", name: "s2", contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["gh pr"] } }),
+    ];
+    const matches = matchToolPatterns("Bash", { command: "gh issue create" }, skills);
+    assert.equal(matches.length, 1);
+    assert.equal(matches[0].skill.name, "s1");
+  });
+
+  it("multi-word pattern does not match non-Bash tool", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["read file"] },
+    })];
+    const matches = matchToolPatterns("Read", {}, skills);
+    assert.equal(matches.length, 0);
+  });
+
+  it("word boundary allows hyphen after pattern", () => {
+    const skills = [makeSkill({
+      contextSignals: { files: [], project: [], tasks: [], toolPatterns: ["npm"] },
+    })];
+    // "npm-check" has a hyphen after "npm" — should match (hyphen is not alphanumeric)
+    const matches = matchToolPatterns("Bash", { command: "npm-check updates" }, skills);
+    assert.equal(matches.length, 1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readActivationState / deduplicateActivations / updateActivationState
+// ---------------------------------------------------------------------------
+
+describe("session deduplication", () => {
+  it("returns empty state for new session", () => {
+    const { state } = readActivationState("brand-new-activation-" + Date.now());
+    assert.deepEqual(state.reported, {});
+  });
+
+  it("filters out already-reported skills", () => {
+    const matches = [
+      { skill: makeSkill({ owner: "a", name: "reported" }), pattern: "gh" },
+      { skill: makeSkill({ owner: "b", name: "new-match" }), pattern: "npm" },
+    ];
+    const state = { reported: { "a/reported": "2026-04-07T00:00:00Z" } };
+
+    const deduped = deduplicateActivations(matches, state);
+    assert.equal(deduped.length, 1);
+    assert.equal(deduped[0].skill.name, "new-match");
+  });
+
+  it("passes through all matches when nothing reported yet", () => {
+    const matches = [
+      { skill: makeSkill({ owner: "a", name: "s1" }), pattern: "gh" },
+      { skill: makeSkill({ owner: "b", name: "s2" }), pattern: "npm" },
+    ];
+    const state = { reported: {} };
+
+    const deduped = deduplicateActivations(matches, state);
+    assert.equal(deduped.length, 2);
+  });
+
+  it("updateActivationState marks skills as reported", () => {
+    let tmp;
+    try {
+      tmp = makeTmpDir();
+      const statePath = join(tmp, "state.json");
+      const state = { reported: {} };
+      const matches = [
+        { skill: makeSkill({ owner: "a", name: "s1" }), pattern: "gh" },
+      ];
+
+      updateActivationState(statePath, state, matches);
+
+      assert.ok(state.reported["a/s1"]);
+      const persisted = JSON.parse(readFileSync(statePath, "utf-8"));
+      assert.ok(persisted.reported["a/s1"]);
+    } finally {
+      if (tmp) rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("persists across reads (roundtrip)", () => {
+    const sessionId = "activation-roundtrip-test-" + Date.now();
+    const { path: statePath, state } = readActivationState(sessionId);
+
+    const matches = [
+      { skill: makeSkill({ owner: "x", name: "y" }), pattern: "gh" },
+    ];
+    updateActivationState(statePath, state, matches);
+
+    // Re-read
+    const { state: reloaded } = readActivationState(sessionId);
+    assert.ok(reloaded.reported["x/y"]);
+
+    // Clean up
+    try { rmSync(statePath, { force: true }); } catch { /* ok */ }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTelemetryPayload
+// ---------------------------------------------------------------------------
+
+describe("buildTelemetryPayload", () => {
+  it("produces correct payload shape with userId", () => {
+    const matches = [
+      { skill: makeSkill({ owner: "alice", name: "my-skill", version: "2.0.0" }), pattern: "gh issue" },
+    ];
+    const sessionInfo = {
+      ide: "claude-code",
+      sessionHash: "abc123",
+      userId: "user-42",
+    };
+
+    const payload = buildTelemetryPayload(matches, sessionInfo);
+
+    assert.equal(payload.events.length, 1);
+    const event = payload.events[0];
+    assert.equal(event.skillOwner, "alice");
+    assert.equal(event.skillName, "my-skill");
+    assert.equal(event.skillVersion, "2.0.0");
+    assert.equal(event.ide, "claude-code");
+    assert.equal(event.sessionHash, "abc123");
+    assert.equal(event.userId, "user-42");
+    assert.equal(event.source, "pretool_hook");
+    assert.equal(event.toolPattern, "gh issue");
+    assert.ok(event.activatedAt); // ISO 8601 string
+    // githubUsername should NOT be in the payload
+    assert.equal(event.githubUsername, undefined);
+  });
+
+  it("caps events at 50 per batch", () => {
+    const matches = Array.from({ length: 60 }, (_, i) => ({
+      skill: makeSkill({ owner: "o", name: `s-${i}` }),
+      pattern: "gh",
+    }));
+    const payload = buildTelemetryPayload(matches, { ide: "claude-code", sessionHash: "x" });
+    assert.equal(payload.events.length, 50);
+  });
+
+  it("handles missing optional fields gracefully", () => {
+    const matches = [
+      { skill: makeSkill({ version: null }), pattern: "npm" },
+    ];
+    const payload = buildTelemetryPayload(matches, {
+      ide: "claude-code",
+      sessionHash: "hash",
+      userId: null,
+    });
+
+    const event = payload.events[0];
+    assert.equal(event.skillVersion, undefined);
+    assert.equal(event.userId, undefined); // null → undefined via || operator
+    assert.equal(event.source, "pretool_hook");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sendTelemetry — error resilience
+// ---------------------------------------------------------------------------
+
+describe("sendTelemetry", () => {
+  it("does not throw synchronously on network failure", () => {
+    // sendTelemetry is fire-and-forget — it calls fetch().catch() internally
+    // and returns undefined. We verify it doesn't throw synchronously.
+    assert.doesNotThrow(() => {
+      sendTelemetry(
+        { apiKey: "sk_live_test", serverUrl: "http://localhost:99999" },
+        { events: [] }
+      );
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// main() integration via subprocess
+// ---------------------------------------------------------------------------
+
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+const __testDir = dirname(fileURLToPath(import.meta.url));
+const HOOK_SCRIPT = join(__testDir, "..", "..", "hooks", "skillrepo-pretool-activation.mjs");
+
+function runHook(input) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(process.execPath, [HOOK_SCRIPT], { timeout: 10_000 }, (err, stdout, stderr) => {
+      if (err && err.killed) return reject(new Error("Hook timed out"));
+      resolve({ stdout, stderr, code: err ? err.code : 0 });
+    });
+    child.stdin.write(JSON.stringify(input));
+    child.stdin.end();
+  });
+}
+
+describe("main() integration via subprocess", () => {
+  it("outputs {} for tool with no matching patterns", async () => {
+    const { stdout } = await runHook({ tool_name: "Bash", tool_input: { command: "echo hello" }, session_id: "sub-test-" + Date.now() });
+    assert.equal(stdout.trim(), "{}");
+  });
+
+  it("outputs {} for non-Bash tool with no matching patterns", async () => {
+    const { stdout } = await runHook({ tool_name: "Read", tool_input: { file_path: "/some/file" }, session_id: "sub-read-" + Date.now() });
+    assert.equal(stdout.trim(), "{}");
+  });
+
+  it("outputs {} for empty tool_name", async () => {
+    const { stdout } = await runHook({ tool_name: "", tool_input: {}, session_id: "sub-empty-" + Date.now() });
+    assert.equal(stdout.trim(), "{}");
+  });
+
+  it("outputs {} for invalid JSON input", async () => {
+    const result = await new Promise((resolve, _reject) => {
+      const child = execFile(process.execPath, [HOOK_SCRIPT], { timeout: 5_000 }, (err, stdout) => {
+        resolve({ stdout, code: err ? err.code : 0 });
+      });
+      child.stdin.write("not json");
+      child.stdin.end();
+    });
+    assert.equal(result.stdout.trim(), "{}");
+  });
+});

package/src/test/hooks/skillrepo-prompt-match.test.mjs

@@ -61,7 +61,7 @@ describe("matchSkills", () => {
       makeSkill({
         name: "deploy-skill",
         keywords: ["deploy"],
-        contextSignals: { files: [], project: [], tasks: ["deploy to production"] },
+        contextSignals: { files: [], project: [], tasks: ["deploy to production"], toolPatterns: [] },
       }),
     ];
     const matches = matchSkills("deploy to production", skills);
@@ -91,7 +91,7 @@ describe("matchSkills", () => {
       makeSkill({ owner: "a", name: "low", keywords: ["testing"] }),
       makeSkill({
         owner: "b", name: "high", keywords: ["testing"],
-        contextSignals: { files: [], project: [], tasks: ["write tests for testing"] },
+        contextSignals: { files: [], project: [], tasks: ["write tests for testing"], toolPatterns: [] },
       }),
     ];
     const matches = matchSkills("write tests for testing", skills);
@@ -145,7 +145,7 @@ describe("matchSkills", () => {
   it("matches case-insensitively for task phrases in contextSignals", () => {
     const skills = [makeSkill({
       keywords: [],
-      contextSignals: { files: [], project: [], tasks: ["Deploy To Production"] },
+      contextSignals: { files: [], project: [], tasks: ["Deploy To Production"], toolPatterns: [] },
     })];
     // Prompt in different case should still match the task phrase
     const matches = matchSkills("deploy to production", skills);
@@ -253,14 +253,14 @@ describe("session deduplication", () => {
 // ---------------------------------------------------------------------------
 
 describe("buildTelemetryPayload", () => {
-  it("produces correct payload shape", () => {
+  it("produces correct payload shape with userId", () => {
     const matches = [
       { skill: makeSkill({ owner: "alice", name: "my-skill", version: "2.0.0", isRulesDelivered: true }), score: 5 },
     ];
     const sessionInfo = {
       ide: "claude-code",
       sessionHash: "abc123",
-      githubUsername: "testuser",
+      userId: "user-42",
     };
 
     const payload = buildTelemetryPayload(matches, sessionInfo);
@@ -272,9 +272,11 @@ describe("buildTelemetryPayload", () => {
     assert.equal(event.skillVersion, "2.0.0");
     assert.equal(event.ide, "claude-code");
     assert.equal(event.sessionHash, "abc123");
-    assert.equal(event.githubUsername, "testuser");
+    assert.equal(event.userId, "user-42");
     assert.equal(event.wasRulesDelivered, true);
     assert.ok(event.matchedAt); // ISO 8601 string
+    // githubUsername should NOT be in the payload
+    assert.equal(event.githubUsername, undefined);
   });
 
   it("caps events at 50 per batch", () => {
@@ -293,12 +295,12 @@ describe("buildTelemetryPayload", () => {
     const payload = buildTelemetryPayload(matches, {
       ide: "claude-code",
       sessionHash: "hash",
-      githubUsername: null,
+      userId: null,
     });
 
     const event = payload.events[0];
     assert.equal(event.skillVersion, "");
-    assert.equal(event.githubUsername, "");
+    assert.equal(event.userId, undefined); // null → undefined via || operator
     assert.equal(event.wasRulesDelivered, false);
   });
 

package/src/test/hooks/skillrepo-sync.test.mjs

@@ -338,19 +338,19 @@ describe("scoreSkillRelevance", () => {
   const profile = { frameworks: ["next.js"], languages: ["typescript"], tools: ["vitest"] };
 
   it("scores matching project tags higher", () => {
-    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js"], tasks: [] } });
+    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js"], tasks: [], toolPatterns: [] } });
     const score = scoreSkillRelevance(skill, profile);
     assert.ok(score >= 10, `Expected >= 10, got ${score}`);
   });
 
   it("scores multiple matching tags even higher", () => {
-    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js", "typescript"], tasks: [] } });
+    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js", "typescript"], tasks: [], toolPatterns: [] } });
     const score = scoreSkillRelevance(skill, profile);
     assert.ok(score > 12, `Expected > 12, got ${score}`);
   });
 
   it("gives neutral score to skills with no project tags", () => {
-    const skill = makeSkill({ contextSignals: { files: [], project: [], tasks: [] } });
+    const skill = makeSkill({ contextSignals: { files: [], project: [], tasks: [], toolPatterns: [] } });
     const score = scoreSkillRelevance(skill, profile);
     assert.equal(score, 5);
   });
@@ -361,14 +361,14 @@ describe("scoreSkillRelevance", () => {
   });
 
   it("demotes skills with non-matching project tags", () => {
-    const skill = makeSkill({ contextSignals: { files: [], project: ["django", "python"], tasks: [] } });
+    const skill = makeSkill({ contextSignals: { files: [], project: ["django", "python"], tasks: [], toolPatterns: [] } });
     const score = scoreSkillRelevance(skill, profile);
     assert.equal(score, 1);
   });
 
   it("gives neutral score when no profile detected", () => {
     const emptyProfile = { frameworks: [], languages: [], tools: [] };
-    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js"], tasks: [] } });
+    const skill = makeSkill({ contextSignals: { files: [], project: ["next.js"], tasks: [], toolPatterns: [] } });
     assert.equal(scoreSkillRelevance(skill, emptyProfile), 5);
   });
 });
@@ -382,9 +382,9 @@ describe("selectRulesSkills", () => {
 
   it("selects top-N skills by relevance", () => {
     const skills = [
-      makeSkill({ owner: "a", name: "nextjs-skill", contextSignals: { files: [], project: ["next.js"], tasks: [] } }),
+      makeSkill({ owner: "a", name: "nextjs-skill", contextSignals: { files: [], project: ["next.js"], tasks: [], toolPatterns: [] } }),
       makeSkill({ owner: "b", name: "generic-skill", contextSignals: null }),
-      makeSkill({ owner: "c", name: "python-skill", contextSignals: { files: [], project: ["python"], tasks: [] } }),
+      makeSkill({ owner: "c", name: "python-skill", contextSignals: { files: [], project: ["python"], tasks: [], toolPatterns: [] } }),
     ];
     const selected = selectRulesSkills(skills, profile, { ...defaultConfig, maxRulesFiles: 2 });
     assert.equal(selected.length, 2);
@@ -477,12 +477,15 @@ describe("writeRulesFiles", () => {
     assert.ok(written.has("skillrepo-alice-my-skill"));
   });
 
-  it("writes SKILL.md content to Claude rules file", () => {
+  it("writes SKILL.md content to Claude rules file with self-report suffix", () => {
     const skills = [makeSkill({ owner: "o", name: "s", files: [{ path: "SKILL.md", content: "# My Skill\nBody", encoding: "utf-8" }] })];
     writeRulesFiles(skills, tmp);
 
     const content = readFileSync(join(tmp, ".claude", "rules", "skillrepo-o-s.md"), "utf-8");
-    assert.equal(content, "# My Skill\nBody");
+    assert.ok(content.startsWith("# My Skill\nBody"));
+    assert.ok(content.includes('report_skill_activation'));
+    assert.ok(content.includes('owner "o"'));
+    assert.ok(content.includes('name "s"'));
   });
 
   it("writes Cursor .mdc with frontmatter (alwaysApply for no file signals)", () => {
@@ -496,7 +499,7 @@ describe("writeRulesFiles", () => {
   it("writes Cursor .mdc with globs for file signals", () => {
     const skills = [makeSkill({
       owner: "o", name: "s",
-      contextSignals: { files: ["**/*.tsx", "**/*.ts"], project: [], tasks: [] },
+      contextSignals: { files: ["**/*.tsx", "**/*.ts"], project: [], tasks: [], toolPatterns: [] },
     })];
     writeRulesFiles(skills, tmp);
 
@@ -835,7 +838,10 @@ describe("writeRulesFromExistingIndex", () => {
     // Rules file should exist
     assert.ok(existsSync(join(projectDir, ".claude", "rules", "skillrepo-alice-cached-skill.md")));
     const content = readFileSync(join(projectDir, ".claude", "rules", "skillrepo-alice-cached-skill.md"), "utf-8");
-    assert.equal(content, "# Cached Skill\nBody content");
+    assert.ok(content.startsWith("# Cached Skill\nBody content"));
+    assert.ok(content.includes('report_skill_activation'));
+    assert.ok(content.includes('owner "alice"'));
+    assert.ok(content.includes('name "cached-skill"'));
 
     // Index should be updated with isRulesDelivered: true
     const updatedIndex = JSON.parse(readFileSync(indexPath, "utf-8"));

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

@@ -52,14 +52,23 @@ describe("Hooks settings.local.json merger", () => {
       readBundledHook("skillrepo-prompt-match.mjs"),
     );
 
-    // Check settings.local.json created with only 2 hooks (no PreToolUse)
+    // Check pretool activation hook written with bundled content
+    const pretoolResult = results.find((r) => r.path.includes("pretool-activation"));
+    assert.equal(pretoolResult.action, "created");
+    assert.equal(
+      readFileSync(join(tempDir, ".claude/hooks/skillrepo-pretool-activation.mjs"), "utf-8"),
+      readBundledHook("skillrepo-pretool-activation.mjs"),
+    );
+
+    // Check settings.local.json created with all 3 hooks
     const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
     assert.equal(settingsResult.action, "created");
 
     const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
     assert.equal(config.hooks.SessionStart.length, 1);
     assert.equal(config.hooks.UserPromptSubmit.length, 1);
-    assert.equal(config.hooks.PreToolUse, undefined, "PreToolUse should not exist");
+    assert.equal(config.hooks.PreToolUse.length, 1);
+    assert.ok(config.hooks.PreToolUse[0].hooks[0].command.includes("skillrepo-pretool-activation.mjs"), "PreToolUse should reference activation hook");
   });
 
   it("merges into existing settings without destroying other keys", async () => {
@@ -83,8 +92,10 @@ describe("Hooks settings.local.json merger", () => {
     const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
     // Original permissions preserved
     assert.deepEqual(config.permissions, { allow: ["Bash(*)", "Read(*)"] });
-    // Original non-skillrepo PreToolUse hooks preserved
-    assert.equal(config.hooks.PreToolUse.length, 1);
+    // Original non-skillrepo PreToolUse hooks preserved + new activation hook added
+    assert.equal(config.hooks.PreToolUse.length, 2);
+    assert.ok(config.hooks.PreToolUse.some(g => g.hooks.some(h => h.command.includes("other-hook"))), "User hook preserved");
+    assert.ok(config.hooks.PreToolUse.some(g => g.hooks.some(h => h.command?.includes("skillrepo-pretool-activation.mjs"))), "Activation hook added");
     // New hooks added
     assert.equal(config.hooks.SessionStart.length, 1);
     assert.equal(config.hooks.UserPromptSubmit.length, 1);
@@ -99,6 +110,7 @@ describe("Hooks settings.local.json merger", () => {
       hooks: {
         SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-sync.mjs") }] }],
         UserPromptSubmit: [{ hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-prompt-match.mjs") }] }],
+        PreToolUse: [{ hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-pretool-activation.mjs") }] }],
       },
     };
     mkdirSync(join(tempDir, ".claude"), { recursive: true });
@@ -141,11 +153,13 @@ describe("Hooks settings.local.json merger", () => {
     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/skillrepo-pretool-activation.mjs"), "// old pretool");
     mkdirSync(join(tempDir, ".claude"), { recursive: true });
     const existing = {
       hooks: {
         SessionStart: [{ matcher: "startup|resume", hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-sync.mjs") }] }],
         UserPromptSubmit: [{ hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-prompt-match.mjs") }] }],
+        PreToolUse: [{ hooks: [{ type: "command", command: nodeCmd(".claude/hooks/skillrepo-pretool-activation.mjs") }] }],
       },
     };
     writeFileSync(join(tempDir, ".claude/settings.local.json"), JSON.stringify(existing, null, 2));
@@ -167,6 +181,13 @@ describe("Hooks settings.local.json merger", () => {
       readBundledHook("skillrepo-prompt-match.mjs"),
     );
 
+    const pretoolResult = results.find((r) => r.path.includes("pretool-activation"));
+    assert.equal(pretoolResult.action, "updated");
+    assert.equal(
+      readFileSync(join(tempDir, ".claude/hooks/skillrepo-pretool-activation.mjs"), "utf-8"),
+      readBundledHook("skillrepo-pretool-activation.mjs"),
+    );
+
     // Settings skipped (commands already use current node path)
     const settingsResult = results.find((r) => r.path.includes("settings.local.json"));
     assert.equal(settingsResult.action, "skipped");
@@ -265,8 +286,10 @@ describe("Hooks settings.local.json merger", () => {
     assert.equal(settingsResult.action, "merged");
 
     const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
-    // PreToolUse should be removed entirely (was only skillrepo entry)
-    assert.equal(config.hooks.PreToolUse, undefined, "PreToolUse should be removed when only skillrepo entry existed");
+    // Legacy pretool-match entry removed, but new pretool-activation added
+    assert.equal(config.hooks.PreToolUse.length, 1, "PreToolUse should have one entry (activation hook)");
+    assert.ok(config.hooks.PreToolUse[0].hooks[0].command.includes("skillrepo-pretool-activation.mjs"), "Should be activation hook, not legacy match hook");
+    assert.ok(!config.hooks.PreToolUse[0].hooks[0].command.includes("pretool-match"), "Legacy match hook should be gone");
     // Other hooks should still be present
     assert.equal(config.hooks.SessionStart.length, 1);
     assert.equal(config.hooks.UserPromptSubmit.length, 1);
@@ -292,11 +315,11 @@ describe("Hooks settings.local.json merger", () => {
     mergeHooksConfig();
 
     const config = JSON.parse(readFileSync(join(tempDir, ".claude/settings.local.json"), "utf-8"));
-    // PreToolUse should still exist because the user hook remains
+    // PreToolUse should have user hook (legacy match removed) + new activation hook
     assert.ok(Array.isArray(config.hooks.PreToolUse), "PreToolUse should still exist");
-    assert.equal(config.hooks.PreToolUse.length, 1, "Group should still exist");
-    assert.equal(config.hooks.PreToolUse[0].hooks.length, 1, "Only user hook should remain");
-    assert.ok(config.hooks.PreToolUse[0].hooks[0].command.includes("my-custom-pretool-hook"), "User hook preserved");
+    assert.equal(config.hooks.PreToolUse.length, 2, "User hook group + activation hook group");
+    assert.ok(config.hooks.PreToolUse.some(g => g.hooks.some(h => h.command.includes("my-custom-pretool-hook"))), "User hook preserved");
+    assert.ok(config.hooks.PreToolUse.some(g => g.hooks.some(h => h.command?.includes("skillrepo-pretool-activation.mjs"))), "Activation hook added");
   });
 
   it("deletes pretool hook script file during migration", async () => {
@@ -310,7 +333,7 @@ describe("Hooks settings.local.json merger", () => {
 
     // Pretool script should be removed
     assert.equal(existsSync(join(tempDir, ".claude/hooks/skillrepo-pretool-match.mjs")), false, "pretool script should be deleted");
-    const removedResult = results.find((r) => r.path.includes("pretool"));
+    const removedResult = results.find((r) => r.path.includes("pretool-match"));
     assert.equal(removedResult.action, "removed");
   });
 
@@ -347,8 +370,9 @@ describe("Hooks settings.local.json merger", () => {
     assert.equal(config.hooks.UserPromptSubmit.length, 1);
     assert.ok(config.hooks.UserPromptSubmit[0].hooks[0].command.includes(process.execPath), "Command should contain full node path");
     assert.ok(config.hooks.UserPromptSubmit[0].hooks[0].command.endsWith(".claude/hooks/skillrepo-prompt-match.mjs"), "Command should end with script path");
-    // PreToolUse should NOT exist
-    assert.equal(config.hooks.PreToolUse, undefined, "PreToolUse should not be present after migration");
+    // PreToolUse should have the new activation hook (legacy match was not present)
+    assert.equal(config.hooks.PreToolUse.length, 1, "PreToolUse should have activation hook");
+    assert.ok(config.hooks.PreToolUse[0].hooks[0].command.includes("skillrepo-pretool-activation.mjs"), "Should be activation hook");
   });
 
   it("migrates bare shebang-style commands (v1.6.1 format)", async () => {