skillrepo 3.2.0 → 4.1.0

package/README.md

@@ -6,8 +6,8 @@ A pull-based CLI for managing your agent-skills library from the terminal.
 npx skillrepo init
 ```
 
-Validates your access key, auto-detects your IDEs, wires up the MCP config,
-and pulls your library. Safe to re-run at any time.
+Validates your access key, picks which agents to configure, wires up the
+MCP config, and pulls your library. Safe to re-run at any time.
 
 ## Install
 
@@ -34,8 +34,10 @@ Requires Node.js 18 or later.
    the terminal. The page works headless too — copy the key from any
    browser if your terminal can't auto-launch one.
 2. **Your library is now on disk.** The CLI wrote skills into
-   `.claude/skills/` (project) and registered the MCP server with every IDE
-   it detected (`.claude/`, `.cursor/`, `.vscode/`, `~/.codeium/windsurf/`).
+   `.claude/skills/` (for Claude Code) and `.agents/skills/` (the
+   shared path for Cursor, Windsurf, Gemini CLI, Codex CLI, Cline,
+   VS Code + Copilot, and others). Both paths are added to
+   `.gitignore` — skills are a per-developer cache, not committed.
 3. **From now on**, use `skillrepo update` to pull new versions,
    `skillrepo add` to add skills to your library, and `skillrepo list` to
    see what you have.
@@ -49,12 +51,30 @@ Requires Node.js 18 or later.
 ### `init` — first-run setup
 
 ```sh
-skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--ide <list>] [--global] [--json] [--no-session-sync]
+skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--agent <list>] [--global] [--json] [--no-session-sync]
 ```
 
-Validates your access key, detects installed IDEs, writes the MCP config,
-installs the Claude Code SessionStart hook (opt-in — see `session-sync`
-below), and runs the first library sync.
+Validates your access key, picks which targets to configure (interactive
+two-row picker by default — Claude Code at `.claude/skills/` and the
+shared `.agents/skills/` cohort path for everything else), writes the
+MCP config, installs the Claude Code SessionStart hook (opt-in — see
+`session-sync` below), and runs the first library sync.
+
+Detection drives the picker's pre-checked rows. Three signal types per
+agent are probed:
+- **Active session** env vars (e.g., `CLAUDECODE`, `CURSOR_AGENT`,
+  `GEMINI_CLI`, `CLINE_ACTIVE`) — strongest signal, indicates the
+  agent is currently running.
+- **HOME traces** (e.g., `~/.claude/`, `~/.cursor/`, `~/.codeium/windsurf/`)
+  — installed-on-this-machine signal.
+- **Project dotfiles** (e.g., `.claude/`, `.cursor/`, `.github/skills/`)
+  — configured-for-this-repo signal.
+
+When any signal fires for either target, that row pre-checks. Fresh
+clone with no detection: both rows still pre-checked — the product's
+job is to set up skills, defaulting to "do nothing" because env vars
+didn't fire is wrong. Pick the third row ("None") to skip placement
+and just write the config + gitignore.
 
 | Flag | Description |
 |------|-------------|
@@ -62,10 +82,53 @@ below), and runs the first library sync.
 | `--url, -u <url>` | Server URL. Defaults to `https://skillrepo.dev`. Use for self-hosted. |
 | `--yes, -y` | Non-interactive. Skip all confirmation prompts. Required for CI. Installs the session-sync hook by default — pass `--no-session-sync` to opt out. Under `npx`, this also auto-runs `npm install -g skillrepo@<this-version>` if no global install is present (so the session-sync hook can use the resulting absolute path). |
 | `--force` | Re-prompt for a new key even if `~/.claude/skillrepo/config.json` is valid. |
-| `--ide <list>` | Comma-separated vendor override. One or more of `claude`, `cursor`, `windsurf`, `vscode`, or `all`. |
+| `--agent <list>` | Comma-separated agent target override. Canonical tokens: `claude` (Claude Code), `agents` (every other supported vendor — Cursor, Windsurf, Gemini CLI, Codex CLI, Cline, VS Code + Copilot — sharing the `.agents/skills/` cohort path), `none` (skip placement entirely; init still writes config + gitignore). Vendor names like `cursor` or `claude-code` are accepted as silent aliases. |
 | `--global` | Write skills to `~/.claude/skills/` (personal) instead of `.claude/skills/` (project). |
 | `--no-session-sync` | Skip step 6 (SessionStart hook install). Works in both interactive and `--yes` modes. Use for CI scripts that bootstrap a project without ever starting a Claude Code session. |
-| `--json` | Emit a structured JSON summary on success. Includes a `sessionSync: { action, path }` block describing whether the hook was installed. |
+| `--json` | Emit a structured JSON summary on success. Requires `--yes`. See JSON output shape below. |
+
+#### JSON output shape (`init --json --yes`)
+
+```json
+{
+  "action": "initialized",
+  "account": { "slug": "...", "id": "...", "tier": "free|pro|enterprise" },
+  "config": { "action": "created|updated|unchanged" },
+  "vendors": ["claudeCode", "cursor", "..."],
+  "mcp": {
+    "merged": [".mcp.json", ".cursor/mcp.json"],
+    "skipped": ["..."],
+    "failed": [{ "path": "...", "reason": "..." }]
+  },
+  "sessionSync": {
+    "action": "installed|unchanged|skipped|failed|not-applicable",
+    "path": "...",
+    "cohortHooks": [
+      {
+        "vendorKey": "cursor|gemini|codex|copilot",
+        "displayName": "...",
+        "path": "~/.cursor/hooks.json",
+        "action": "installed|updated|unchanged|failed",
+        "reason": "..."
+      }
+    ]
+  },
+  "sync": {
+    "added": 0,
+    "updated": 0,
+    "removed": 0,
+    "notModified": false,
+    "fullSync": true,
+    "syncedAt": "2026-05-01T00:00:00.000Z"
+  }
+}
+```
+
+Field notes:
+- `vendors` is the resolved canonical-key list, NOT the raw `--agent` input. `--agent agents` produces every cohort vendor (cursor, windsurf, gemini, codex, cline, copilot); `--agent none` produces an empty array.
+- `sessionSync.cohortHooks[]` reports per-vendor outcomes for the auto-refresh hooks installed alongside the Claude Code SessionStart hook (one entry per cohort vendor with a non-null `agentHook` registry spec — Cursor, Gemini CLI, Codex CLI, VS Code + Copilot). `reason` is present only when `action: "failed"`. Empty array when `--no-session-sync` was passed or no cohort vendor was selected.
+- `sync.fullSync` is `true` for first-time syncs (no prior `.last-sync`), `false` for delta syncs, and `null` only on synthesized-failure summaries when the network call never completed (also signals via `sync.failureReason`).
+- `sync.failureReason: string` is present only when the first sync failed but the rest of init succeeded — config is still saved; user should re-run `skillrepo update`.
 
 `init` is idempotent: re-running with a valid existing config re-runs
 detection + MCP merge + first sync without re-prompting for a key. If the
@@ -77,14 +140,17 @@ fresh key without leaving the terminal.
 When stdin is not a TTY (CI, piped input), `init` skips the browser launch
 and just prints the URL — paste the key via the upstream pipe.
 
-**Headless / CI:** if you run from a directory with no IDE markers, init
-will refuse and print a copy-pasteable MCP config for manual wiring. To
-proceed anyway, pass `--ide claude` (or the target vendor).
+**Headless / non-interactive:** under `--yes` the picker is skipped and
+the pre-checked rows become the selection. With no detection signals,
+both default rows are pre-checked — running `init --yes` on a fresh
+clone configures both targets so CI bootstrap scripts always produce
+a working library. Pass `--agent <target>` (`claude`, `agents`, `none`,
+or a vendor name like `cursor`) to bypass the picker entirely.
 
 ### `update` — sync your library
 
 ```sh
-skillrepo update [--global] [--ide <list>] [--json]
+skillrepo update [--global] [--agent <list>] [--json] [--silent]
 ```
 
 Pulls the latest state of your library from the server using a delta
@@ -93,10 +159,20 @@ from the library, and skips skills that are unchanged. Uses ETag
 caching so repeat runs return `304 Not Modified` when nothing has
 changed.
 
+`--silent` suppresses normal output and writes a single `{}` line to
+stdout on success. Designed for SessionStart hooks that pipe stdout
+to their agent's session log — Gemini CLI specifically requires hook
+stdout to be valid JSON, and the empty object satisfies that without
+injecting model context. Sync progress and warnings still go to
+stderr. On failure, the command exits with the appropriate non-zero
+code and the error message goes to stderr (distinct from
+`--session-hook`, which is Claude-Code-specific and exits 0 on every
+error so a sync failure can't block a session start).
+
 ### `get` — fetch a single skill
 
 ```sh
-skillrepo get <@owner/name> [--global] [--ide <list>] [--json]
+skillrepo get <@owner/name> [--global] [--agent <list>] [--json]
 ```
 
 One-shot fetch. Does NOT mutate your library or the server — just reads
@@ -125,7 +201,7 @@ but currently a no-op — semantic search is a planned backend feature.
 ### `add` — add a skill to your library
 
 ```sh
-skillrepo add <@owner/name> [--global] [--ide <list>] [--json]
+skillrepo add <@owner/name> [--global] [--agent <list>] [--json]
 ```
 
 POSTs to `/api/v1/library`, then fetches the single skill directly and
@@ -136,7 +212,7 @@ consistent.
 ### `remove` — remove a skill from your library
 
 ```sh
-skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]
+skillrepo remove <@owner/name> [--global] [--agent <list>] [--json]
 ```
 
 DELETEs from `/api/v1/library` and deletes the local directory. Requires
@@ -154,6 +230,23 @@ Installs (or removes) a Claude Code [SessionStart hook](https://docs.claude.com/
 
 By default `skillrepo init` prompts you to install this hook. If you said no (or passed `--no-session-sync`), run `session-sync enable` later to turn it on.
 
+#### Auto-refresh hooks for other agents
+
+For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library refreshes on every session start without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
+
+| Agent | Hook config path | Notes |
+|-------|------------------|-------|
+| Cursor | `~/.cursor/hooks.json` (`sessionStart` event) | `timeout: 60` (seconds) |
+| Gemini CLI | `~/.gemini/settings.json` (`SessionStart` event) | `matcher: "*"` group filter, `timeout: 60000` (milliseconds), entry named `skillrepo-update` |
+| Codex CLI | `~/.codex/hooks.json` (`SessionStart` event) | `timeout: 60` (seconds). Codex also reads `[hooks]` from `~/.codex/config.toml`; both sources coexist — Codex merges them at runtime, so a hand-written TOML entry won't conflict with our JSON. |
+| VS Code + Copilot | `~/.copilot/hooks/skillrepo-update.json` (`sessionStart` event) | `timeout: 60` (seconds). **Preview status**: GitHub currently labels Copilot's hook system as Preview; the schema may shift before GA. |
+
+`skillrepo init` writes these alongside the Claude Code hook for every selected vendor that publishes a SessionStart-equivalent event. `--no-session-sync` skips ALL of them. `skillrepo uninstall --global` removes them surgically — other tools' entries (1Password, Snyk, your own scripts) in those config files are preserved.
+
+**Cloud-agent runners** (e.g. GitHub Codespaces, Copilot's cloud agent) read only the committed default-branch content. Because skills sync to a per-developer, gitignored cache, those runners do not see the local skill library — same documented limitation as `.agents/skills/` placement. The auto-refresh hooks above are per-developer; they don't run in cloud runners.
+
+Auto-refresh hooks for Windsurf and Cline are not yet supported — those agents lack a documented SessionStart-equivalent event today. Run `skillrepo update` manually in those environments.
+
 **Under `npx skillrepo init`, the CLI offers to install itself globally.** Session sync needs the binary at a stable absolute path (the `npx` cache path is transient and would break on the next cache eviction). Rather than skipping with a warning the way v3.1.1 did, v3.1.2 prompts during init: *"SkillRepo needs a global install to enable session sync. Install `skillrepo` globally now? (Y/n)"* — saying yes runs `npm install -g skillrepo@<version>` (pinned to the version you just invoked) and then installs the hook with the resulting absolute path. Under `--yes` the install runs without prompting; under `--no-session-sync` it's skipped entirely. If the install fails (permissions, network, registry), init prints actionable next-steps and continues; the rest of init still completes successfully.
 
 `skillrepo session-sync enable` does **not** auto-install — it's an explicit, deliberate command and assumes you already have a global install. If invoked under `npx` without a global install present, it returns a clear "install globally first" message rather than mutating your global package set.
@@ -194,6 +287,13 @@ With `--global`, also removes:
 - `mcpServers.skillrepo` from `~/.codeium/windsurf/mcp_config.json`
 - The `~/.claude/skills/` global skill cache
 - The `~/.claude/skillrepo/` directory (stored credentials + sync cache)
+- The SkillRepo SessionStart entry from each cohort vendor's hook config —
+  `~/.cursor/hooks.json`, `~/.gemini/settings.json`, `~/.codex/hooks.json`,
+  and `~/.copilot/hooks/skillrepo-update.json`. Other tools' entries
+  (1Password, Snyk, Apiiro, the user's own hooks) and unrelated top-level
+  keys (theme, mcpServers, etc.) are preserved — only our entry, identified
+  by the canonical command `npx --yes skillrepo update --silent`, is
+  filtered out.
 
 Flags:
 
@@ -275,11 +375,20 @@ Two scenarios worth calling out:
 
 ### Skill placement
 
-By default, skills land at `.claude/skills/<name>/` (project-scoped). Pass
-`--global` to target `~/.claude/skills/<name>/` instead. When the CLI
-detects an IDE that has no documented skills convention (Cursor, Windsurf,
-VS Code), it falls back to project `/skills/<name>/` and adds `/skills/`
-to your `.gitignore` on first write.
+Skills land at one of two project paths, depending on the agent:
+
+| Agent | Project path | Personal (`--global`) path |
+|---|---|---|
+| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
+| Cursor / Windsurf / Gemini CLI / Codex CLI / Cline / GitHub Copilot | `.agents/skills/<name>/` | `~/.agents/skills/<name>/` |
+| Windsurf (personal-scope override) | — | `~/.codeium/windsurf/skills/<name>/` |
+
+The CLI auto-adds `.claude/skills/` and `.agents/skills/` to your project
+`.gitignore` on first write — skills are a per-developer cache, not
+committed content. The `--agent` flag overrides detection (e.g.
+`--agent claude,agents` writes both paths). See
+[`docs/vendor-paths.md`](docs/vendor-paths.md) for primary-source
+citations on each agent's read paths.
 
 ## Exit codes
 
@@ -342,11 +451,12 @@ path — both the interactive prompt in `init` and the Bearer header
 used by every subsequent command — so pasting from email or a
 browser with a trailing newline is safe.
 
-**"No IDEs detected in this directory"** — The CLI detected no
-`.claude/`, `.cursor/`, `.vscode/`, or `~/.codeium/windsurf/` markers.
-Either run from inside a project with one of those folders, pass
-`--ide <vendor>` to target a specific IDE, or copy the printed MCP
-config manually.
+**Picker selected nothing under `--yes`** — Phase 3 (#1236) replaced
+the old "no agents detected → refuse" branch with a friendlier
+default: when no detection signals fire, both default rows are
+pre-checked, so `--yes` configures both targets. If you want to skip
+placement entirely under `--yes`, pass `--agent none` (config and
+gitignore still happen; only the skill files are skipped).
 
 **"Rate limit exceeded — retried automatically and still getting
 429"** — The CLI already retried with backoff. Wait a minute and

package/bin/skillrepo.mjs

@@ -44,27 +44,27 @@ import { CliError, EXIT_OK, EXIT_VALIDATION } from "../src/lib/errors.mjs";
 const COMMANDS = {
   init: {
     description: "Validate access key, configure detected IDEs, and run first sync",
-    usage: "skillrepo init [--key <key>] [--url <url>] [--yes]",
+    usage: "skillrepo init [--key <key>] [--url <url>] [--yes] [--agent <list>] [--global] [--force] [--no-session-sync] [--json]",
     run: async (argv) => runInit(argv),
   },
   update: {
     description: "Sync your library against the registry (delta + tombstones)",
-    usage: "skillrepo update [--global] [--ide <list>] [--json]",
+    usage: "skillrepo update [--global] [--agent <list>] [--json]",
     run: async (argv) => runUpdate(argv),
   },
   get: {
     description: "Fetch a single skill and write it to disk (no library mutation)",
-    usage: "skillrepo get <@owner/name> [--global] [--ide <list>] [--json]",
+    usage: "skillrepo get <@owner/name> [--global] [--agent <list>] [--json]",
     run: async (argv) => runGet(argv),
   },
   add: {
     description: "Add a skill to your library and pull it locally",
-    usage: "skillrepo add <@owner/name> [--global] [--ide <list>] [--json]",
+    usage: "skillrepo add <@owner/name> [--global] [--agent <list>] [--json]",
     run: async (argv) => runAdd(argv),
   },
   remove: {
     description: "Remove a skill from your library and delete it locally",
-    usage: "skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]",
+    usage: "skillrepo remove <@owner/name> [--global] [--agent <list>] [--json]",
     run: async (argv) => runRemove(argv),
   },
   list: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/add.mjs

@@ -30,13 +30,22 @@
  *   - 403 plan-limit → validationError (via http.mjs) with billing hint
  *   - 403 scope → scopeError (via http.mjs) with write-key hint
  *
- * Flags: --global / --ide / --json / --key / --url
+ * Flags: --global / --agent / --json / --key / --url
  * Positional: <@owner/name>
  */
 
 import { addSkillToLibrary, getSkill } from "../lib/http.mjs";
-import { writeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  writeSkillDir,
+  cleanupOrphans,
+  placementTargetsFor,
+  describePlacementTarget,
+} from "../lib/file-write.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -73,6 +82,11 @@ export async function runAdd(argv, io = {}) {
 
   const { owner, name } = parseIdentifier(identifier);
   const vendors = effectiveVendors(flags);
+  // `add` writes specific files to disk — `--agent none` would make
+  // the command a documented no-op, which is never a useful intent.
+  // Reject early with an actionable hint pointing at the meaningful
+  // targets.
+  requireVendorTargets(vendors, "add");
 
   // Pre-flight: clean orphans from prior crashes (same pattern as get.mjs)
   cleanupOrphans({ vendors, global: flags.global });
@@ -161,9 +175,10 @@ export async function runAdd(argv, io = {}) {
     return;
   }
 
-  const where = flags.global
-    ? "personal (~/.claude/skills/)"
-    : "project (.claude/skills/)";
+  const targets = placementTargetsFor({ vendors, global: flags.global });
+  const where = `${flags.global ? "personal" : "project"} (${targets
+    .map(describePlacementTarget)
+    .join(", ")})`;
   if (wasNewlyAdded) {
     stdout.write(
       `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} files) → ${where}\n\n`,

package/src/commands/get.mjs

@@ -9,7 +9,7 @@
  *
  * Flags (via resolveFlags):
  *   --global         Write to ~/.claude/skills/ instead of project-local
- *   --ide <list>     Comma-separated vendor list
+ *   --agent <list>   Comma-separated agent target list
  *   --key/--url      Override credentials
  *
  * Positional:
@@ -25,8 +25,17 @@
  */
 
 import { getSkill } from "../lib/http.mjs";
-import { writeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  writeSkillDir,
+  cleanupOrphans,
+  placementTargetsFor,
+  describePlacementTarget,
+} from "../lib/file-write.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -64,6 +73,10 @@ export async function runGet(argv, io = {}) {
 
   const { owner, name } = parseIdentifier(identifier);
   const vendors = effectiveVendors(flags);
+  // `get` writes a specific skill to disk — `--agent none` would
+  // make the command a no-op, which is never a useful intent. Reject
+  // early.
+  requireVendorTargets(vendors, "get");
 
   // Pre-flight: clean orphans from prior crashes before any new write
   cleanupOrphans({ vendors, global: flags.global });
@@ -109,7 +122,10 @@ export async function runGet(argv, io = {}) {
     return;
   }
 
-  const where = flags.global ? "personal (~/.claude/skills/)" : "project (.claude/skills/)";
+  const targets = placementTargetsFor({ vendors, global: flags.global });
+  const where = `${flags.global ? "personal" : "project"} (${targets
+    .map(describePlacementTarget)
+    .join(", ")})`;
   stdout.write(
     `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} files) → ${where}\n\n`,
   );

package/src/commands/init-cohort-hooks.mjs

@@ -0,0 +1,127 @@
+/**
+ * `skillrepo init` step-6 sibling for cohort SessionStart hooks (#1240).
+ *
+ * Runs ALONGSIDE `installSessionSyncHook` (the legacy Claude-Code-only
+ * installer). Where the Claude installer has to resolve a stable
+ * absolute `binaryPath` for the hook command — three branches
+ * (non-npx, existing global, auto-install) — the cohort installer has
+ * no such concern: every cohort hook is `npx --yes skillrepo update
+ * --silent`, which works on any host without a global install.
+ *
+ * That's why this is a sibling step, not an extension of
+ * `installSessionSyncHook`. The two flows share almost no logic. The
+ * architect review on #1240 specifically called out conflating them
+ * as a structural mistake — `installSessionSyncHook` is named for
+ * Claude Code's hook mechanism, and folding cohort logic into it
+ * would create a function with four irreducible branches by Phase 4
+ * (#1241-#1244).
+ *
+ * ## Decision tree
+ *
+ *   noSessionSync                  → skip all cohort hooks (mirrors
+ *                                    Claude path's --no-session-sync
+ *                                    semantics)
+ *   no cohort vendors selected    → no-op (nothing to install)
+ *   cohort vendors selected       → install hooks for each one;
+ *                                    per-vendor failures don't abort
+ *                                    siblings
+ *
+ * ## Return shape
+ *
+ *   { hooks: AgentHookInstallResult[] }
+ *
+ * Each entry: `{ vendorKey, displayName, path, action, reason? }`. The
+ * caller (init.mjs) merges these into the `sessionSync.cohortHooks`
+ * field of the JSON summary.
+ */
+
+import { installAgentHooksForVendors } from "../lib/agent-hook-merge.mjs";
+import { getAgentByKey } from "../lib/agent-registry.mjs";
+
+/**
+ * @typedef {Object} CohortHookOptions
+ * @property {boolean} noSessionSync - True if `--no-session-sync` was
+ *           passed. The flag covers BOTH the Claude session hook and
+ *           the cohort hooks — semantically "skip all auto-refresh
+ *           hooks." Pre-#1240 this was a Claude-only flag; the
+ *           framing widened with the cohort feature.
+ * @property {string[]} vendors - Canonical vendor keys the user
+ *           selected (via `--agent` or the picker). Vendors without
+ *           an `agentHook` spec are silently skipped by the
+ *           dispatcher; truly unknown keys surface as failures.
+ * @property {object} p - Init's printer (from `init.mjs:makePrinter`).
+ *           Silenced under `--json`; otherwise renders one line per
+ *           cohort hook installed/updated/failed.
+ */
+
+/**
+ * Run the cohort sibling step. Always returns a result; never throws
+ * on user-recoverable failures (per-vendor errors are captured in
+ * each result entry).
+ *
+ * @param {CohortHookOptions} options
+ * @returns {{ hooks: import("../lib/agent-hook-merge.mjs").AgentHookInstallResult[] }}
+ */
+export function installCohortHooks({ noSessionSync, vendors, p }) {
+  if (noSessionSync) {
+    // Match the Claude path's --no-session-sync semantics: silent
+    // skip. The Claude path already prints the warning, so we don't
+    // double-warn here. If somehow the user passes --no-session-sync
+    // AND no Claude target (so the Claude path doesn't print), the
+    // user got exactly what they asked for — explicit opt-out.
+    return { hooks: [] };
+  }
+
+  // Filter vendors to those with an agentHook spec. The dispatcher
+  // does this filtering internally too (silently skipping unknown
+  // entries), but doing it here lets us avoid the noise of "Skipped
+  // claudeCode (no agentHook)" lines for every vendor in the cohort
+  // list that isn't ours to install. Claude Code, Windsurf, and
+  // Cline all hit this filter; only the four cohort vendors with
+  // `agentHook != null` reach the dispatcher.
+  const eligible = vendors.filter((v) => {
+    const entry = getAgentByKey(v);
+    return entry && entry.agentHook !== null;
+  });
+
+  if (eligible.length === 0) {
+    return { hooks: [] };
+  }
+
+  const results = installAgentHooksForVendors({ vendors: eligible });
+
+  // Surface each result on the printer so the user sees what was
+  // written / refreshed / failed. Mirrors `installSessionSyncHook`'s
+  // per-action printing for Claude.
+  for (const r of results) {
+    if (r.action === "installed") {
+      p.success(`Cohort SessionStart hook installed for ${r.displayName} (${r.path})`);
+    } else if (r.action === "updated") {
+      p.success(`Cohort SessionStart hook updated for ${r.displayName} (${r.path})`);
+    } else if (r.action === "unchanged") {
+      p.success(`Cohort SessionStart hook already installed for ${r.displayName} (${r.path})`);
+    } else if (r.action === "failed") {
+      p.warning(
+        `Cohort SessionStart hook for ${r.displayName} failed: ${r.reason}. ` +
+          `Run \`skillrepo init\` again after fixing the issue.`,
+      );
+    }
+  }
+
+  // VS Code + Copilot's hook system is currently labelled Preview by
+  // GitHub (#1244). Surface that caveat once if Copilot was among the
+  // installed vendors so users know the hook schema may shift before
+  // GA. Skip the warning if Copilot's install actually failed — we
+  // already printed the failure line above and a Preview note would
+  // muddle the actionable signal.
+  const copilotResult = results.find((r) => r.vendorKey === "copilot");
+  if (copilotResult && copilotResult.action !== "failed") {
+    p.warning(
+      "Copilot's SessionStart hook system is currently labelled Preview by GitHub. " +
+        "The schema may shift before GA; re-run `skillrepo init` after upgrading the CLI " +
+        "if Copilot's hook config format changes.",
+    );
+  }
+
+  return { hooks: results };
+}

package/src/commands/init-session-sync.mjs

@@ -73,7 +73,7 @@ import { SessionSyncAction, isHookActive } from "./session-sync-actions.mjs";
  * @typedef {Object} SessionSyncOptions
  * @property {boolean} noSessionSync - True if `--no-session-sync`.
  * @property {boolean} claudeTargeted - True if Claude Code is in the
- *           vendor target list (via `--ide claude` or `--global` or
+ *           vendor target list (via `--agent claude` or `--global` or
  *           auto-detection).
  * @property {boolean} yes - True if `--yes`.
  * @property {boolean} json - True if `--json`. Affects spawn output