skillrepo 2.0.0 → 3.0.0

package/src/lib/identifier.mjs

@@ -0,0 +1,153 @@
+/**
+ * Skill identifier parsing — extracts owner + name from CLI arguments.
+ *
+ * Architects's PR2 review flagged that every command (`get`, `add`,
+ * `remove`) needs to parse `@owner/name` into separate strings, and
+ * suggested a shared helper. This module is that helper.
+ *
+ * Accepted formats:
+ *   - `@owner/name` (canonical)
+ *   - `owner/name`  (without the leading `@` — convenience)
+ *
+ * Rejected:
+ *   - bare `name` (no slash)
+ *   - `@owner` (no slash)
+ *   - `owner/name/extra` (extra slash)
+ *   - empty owner or empty name
+ *   - whitespace
+ *   - any segment that fails the agentskills.io spec rules
+ *
+ * The owner segment matches the same `name` rules from the spec
+ * (lowercase alphanumeric + hyphens, no leading/trailing/consecutive
+ * hyphens, 1-100 chars). The name segment matches the spec exactly
+ * (1-64 chars). These mirror the server-side validation and prevent
+ * a malformed identifier from reaching the API.
+ *
+ * Note: the spec says skill `name` is up to 64 chars. Server-side
+ * `accounts.slug` (the owner) is up to 100 chars. We use 100 for
+ * owners and 64 for names to match each upstream constraint.
+ */
+
+import { validationError } from "./errors.mjs";
+
+const OWNER_RE = /^[a-z0-9-]+$/;
+const NAME_RE = /^[a-z0-9-]+$/;
+
+/**
+ * @typedef {Object} ParsedIdentifier
+ * @property {string} owner
+ * @property {string} name
+ */
+
+/**
+ * Parse a CLI identifier into { owner, name }.
+ *
+ * Throws `validationError` (exit 5) on any malformed input with a
+ * specific message pointing at the failing rule. The error hint
+ * points at the canonical format.
+ *
+ * @param {string} raw
+ * @returns {ParsedIdentifier}
+ */
+export function parseIdentifier(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw validationError("Skill identifier is required.", {
+      hint: "Pass an identifier like @owner/name or owner/name.",
+    });
+  }
+
+  const trimmed = raw.trim();
+
+  // Strip optional leading `@`
+  const stripped = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+
+  const slashCount = (stripped.match(/\//g) || []).length;
+  if (slashCount === 0) {
+    throw validationError(
+      `Invalid identifier "${raw}": missing owner.`,
+      { hint: "Use @owner/name format." },
+    );
+  }
+  if (slashCount > 1) {
+    throw validationError(
+      `Invalid identifier "${raw}": too many segments.`,
+      { hint: "Use @owner/name format with exactly one slash." },
+    );
+  }
+
+  const [owner, name] = stripped.split("/");
+
+  if (owner === "") {
+    throw validationError(
+      `Invalid identifier "${raw}": empty owner.`,
+      { hint: "Use @owner/name format." },
+    );
+  }
+  if (name === "") {
+    throw validationError(
+      `Invalid identifier "${raw}": empty name.`,
+      { hint: "Use @owner/name format." },
+    );
+  }
+
+  validateOwner(owner, raw);
+  validateName(name, raw);
+
+  return { owner, name };
+}
+
+/**
+ * Format a `{ owner, name }` pair back into the canonical
+ * `@owner/name` string. Used by command summaries and error messages.
+ */
+export function formatIdentifier({ owner, name }) {
+  return `@${owner}/${name}`;
+}
+
+// ── Internals ───────────────────────────────────────────────────────────
+
+function validateOwner(owner, raw) {
+  if (owner.length > 100) {
+    throw validationError(
+      `Invalid identifier "${raw}": owner exceeds 100 characters.`,
+    );
+  }
+  if (!OWNER_RE.test(owner)) {
+    throw validationError(
+      `Invalid identifier "${raw}": owner "${owner}" must be lowercase alphanumeric with hyphens.`,
+    );
+  }
+  if (owner.startsWith("-") || owner.endsWith("-")) {
+    throw validationError(
+      `Invalid identifier "${raw}": owner "${owner}" must not start or end with a hyphen.`,
+    );
+  }
+  if (owner.includes("--")) {
+    throw validationError(
+      `Invalid identifier "${raw}": owner "${owner}" must not contain consecutive hyphens.`,
+    );
+  }
+}
+
+function validateName(name, raw) {
+  if (name.length > 64) {
+    throw validationError(
+      `Invalid identifier "${raw}": name exceeds 64 characters.`,
+    );
+  }
+  if (!NAME_RE.test(name)) {
+    throw validationError(
+      `Invalid identifier "${raw}": name "${name}" must be lowercase alphanumeric with hyphens.`,
+    );
+  }
+  if (name.startsWith("-") || name.endsWith("-")) {
+    throw validationError(
+      `Invalid identifier "${raw}": name "${name}" must not start or end with a hyphen.`,
+    );
+  }
+  if (name.includes("--")) {
+    throw validationError(
+      `Invalid identifier "${raw}": name "${name}" must not contain consecutive hyphens.`,
+    );
+  }
+}

package/src/lib/mcp-merge.mjs

@@ -0,0 +1,275 @@
+/**
+ * MCP auto-merge for detected IDEs (#682).
+ *
+ * Wraps the existing per-vendor MCP config mergers (claude-mcp,
+ * cursor-mcp, windsurf-mcp, vscode-mcp) with a user-visible
+ * confirmation prompt showing what will change before any file
+ * write. The underlying mergers are UNCHANGED — this module is a
+ * thin coordinator that:
+ *
+ *   1. For each detected vendor, reads the current config
+ *   2. Builds a structured preview of what the merge would do
+ *      (created | updated | skipped — no actual text diff)
+ *   3. Prompts y/n via prompt.mjs (unless --yes)
+ *   4. On yes: calls the existing merger, which writes the file
+ *   5. On no: skips this vendor and continues with the next
+ *   6. On merger error: records the failure and continues with the
+ *      next vendor — one broken IDE config doesn't abort init
+ *
+ * For undetected IDEs, the function prints the MCP config JSON
+ * blob that the user can paste into their own IDE's MCP settings,
+ * per the plan's requirement for undetected-vendor output.
+ *
+ * Architectural rationale (from the PR2 plan review):
+ *
+ *   The plan called for a "structured key-level diff". A full text
+ *   diff is noisy for JSON (indentation changes trigger spurious
+ *   deltas), so we describe the change at the key level: "Adding
+ *   mcpServers.skillrepo to .mcp.json. Existing entries preserved."
+ *
+ *   Failures are per-vendor. If writing the Claude Code config
+ *   fails, we still try Cursor, Windsurf, VS Code. The final
+ *   summary reports which vendors succeeded, which were skipped by
+ *   the user, and which errored.
+ */
+
+import { readFileSafe } from "./fs-utils.mjs";
+import {
+  claudeMcpJson,
+  cursorMcpJson,
+  windsurfMcpJson,
+  vscodeMcpJson,
+} from "./paths.mjs";
+import { mergeClaudeMcpConfig } from "./mergers/claude-mcp.mjs";
+import { mergeCursorMcpConfig } from "./mergers/cursor-mcp.mjs";
+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";
+
+/**
+ * @typedef {Object} McpMergeResult
+ * @property {string} vendor
+ * @property {string} path - User-facing path (relative for project, absolute for global)
+ * @property {"merged" | "skipped" | "failed"} outcome
+ * @property {string} [reason] - Present when outcome is "skipped" or "failed"
+ * @property {"created" | "updated" | "merged"} [action] - From the
+ *   underlying merger. NOTE: claude-mcp.mjs currently returns
+ *   `"merged"` for the "added a skillrepo entry to an existing
+ *   file" case, while cursor-mcp.mjs and friends return `"merged"`
+ *   for the inverse case. The round-1 review flagged this
+ *   inconsistency; the typedef widens the union to accept all
+ *   three values so the mcp-merge layer doesn't lie about the
+ *   underlying return. The mergers themselves will be normalized
+ *   in a future PR outside #646's scope.
+ */
+
+/**
+ * Run MCP auto-merge for every vendor in `vendors`, prompting the
+ * user for each one unless `yes` is true.
+ *
+ * @param {object} options
+ * @param {string[]} options.vendors - Vendor keys: claudeCode | cursor | windsurf | vscode
+ * @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
+ * @param {NodeJS.WritableStream} [options.io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [options.io.stderr=process.stderr]
+ * @param {(prompt: string, defaultYes?: boolean) => Promise<boolean>} [options.confirmFn]
+ *        Optional injection point for the y/n prompt. Defaults to
+ *        the real `confirm` from prompt.mjs. Tests pass a stub to
+ *        avoid spawning a readline interface. This dependency is
+ *        injected rather than monkey-patched because ESM module
+ *        exports are frozen and cannot be reassigned.
+ * @returns {Promise<McpMergeResult[]>}
+ */
+export async function mergeMcpForVendors(options) {
+  const { vendors, mcpUrl, yes = false, io = {}, confirmFn = realConfirm } = options;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+
+  if (!Array.isArray(vendors) || vendors.length === 0) {
+    return [];
+  }
+  if (typeof mcpUrl !== "string" || !mcpUrl) {
+    // Use validationError (exit 5) rather than a bare Error so the
+    // dispatcher's top-level catch maps this to the right exit
+    // code. A bare Error would fall through to exit 1 (network),
+    // which would mislead a caller that passed a broken mcpUrl.
+    throw validationError("mergeMcpForVendors: mcpUrl is required");
+  }
+
+  // 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).
+  const uniqueVendors = Array.from(new Set(vendors));
+
+  const results = [];
+  for (const vendor of uniqueVendors) {
+    const vendorInfo = VENDOR_INFO[vendor];
+    if (!vendorInfo) {
+      // Unknown vendor — skip with a recorded failure
+      results.push({
+        vendor,
+        path: "(unknown)",
+        outcome: "failed",
+        reason: `Unknown vendor: ${vendor}`,
+      });
+      continue;
+    }
+
+    const filePath = vendorInfo.pathFn();
+    const displayPath = vendorInfo.displayPath;
+    const existing = readFileSafe(filePath);
+    const preview = buildPreview(displayPath, existing);
+
+    // Print the preview
+    stdout.write(`\n  ${displayPath}: ${preview}\n`);
+
+    // Prompt (unless --yes)
+    let shouldMerge = yes;
+    if (!yes) {
+      shouldMerge = await confirmFn(`  Update ${displayPath}?`, true);
+    }
+
+    if (!shouldMerge) {
+      results.push({
+        vendor,
+        path: displayPath,
+        outcome: "skipped",
+        reason: "user declined",
+      });
+      continue;
+    }
+
+    // Call the underlying merger
+    try {
+      const mergerResult = vendorInfo.merger(mcpUrl);
+      results.push({
+        vendor,
+        path: displayPath,
+        outcome: "merged",
+        action: mergerResult.action,
+      });
+    } catch (err) {
+      // One vendor's failure does not abort the rest. Record the
+      // failure, emit a warning on the injected stderr stream, and
+      // continue. The init command's summary will list each failed
+      // vendor so the user can fix them manually.
+      stderr.write(`  ⚠ Failed to update ${displayPath}: ${err.message}\n`);
+      results.push({
+        vendor,
+        path: displayPath,
+        outcome: "failed",
+        reason: err.message,
+      });
+    }
+  }
+
+  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 ──────────────────────────────────────────────────────────
+
+/**
+ * Per-vendor metadata: the merge function, the file path resolver,
+ * and the display-path string used in prompts.
+ */
+const VENDOR_INFO = {
+  claudeCode: {
+    merger: mergeClaudeMcpConfig,
+    pathFn: claudeMcpJson,
+    displayPath: ".mcp.json",
+  },
+  cursor: {
+    merger: mergeCursorMcpConfig,
+    pathFn: cursorMcpJson,
+    displayPath: ".cursor/mcp.json",
+  },
+  windsurf: {
+    merger: mergeWindsurfMcpConfig,
+    pathFn: windsurfMcpJson,
+    displayPath: "~/.codeium/windsurf/mcp_config.json",
+  },
+  vscode: {
+    merger: mergeVscodeMcpConfig,
+    pathFn: vscodeMcpJson,
+    displayPath: ".vscode/mcp.json",
+  },
+};
+
+/**
+ * Build a user-facing preview string for the merge action. We don't
+ * compute a text diff — JSON re-serialization produces noisy diffs
+ * that the user doesn't care about. Instead, we describe the
+ * change at the key level:
+ *
+ *   - No file yet:           "Will create"
+ *   - File exists, no entry: "Will add mcpServers.skillrepo (N existing servers preserved)"
+ *   - File exists, has entry:"Will update existing mcpServers.skillrepo entry"
+ *   - File corrupt:          "Will refuse to write — invalid JSON"
+ */
+function buildPreview(displayPath, existingContent) {
+  if (existingContent === null) {
+    return "will create (file does not exist)";
+  }
+  let config;
+  try {
+    config = JSON.parse(existingContent);
+  } catch {
+    return "WARNING: existing file has invalid JSON — merge will throw";
+  }
+  if (!config || typeof config !== "object") {
+    return "WARNING: existing file is not a JSON object — merge will throw";
+  }
+  // All four vendors (claude-mcp, cursor-mcp, windsurf-mcp,
+  // vscode-mcp) use the `mcpServers` key. No vendor uses a
+  // `servers` alias. The round-1 review caught the extra
+  // `?? config.servers` fallback as dead code; removed.
+  const mcpServers = config.mcpServers ?? {};
+  const otherServers = Object.keys(mcpServers).filter((k) => k !== "skillrepo");
+  const existingEntry = mcpServers.skillrepo;
+
+  if (existingEntry) {
+    if (otherServers.length === 0) {
+      return "will update existing skillrepo entry (no other servers)";
+    }
+    return `will update existing skillrepo entry (${otherServers.length} other server${otherServers.length === 1 ? "" : "s"} preserved: ${otherServers.join(", ")})`;
+  }
+
+  if (otherServers.length === 0) {
+    return "will add skillrepo entry to empty mcpServers";
+  }
+  return `will add skillrepo entry (${otherServers.length} existing server${otherServers.length === 1 ? "" : "s"} preserved: ${otherServers.join(", ")})`;
+}

package/src/lib/mergers/gitignore.mjs

@@ -1,39 +1,94 @@
 /**
- * Merger for .gitignore — adds SkillRepo rules file patterns.
+ * Merger for .gitignore — adds the three paths `skillrepo init` writes
+ * that must not be committed.
  *
- * Skills delivered via .claude/rules/skillrepo-*.md are user-specific
- * (based on library subscription) and should not be committed to git.
+ * 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:
+ *
+ *   - `.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.
+ *
+ * Idempotent: entries already present are skipped. A single call
+ * either adds all missing entries in one grouped section or exits
+ * without writing if they're all already present.
  */
 
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
 import { join } from "node:path";
 
-const GITIGNORE_ENTRY = ".claude/rules/skillrepo-*.md";
-const SECTION_HEADER = "# SkillRepo (auto-generated rules files)";
+const SECTION_HEADER = "# SkillRepo CLI (added by `skillrepo init`)";
+const REQUIRED_ENTRIES = [
+  ".env.local",
+  ".claude/skills/",
+  ".claude/settings.local.json",
+];
 
 /**
- * Add SkillRepo rules file pattern to .gitignore.
- * Creates .gitignore if it doesn't exist. Idempotent — skips if already present.
+ * Ensure the three 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.
  *
- * @returns {{ path: string; action: string }}
+ * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
 export function mergeGitignore() {
   const gitignorePath = join(process.cwd(), ".gitignore");
   const existing = readFileSafe(gitignorePath);
 
-  if (existing !== null && existing.includes(GITIGNORE_ENTRY)) {
-    return { path: ".gitignore", action: "skipped" };
+  if (existing === null) {
+    // Fresh .gitignore — write all required entries as one section.
+    const content = renderSection(REQUIRED_ENTRIES);
+    writeFileSafe(gitignorePath, content);
+    return {
+      path: ".gitignore",
+      action: "created",
+      added: [...REQUIRED_ENTRIES],
+    };
   }
 
-  const newBlock = `\n${SECTION_HEADER}\n${GITIGNORE_ENTRY}\n`;
+  // Line-exact match check. `.env.local` as a line is distinct from
+  // `.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));
 
-  if (existing === null) {
-    writeFileSafe(gitignorePath, newBlock.trimStart());
-    return { path: ".gitignore", action: "created" };
+  if (missing.length === 0) {
+    return {
+      path: ".gitignore",
+      action: "skipped",
+      added: [],
+    };
   }
 
-  // Append to existing .gitignore
-  const content = existing.endsWith("\n") ? existing + newBlock : existing + "\n" + newBlock;
-  writeFileSafe(gitignorePath, content);
-  return { path: ".gitignore", action: "updated" };
+  // Append only the missing entries as a new section. Preserve the
+  // original line-ending style.
+  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);
+
+  return {
+    path: ".gitignore",
+    action: "updated",
+    added: missing,
+  };
+}
+
+/**
+ * Render the SkillRepo section with the given entries. The leading
+ * blank line separates the section from whatever precedes it when
+ * appending, and the trailing newline keeps the file POSIX-clean.
+ */
+function renderSection(entries, lineEnding = "\n") {
+  return SECTION_HEADER + lineEnding + entries.join(lineEnding) + lineEnding;
 }

package/src/lib/paths.mjs

@@ -3,7 +3,7 @@
  * Uses Node built-ins only — no dependencies.
  */
 
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { homedir } from "node:os";
 
 const cwd = () => process.cwd();
@@ -11,19 +11,10 @@ const cwd = () => process.cwd();
 // Claude Code
 export const claudeMcpJson = () => join(cwd(), ".mcp.json");
 export const claudeDir = () => join(cwd(), ".claude");
-export const claudeSettingsLocal = () => join(cwd(), ".claude", "settings.local.json");
-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");
 
 // Cursor
 export const cursorDir = () => join(cwd(), ".cursor");
 export const cursorMcpJson = () => join(cwd(), ".cursor", "mcp.json");
-export const cursorRulesDir = () => join(cwd(), ".cursor", "rules");
-export const cursorHooksDir = () => join(cwd(), ".cursor", "hooks");
-export const cursorSkillrepoMdc = () => join(cwd(), ".cursor", "rules", "skillrepo.mdc");
-export const cursorSkillrepoIndex = () => join(cwd(), ".cursor", "skillrepo-index.json");
-export const cursorHooksJson = () => join(cwd(), ".cursor", "hooks.json");
 
 // Windsurf (always global — no project-level config)
 export const windsurfDir = () => join(homedir(), ".codeium", "windsurf");
@@ -34,15 +25,53 @@ export const vscodeDir = () => join(cwd(), ".vscode");
 export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 
 // Global SkillRepo cache (shared across projects, lives in user home)
-export const globalSkillrepoDir = () => join(homedir(), ".claude", "skillrepo");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
-export const globalIndexPath = () => join(homedir(), ".claude", "skillrepo", "index.json");
-export const globalSkillsDir = () => join(homedir(), ".claude", "skillrepo", "skills");
 
-// Project-level rules directories (deterministic skill delivery)
-export const claudeRulesDir = () => join(cwd(), ".claude", "rules");
+// ── Skill placement targets (added in #646 / PR1) ─────────────────────
+//
+// 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.
+
+/** Claude Code project-local skill directory for a specific skill name. */
+export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", name);
+
+/** 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");
+
+// ── Shared ────────────────────────────────────────────────────────────
 
-// Shared
 export const envLocal = () => join(cwd(), ".env.local");
-export const projectRoot = () => resolve(cwd());
+
+/**
+ * Project .gitignore — used by the file-write pipeline to ensure the
+ * project /skills/ fallback directory is gitignored on first write.
+ */
+export const gitignorePath = () => join(cwd(), ".gitignore");