skillrepo 3.2.0 → 4.0.0

package/src/lib/file-write.mjs

@@ -33,11 +33,14 @@
  *       - Blocked extensions — rejected (matches server BLOCKED_EXTENSIONS)
  *       - Skill name vs frontmatter `name` — must match
  *
- *   • Vendor placement: Claude Code uses .claude/skills/<name>/ (project)
- *     or ~/.claude/skills/<name>/ (--global) per Anthropic's documented
- *     convention. Other detected vendors without their own convention
- *     fall back to <cwd>/skills/<name>/, with /skills/ added to .gitignore
- *     on first creation. See follow-up #876.
+ *   • Vendor placement: per-vendor decisions live in `agent-registry.mjs`.
+ *     Claude Code writes to .claude/skills/<name>/ (Anthropic's documented
+ *     convention); the cohort of cursor / windsurf / gemini / codex / cline
+ *     / copilot shares .agents/skills/<name>/ for project scope (with
+ *     `.agents/skills/` added to .gitignore on first cohort write). Personal
+ *     scope honors per-vendor conventions where they exist (Windsurf has its
+ *     own personal path under ~/.codeium/windsurf/skills/). See
+ *     `packages/cli/docs/vendor-paths.md` for the full citation list.
  */
 
 import {
@@ -55,12 +58,17 @@ import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
   claudeSkillsProject,
   claudeSkillsGlobal,
-  projectSkillsFallback,
-  projectSkillsFallbackRoot,
   claudeSkillsProjectRoot,
   claudeSkillsGlobalRoot,
+  agentsSkillsProject,
+  agentsSkillsProjectRoot,
+  agentsSkillsGlobal,
+  agentsSkillsGlobalRoot,
+  windsurfSkillsGlobal,
+  windsurfSkillsGlobalRoot,
   gitignorePath,
 } from "./paths.mjs";
+import { AGENT_REGISTRY, getAgentByKey } from "./agent-registry.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
 import { platformConventions } from "./platform.mjs";
 
@@ -83,7 +91,7 @@ export const BLOCKED_EXTENSIONS = new Set([
   ".wasm",
 ]);
 
-const GITIGNORE_SKILLS_LINE = "/skills/";
+const GITIGNORE_AGENTS_SKILLS_LINE = ".agents/skills/";
 const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
 
 // ── Types (JSDoc only — this is plain JS) ───────────────────────────────
@@ -102,9 +110,25 @@ const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
  */
 
 /**
- * @typedef {"claudeProject" | "claudeGlobal" | "projectFallback"} PlacementTarget
+ * @typedef {"claudeProject" | "claudeGlobal" | "agentsProject" | "agentsGlobal" | "windsurfGlobal"} PlacementTarget
  */
 
+/** @type {readonly PlacementTarget[]} */
+const ALL_TARGETS = Object.freeze([
+  "claudeProject",
+  "claudeGlobal",
+  "agentsProject",
+  "agentsGlobal",
+  "windsurfGlobal",
+]);
+
+/** @type {readonly PlacementTarget[]} */
+const GLOBAL_TARGETS = Object.freeze([
+  "claudeGlobal",
+  "agentsGlobal",
+  "windsurfGlobal",
+]);
+
 // ── Public API ──────────────────────────────────────────────────────────
 
 /**
@@ -165,8 +189,64 @@ export function resolvePlacementDir(target, skillName) {
       return claudeSkillsProject(skillName);
     case "claudeGlobal":
       return claudeSkillsGlobal(skillName);
-    case "projectFallback":
-      return projectSkillsFallback(skillName);
+    case "agentsProject":
+      return agentsSkillsProject(skillName);
+    case "agentsGlobal":
+      return agentsSkillsGlobal(skillName);
+    case "windsurfGlobal":
+      return windsurfSkillsGlobal(skillName);
+    default: {
+      throw validationError(`Unknown placement target: ${target}`);
+    }
+  }
+}
+
+/**
+ * Human-readable path label for a placement target. Used in success
+ * messages so the user sees where files actually landed (`.agents/skills/`
+ * for cohort vendors, not the misleading `.claude/skills/` previously
+ * hardcoded in add/get).
+ *
+ * @param {PlacementTarget} target
+ * @returns {string}
+ */
+export function describePlacementTarget(target) {
+  switch (target) {
+    case "claudeProject":
+      return ".claude/skills/";
+    case "claudeGlobal":
+      return "~/.claude/skills/";
+    case "agentsProject":
+      return ".agents/skills/";
+    case "agentsGlobal":
+      return "~/.agents/skills/";
+    case "windsurfGlobal":
+      return "~/.codeium/windsurf/skills/";
+    default:
+      return target;
+  }
+}
+
+/**
+ * Map a `PlacementTarget` to its parent root resolver. Used by
+ * `cleanupOrphans` to know which directories to scan for `.tmp`/`.old`
+ * siblings.
+ *
+ * @param {PlacementTarget} target
+ * @returns {() => string}
+ */
+function placementRootFn(target) {
+  switch (target) {
+    case "claudeProject":
+      return claudeSkillsProjectRoot;
+    case "claudeGlobal":
+      return claudeSkillsGlobalRoot;
+    case "agentsProject":
+      return agentsSkillsProjectRoot;
+    case "agentsGlobal":
+      return agentsSkillsGlobalRoot;
+    case "windsurfGlobal":
+      return windsurfSkillsGlobalRoot;
     default: {
       throw validationError(`Unknown placement target: ${target}`);
     }
@@ -174,46 +254,52 @@ export function resolvePlacementDir(target, skillName) {
 }
 
 /**
- * Compute the placement targets for a write based on detected/requested
- * vendors and the --global flag.
+ * Compute the placement targets for a write based on requested vendors
+ * and the --global flag.
  *
- * Rules:
- *   - --global → only ["claudeGlobal"] (other vendors don't have a
- *     documented global convention; we don't synthesize one)
- *   - claudeCode in vendors → "claudeProject"
- *   - any non-claudeCode vendor in vendors (cursor, windsurf, vscode)
- *     → "projectFallback" (single fallback, deduped — multiple
- *     non-claude vendors share the same fallback)
+ * Each vendor's `projectTarget` and `globalTarget` come from
+ * `agent-registry.mjs`. Multiple vendors mapping to the same target
+ * (e.g. cursor + windsurf both at `agentsProject`) collapse into one
+ * write. A vendor with `globalTarget === null` is rejected under
+ * `--global` because the vendor has no documented personal scope.
  *
  * @param {object} options
- * @param {string[]} options.vendors - List of vendor keys (claudeCode, cursor, windsurf, vscode).
- * @param {boolean} [options.global] - If true, write to personal/global Claude Code dir only.
+ * @param {string[]} options.vendors - List of canonical vendor keys.
+ * @param {boolean} [options.global] - If true, use each vendor's globalTarget.
  * @returns {PlacementTarget[]}
  */
 export function placementTargetsFor({ vendors, global = false }) {
-  if (global) {
-    return ["claudeGlobal"];
-  }
-
   if (!Array.isArray(vendors) || vendors.length === 0) {
     throw validationError(
-      "No vendors specified. Pass --ide claude (or another vendor) explicitly.",
+      "No vendors specified. Pass --agent claude (or another target) explicitly.",
     );
   }
 
   const targets = [];
-  let needsFallback = false;
   for (const vendor of vendors) {
-    if (vendor === "claudeCode") {
-      targets.push("claudeProject");
-    } else if (vendor === "cursor" || vendor === "windsurf" || vendor === "vscode") {
-      needsFallback = true;
-    } else {
-      throw validationError(`Unknown vendor: ${vendor}`);
+    const entry = getAgentByKey(vendor);
+    if (!entry) {
+      throw validationError(`Unknown vendor: ${vendor}`, {
+        hint: `Valid keys: ${AGENT_REGISTRY.map((e) => e.key).join(", ")}.`,
+      });
+    }
+    const target = global ? entry.globalTarget : entry.projectTarget;
+    if (target === null) {
+      const supported = AGENT_REGISTRY
+        .filter((e) => e.globalTarget !== null)
+        .map((e) => e.key)
+        .join(", ");
+      throw validationError(
+        `${vendor} has no documented personal scope, so --global is not supported.`,
+        {
+          hint:
+            `Drop --global, or use --agent with a vendor that supports it (${supported}).`,
+        },
+      );
+    }
+    if (!targets.includes(target)) {
+      targets.push(target);
     }
-  }
-  if (needsFallback) {
-    targets.push("projectFallback");
   }
   return targets;
 }
@@ -264,7 +350,7 @@ export function readFrontmatterName(files) {
  * skip-if-unchanged enhancement at this layer would duplicate that work
  * and require re-reading every file from disk.
  *
- * Pre-flight: `.gitignore` setup for the projectFallback target runs
+ * Pre-flight: `.gitignore` setup for the agentsProject target runs
  * BEFORE any per-target write. This is intentional — running it inline
  * inside the loop would let a read-only `.gitignore` failure abort the
  * loop AFTER an earlier vendor (e.g., claudeCode) had already
@@ -277,14 +363,15 @@ export function writeSkillDir(skill, options = {}) {
 
   const targets = placementTargetsFor(options);
 
-  // Pre-flight: if any target requires the project /skills/ fallback,
-  // ensure .gitignore is set up before starting any writes. A failure
-  // here is recoverable (user fixes their .gitignore and re-runs)
-  // because nothing has hit disk yet. A failure here AFTER a successful
-  // claudeProject write would leave the user with a half-applied state
-  // and an error message that doesn't reflect what's actually on disk.
-  if (targets.includes("projectFallback")) {
-    ensureFallbackGitignore();
+  // Pre-flight: if any target writes to .agents/skills/, ensure
+  // .gitignore is set up before starting any writes. A failure here
+  // is recoverable (user fixes their .gitignore and re-runs) because
+  // nothing has hit disk yet. A failure here AFTER a successful
+  // claudeProject write would leave the user with a half-applied
+  // state and an error message that doesn't reflect what's actually
+  // on disk.
+  if (targets.includes("agentsProject")) {
+    ensureAgentsGitignore();
   }
 
   const written = [];
@@ -377,26 +464,26 @@ export function removeSkillDir(skillName, options = {}) {
  * @returns {{ cleaned: string[] }}
  */
 export function cleanupOrphans(options = {}) {
-  const roots = [];
-  if (options.global) {
-    roots.push(claudeSkillsGlobalRoot());
+  const roots = new Set();
+  if (Array.isArray(options.vendors) && options.vendors.length > 0) {
+    const targets = placementTargetsFor({
+      vendors: options.vendors,
+      global: !!options.global,
+    });
+    for (const target of targets) {
+      roots.add(placementRootFn(target)());
+    }
+  } else if (options.global) {
+    // No vendors under --global — sweep every known global root so a
+    // stale orphan from any prior --global write is cleaned.
+    for (const target of GLOBAL_TARGETS) {
+      roots.add(placementRootFn(target)());
+    }
   } else {
-    if (Array.isArray(options.vendors) && options.vendors.length > 0) {
-      if (options.vendors.includes("claudeCode")) {
-        roots.push(claudeSkillsProjectRoot());
-      }
-      if (
-        options.vendors.includes("cursor") ||
-        options.vendors.includes("windsurf") ||
-        options.vendors.includes("vscode")
-      ) {
-        roots.push(projectSkillsFallbackRoot());
-      }
-    } else {
-      // No vendors specified — clean everything we know about.
-      roots.push(claudeSkillsProjectRoot());
-      roots.push(projectSkillsFallbackRoot());
-      roots.push(claudeSkillsGlobalRoot());
+    // No vendors and no --global — sweep every root we know about so
+    // any orphan from any prior run is cleaned.
+    for (const target of ALL_TARGETS) {
+      roots.add(placementRootFn(target)());
     }
   }
 
@@ -666,17 +753,14 @@ function writeSkillToDir(skill, targetDir) {
 }
 
 /**
- * Ensure the project /skills/ directory is gitignored. Idempotent —
- * skips if the entry is already present. Creates .gitignore if missing.
+ * Ensure `.agents/skills/` is gitignored. Idempotent — skips if the
+ * entry is already present. Creates .gitignore if missing.
  *
  * Throws diskError on any write failure so a read-only or symlinked
  * .gitignore surfaces as a user-visible error instead of silent data
- * loss. This is the explicit fix for the architect's PR1 review item:
- * `writeFileSafe` was previously called without a try/catch and a
- * failing write would leave the user with skills on disk but no
- * .gitignore protection — the next `git add` would commit them.
+ * loss.
  */
-function ensureFallbackGitignore() {
+function ensureAgentsGitignore() {
   const filePath = gitignorePath();
   let existing = null;
   try {
@@ -684,18 +768,19 @@ function ensureFallbackGitignore() {
   } catch (err) {
     throw diskError(`Cannot read ${filePath}: ${err.message}`, {
       cause: err,
-      hint: "Update your .gitignore manually to add /skills/ before re-running.",
+      hint:
+        `Update your .gitignore manually to add ${GITIGNORE_AGENTS_SKILLS_LINE} before re-running.`,
     });
   }
 
-  if (existing !== null && existing.includes(GITIGNORE_SKILLS_LINE)) {
+  if (existing !== null && existing.includes(GITIGNORE_AGENTS_SKILLS_LINE)) {
     return; // Already present — no-op
   }
 
   const newContent =
     existing === null
-      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`
-      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`;
+      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`
+      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`;
 
   try {
     writeFileSafe(filePath, newContent);
@@ -703,7 +788,7 @@ function ensureFallbackGitignore() {
     throw diskError(`Cannot update ${filePath}: ${err.message}`, {
       cause: err,
       hint:
-        "The CLI needs to add /skills/ to .gitignore so library skills don't get committed. " +
+        `The CLI needs to add ${GITIGNORE_AGENTS_SKILLS_LINE} to .gitignore so library skills don't get committed. ` +
         "Update .gitignore manually and re-run, or remove the read-only/symlinked constraint.",
     });
   }

package/src/lib/mcp-merge.mjs

@@ -46,6 +46,7 @@ import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
 import { mergeVscodeMcpConfig } from "./mergers/vscode-mcp.mjs";
 import { confirm as realConfirm } from "./prompt.mjs";
 import { validationError } from "./errors.mjs";
+import { getAgentByKey } from "./agent-registry.mjs";
 
 /**
  * @typedef {Object} McpMergeResult
@@ -69,7 +70,7 @@ import { validationError } from "./errors.mjs";
  * user for each one unless `yes` is true.
  *
  * @param {object} options
- * @param {string[]} options.vendors - Vendor keys: claudeCode | cursor | windsurf | vscode
+ * @param {string[]} options.vendors - Canonical vendor keys (see agent-registry.mjs).
  * @param {string} options.mcpUrl - The SkillRepo MCP endpoint URL
  * @param {boolean} [options.yes] - Skip prompts (auto-accept everything)
  * @param {object} [options.io] - Injected streams for testability
@@ -111,18 +112,26 @@ export async function mergeMcpForVendors(options) {
   }
 
   // Deduplicate vendors so a caller passing `["claudeCode",
-  // "claudeCode"]` doesn't run the merger twice. The round-1 review
-  // flagged this as a latent caller trap — `cli-config.mjs`'s
-  // parseVendorList doesn't dedupe either, so `--ide claude,claude`
-  // would reach this loop twice for the same vendor. Idempotent on
-  // a single vendor key (Set preserves first-seen insertion order).
+  // "claudeCode"]` doesn't run the merger twice. Defense-in-depth —
+  // `cli-config.mjs`'s `parseAgentList` already dedupes, but a future
+  // caller building the vendor list manually could reintroduce the
+  // duplicate. Idempotent on a single vendor key (Set preserves
+  // first-seen insertion order).
   const uniqueVendors = Array.from(new Set(vendors));
 
   const results = [];
   for (const vendor of uniqueVendors) {
+    const entry = getAgentByKey(vendor);
+    // Vendors with `hasMcp: false` are file-only (no documented MCP
+    // config the CLI knows how to merge). Skipping silently is correct
+    // — they're a deliberate registry classification, not user error.
+    // A truly unknown vendor (no registry entry at all) is a caller
+    // bug; surface that as a "failed" result so it can't hide.
+    if (entry && entry.hasMcp === false) {
+      continue;
+    }
     const vendorInfo = VENDOR_INFO[vendor];
     if (!vendorInfo) {
-      // Unknown vendor — skip with a recorded failure
       results.push({
         vendor,
         path: "(unknown)",
@@ -183,34 +192,6 @@ export async function mergeMcpForVendors(options) {
   return results;
 }
 
-/**
- * Print MCP config JSON for undetected IDEs so the user can paste
- * it into their own IDE's MCP settings manually. Called by init
- * when no IDEs were detected or when the user wants to see the
- * raw config shape.
- *
- * @param {string} mcpUrl
- * @param {object} [io]
- * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
- */
-export function printManualMcpInstructions(mcpUrl, io = {}) {
-  const stdout = io.stdout ?? process.stdout;
-  const config = {
-    mcpServers: {
-      skillrepo: {
-        type: "http",
-        url: mcpUrl,
-        headers: {
-          Authorization: "Bearer ${SKILLREPO_ACCESS_KEY}",
-        },
-      },
-    },
-  };
-  stdout.write("\n  To configure MCP manually, add this to your IDE's MCP settings:\n\n");
-  stdout.write(JSON.stringify(config, null, 2).replace(/^/gm, "    ") + "\n\n");
-  stdout.write("  The SKILLREPO_ACCESS_KEY env var is set in .env.local.\n\n");
-}
-
 // ── Internals ──────────────────────────────────────────────────────────
 
 /**
@@ -233,7 +214,7 @@ const VENDOR_INFO = {
     pathFn: windsurfMcpJson,
     displayPath: "~/.codeium/windsurf/mcp_config.json",
   },
-  vscode: {
+  copilot: {
     merger: mergeVscodeMcpConfig,
     pathFn: vscodeMcpJson,
     displayPath: ".vscode/mcp.json",

package/src/lib/mergers/gitignore.mjs

@@ -1,22 +1,14 @@
 /**
- * Merger for .gitignore — adds the three paths `skillrepo init` writes
- * that must not be committed.
- *
- * This module is v3.0.0-rewritten. The v2.0.0 version added a single
- * `.claude/rules/skillrepo-*.md` pattern for the now-deleted rules
- * delivery flow. The hooks were removed in #835 and the rules-delivery
- * model was replaced with direct skill syncing to `.claude/skills/`.
- * The three paths this merger adds are:
+ * Merger for .gitignore — adds the paths `skillrepo init` writes that
+ * must not be committed.
  *
+ * Always added:
  *   - `.env.local` — contains SKILLREPO_ACCESS_KEY, a live credential
- *   - `.claude/skills/` — per-developer synced library content
  *   - `.claude/settings.local.json` — Claude Code per-user settings
  *
- * The `.env.local` entry is the security-critical one: without it, a
- * developer running `skillrepo init` in a fresh project could commit
- * their access key on the next `git add .`. PR4 round-3 review caught
- * that the docs promised this behavior but the CLI never actually
- * wrote the entries — this merger closes the gap.
+ * Conditionally added based on the `vendors` option:
+ *   - `.claude/skills/` — when any vendor maps to `claudeProject`
+ *   - `.agents/skills/` — when any vendor maps to `agentsProject`
  *
  * Idempotent: entries already present are skipped. A single call
  * either adds all missing entries in one grouped section or exits
@@ -24,35 +16,70 @@
  */
 
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { join } from "node:path";
+import { gitignorePath } from "../paths.mjs";
+import { placementTargetsFor } from "../file-write.mjs";
 
 const SECTION_HEADER = "# SkillRepo CLI (added by `skillrepo init`)";
-const REQUIRED_ENTRIES = [
+const ALWAYS_ENTRIES = Object.freeze([
   ".env.local",
-  ".claude/skills/",
   ".claude/settings.local.json",
-];
+]);
+
+/**
+ * Compute the gitignore entries to ensure based on the placement
+ * targets the caller will write to. When no vendors are passed, fall
+ * back to the historical default of `.claude/skills/` so existing
+ * call sites that haven't been threaded through `vendors` keep
+ * working.
+ *
+ * @param {{ vendors?: string[], global?: boolean }} options
+ * @returns {string[]}
+ */
+function entriesFor(options) {
+  const entries = [...ALWAYS_ENTRIES];
+  if (!Array.isArray(options.vendors) || options.vendors.length === 0) {
+    entries.push(".claude/skills/");
+    return entries;
+  }
+  let targets;
+  try {
+    targets = placementTargetsFor({
+      vendors: options.vendors,
+      global: !!options.global,
+    });
+  } catch {
+    // Caller passed an unknown vendor; fall back to the always-set
+    // entries plus `.claude/skills/` so we never under-protect.
+    entries.push(".claude/skills/");
+    return entries;
+  }
+  if (targets.includes("claudeProject")) entries.push(".claude/skills/");
+  if (targets.includes("agentsProject")) entries.push(".agents/skills/");
+  return entries;
+}
 
 /**
- * Ensure the three init-required paths are in .gitignore. Creates the
- * file if it doesn't exist. Idempotent — returns `"skipped"` if every
+ * Ensure the init-required paths are in .gitignore. Creates the file
+ * if it doesn't exist. Idempotent — returns `"skipped"` if every
  * required entry is already present, `"created"` if the file didn't
  * exist, `"updated"` if it did and at least one entry was missing.
  *
+ * @param {{ vendors?: string[], global?: boolean }} [options]
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
-export function mergeGitignore() {
-  const gitignorePath = join(process.cwd(), ".gitignore");
-  const existing = readFileSafe(gitignorePath);
+export function mergeGitignore(options = {}) {
+  const requiredEntries = entriesFor(options);
+  const filePath = gitignorePath();
+  const existing = readFileSafe(filePath);
 
   if (existing === null) {
     // Fresh .gitignore — write all required entries as one section.
-    const content = renderSection(REQUIRED_ENTRIES);
-    writeFileSafe(gitignorePath, content);
+    const content = renderSection(requiredEntries);
+    writeFileSafe(filePath, content);
     return {
       path: ".gitignore",
       action: "created",
-      added: [...REQUIRED_ENTRIES],
+      added: [...requiredEntries],
     };
   }
 
@@ -60,7 +87,7 @@ export function mergeGitignore() {
   // `.env.local.backup` or a comment `# .env.local` — split on
   // newlines and trim so we match the entry literally.
   const lines = existing.split(/\r?\n/).map((l) => l.trim());
-  const missing = REQUIRED_ENTRIES.filter((entry) => !lines.includes(entry));
+  const missing = requiredEntries.filter((entry) => !lines.includes(entry));
 
   if (missing.length === 0) {
     return {
@@ -75,7 +102,7 @@ export function mergeGitignore() {
   const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
   const separator = existing.endsWith("\n") ? "" : lineEnding;
   const block = renderSection(missing, lineEnding);
-  writeFileSafe(gitignorePath, existing + separator + lineEnding + block);
+  writeFileSafe(filePath, existing + separator + lineEnding + block);
 
   return {
     path: ".gitignore",

package/src/lib/paths.mjs

@@ -28,25 +28,13 @@ export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
 
-// ── Skill placement targets (added in #646 / PR1) ─────────────────────
+// ── Skill placement targets ────────────────────────────────────────────
 //
-// Claude Code documents two skill discovery locations at
-// https://code.claude.com/docs/en/skills:
-//
-//   Personal: ~/.claude/skills/<name>/SKILL.md
-//   Project:  <cwd>/.claude/skills/<name>/SKILL.md
-//
-// The `name` segment must match the `name` field in the SKILL.md
-// frontmatter per the agentskills.io spec — the file-write pipeline
-// enforces this at write time.
-//
-// Other detected vendors (Cursor, Windsurf, VS Code Copilot) do not
-// currently document an on-disk skill discovery convention. For those
-// vendors, the file-write pipeline writes to a project-level fallback
-// at `<cwd>/skills/<name>/`, with an entry added to .gitignore on
-// first write so the user-specific skill set never leaks into the repo
-// history. See follow-up issue #876 for tracking when those IDEs
-// publish their own conventions.
+// Per-vendor placement decisions live in `agent-registry.mjs`. This
+// module exposes the path resolvers each placement target maps to;
+// `file-write.mjs` switches on the registry's PlacementTarget union to
+// pick the right resolver. See `packages/cli/docs/vendor-paths.md` for
+// the verified vendor-by-vendor reference and primary-source citations.
 
 /** Claude Code project-local skill directory for a specific skill name. */
 export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", name);
@@ -54,25 +42,39 @@ export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", na
 /** Claude Code personal/global skill directory for a specific skill name. */
 export const claudeSkillsGlobal = (name) => join(homedir(), ".claude", "skills", name);
 
-/** Project-local fallback skills root (used when --ide includes a vendor without a documented convention). */
-export const projectSkillsFallbackRoot = () => join(cwd(), "skills");
-
-/** Project-local fallback for a specific skill name. */
-export const projectSkillsFallback = (name) => join(cwd(), "skills", name);
-
 /** Parent directory of the project-local Claude Code skills (used by orphan cleanup). */
 export const claudeSkillsProjectRoot = () => join(cwd(), ".claude", "skills");
 
 /** Parent directory of the personal/global Claude Code skills (used by orphan cleanup). */
 export const claudeSkillsGlobalRoot = () => join(homedir(), ".claude", "skills");
 
+/** Cross-vendor `.agents/skills/<name>/` project-local placement (cursor, windsurf, gemini, codex, cline, copilot). */
+export const agentsSkillsProject = (name) => join(cwd(), ".agents", "skills", name);
+
+/** Parent of the project-local `.agents/skills/` cohort root (used by orphan cleanup). */
+export const agentsSkillsProjectRoot = () => join(cwd(), ".agents", "skills");
+
+/** Cross-vendor personal `.agents/skills/<name>/` placement (cursor, gemini, codex, cline). */
+export const agentsSkillsGlobal = (name) => join(homedir(), ".agents", "skills", name);
+
+/** Parent of the personal `.agents/skills/` cohort root (used by orphan cleanup). */
+export const agentsSkillsGlobalRoot = () => join(homedir(), ".agents", "skills");
+
+/** Windsurf's vendor-specific personal placement under `~/.codeium/windsurf/skills/<name>/`. */
+export const windsurfSkillsGlobal = (name) =>
+  join(homedir(), ".codeium", "windsurf", "skills", name);
+
+/** Parent of the Windsurf personal skills root (used by orphan cleanup). */
+export const windsurfSkillsGlobalRoot = () =>
+  join(homedir(), ".codeium", "windsurf", "skills");
+
 // ── Shared ────────────────────────────────────────────────────────────
 
 export const envLocal = () => join(cwd(), ".env.local");
 
 /**
  * Project .gitignore — used by the file-write pipeline to ensure the
- * project /skills/ fallback directory is gitignored on first write.
+ * `.agents/skills/` cohort directory is gitignored on first write.
  */
 export const gitignorePath = () => join(cwd(), ".gitignore");