skillrepo 3.2.0 → 4.0.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,40 @@ 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": "..." },
+  "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.
+- `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 +127,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]
 ```
 
 Pulls the latest state of your library from the server using a delta
@@ -96,7 +149,7 @@ changed.
 ### `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 +178,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 +189,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
@@ -275,11 +328,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 +404,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.0.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-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