@cursor/july 0.1.73 → 0.1.75

package/src/internal/cursor-deployment-relay.ts

@@ -0,0 +1,274 @@
+/**
+ * Pull relay for `/v0/deployment-events`.
+ *
+ * A {@link RelayAdapter} over {@link CursorRelayCore} — the same engine the
+ * GitHub SCM and Slack relays use, so registration heartbeats, durable
+ * offsets, backoff, and bounded dispatch retry are inherited rather than
+ * reimplemented. Only the subscribe/poll paths, the registration body, and
+ * the per-event filter differ.
+ */
+
+import type {
+  DeploymentEvent,
+  DeploymentEventType,
+  DeploymentSubscription,
+} from "../channels/deployments/types.js";
+import { CursorRelayCore, type RelayAdapter } from "./cursor-relay-core.js";
+
+const DEFAULT_EVENTS: readonly DeploymentEventType[] = ["deployment.succeeded"];
+
+/** One page entry: the event fields plus its stream offset, as the sibling
+ * providers spell it. */
+export type DeploymentRelayEvent = DeploymentEvent & { offset: string };
+
+export interface ResolvedSubscription {
+  repo: string;
+  environments: string[];
+  events: Set<DeploymentEventType>;
+}
+
+interface SubscriptionStatus {
+  repo: string;
+  isSubscribed: boolean;
+  detail?: string;
+}
+
+export interface DeploymentEventRelayOptions {
+  baseUrl: string;
+  apiKey: string;
+  stateDir: string;
+  subscriptions: readonly ResolvedSubscription[];
+  dispatch: (event: DeploymentEvent) => Promise<void>;
+  logger: (line: string) => void;
+  fetchImpl?: typeof fetch;
+  pollWaitMs?: number;
+}
+
+/** Normalize the channel's `repos` option into concrete subscriptions. */
+export function resolveDeploymentSubscriptions(options: {
+  repos: readonly (string | DeploymentSubscription)[];
+  environments?: readonly string[];
+  events?: readonly DeploymentEventType[];
+}): ResolvedSubscription[] {
+  const byRepo = new Map<string, ResolvedSubscription>();
+  for (const entry of options.repos) {
+    const subscription: DeploymentSubscription =
+      typeof entry === "string" ? { repo: entry } : entry;
+    // Case-folded only: `Deployment.repository` has no documented format, and
+    // the server keys subscriptions the same way.
+    const repo = subscription.repo.trim().toLowerCase();
+    if (repo === "") {
+      throw new Error(
+        `deploymentsChannel: invalid repo "${subscription.repo}".`
+      );
+    }
+    const environments = [
+      ...new Set(
+        (subscription.environments ?? options.environments ?? [])
+          .map((value) => value.trim())
+          .filter(Boolean)
+      ),
+    ];
+    const events = new Set(
+      subscription.events ?? options.events ?? DEFAULT_EVENTS
+    );
+    if (events.size === 0) {
+      throw new Error(
+        `deploymentsChannel: repo "${repo}" subscribes to no events.`
+      );
+    }
+    // Later entries for the same repo widen the earlier one rather than
+    // silently replacing it.
+    const existing = byRepo.get(repo);
+    if (existing === undefined) {
+      byRepo.set(repo, { repo, environments, events });
+      continue;
+    }
+    for (const event of events) existing.events.add(event);
+    existing.environments =
+      existing.environments.length === 0 || environments.length === 0
+        ? []
+        : [...new Set([...existing.environments, ...environments])];
+  }
+  // Empty is legal here and means "this channel wants nothing", which is how
+  // an env-configured channel stays inert without a repo list. The wire-level
+  // empty list means deregister, so the host simply never registers it.
+  return [...byRepo.values()];
+}
+
+/** Whether one confirmed subscription wants this event. */
+export function deploymentEventMatches(
+  subscription: ResolvedSubscription,
+  envelope: DeploymentEvent
+): boolean {
+  if (!subscription.events.has(envelope.eventType)) {
+    return false;
+  }
+  return (
+    subscription.environments.length === 0 ||
+    subscription.environments.includes(envelope.environment)
+  );
+}
+
+/** One channel the host can deliver a deployment event to. */
+export interface DeploymentDispatchTarget {
+  /** Display name for logs, e.g. `executor/deployments`. */
+  name: string;
+  subscriptions: readonly ResolvedSubscription[];
+  deliver: (event: DeploymentEvent) => Promise<unknown>;
+}
+
+/**
+ * Deliver one event to every channel subscribed to it.
+ *
+ * Each channel is delivered independently: one channel's handler throwing
+ * must not skip the channels after it, because the relay core retries the
+ * whole dispatch and the channels that already ran would see the event twice.
+ * Throws only when every subscribed channel failed, so a retry cannot
+ * re-deliver to a channel that succeeded.
+ */
+export async function fanOutDeploymentEvent(input: {
+  targets: readonly DeploymentDispatchTarget[];
+  event: DeploymentEvent;
+  logger: (line: string) => void;
+}): Promise<void> {
+  const { event, logger } = input;
+  const matched = input.targets.filter((target) =>
+    target.subscriptions.some(
+      (subscription) =>
+        subscription.repo === event.repo &&
+        deploymentEventMatches(subscription, event)
+    )
+  );
+  const failures: string[] = [];
+  for (const target of matched) {
+    try {
+      await target.deliver(event);
+    } catch (error) {
+      failures.push(target.name);
+      logger(
+        `[agent-sdk] deployment-events: ${target.name} failed on ${event.eventId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+  logger(
+    `[agent-sdk] deployment-events: ${event.eventType} ${event.repo}@${event.sha} (${event.environment}) → ${matched.length - failures.length}/${matched.length} channel(s)`
+  );
+  if (failures.length > 0 && failures.length === matched.length) {
+    throw new Error(
+      `deployment-events: every subscribed channel failed on ${event.eventId} (${failures.join(", ")})`
+    );
+  }
+}
+
+export class DeploymentEventRelay {
+  private readonly core: CursorRelayCore<DeploymentRelayEvent>;
+  private subscribed = new Map<string, ResolvedSubscription>();
+  private readonly loggedSkippedRepos = new Set<string>();
+
+  constructor(private readonly options: DeploymentEventRelayOptions) {
+    const adapter: RelayAdapter<DeploymentRelayEvent> = {
+      logPrefix: "deployment-events",
+      subscribePath: "/v0/deployment-events/subscriptions",
+      pollPath: "/v0/deployment-events",
+      buildRegistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: options.subscriptions.map((subscription) => ({
+          repo: subscription.repo,
+          environments: subscription.environments,
+          events: [...subscription.events],
+        })),
+      }),
+      // Empty subscriptions drop this consumer's registration on clean stop
+      // instead of leaving it to lapse by TTL.
+      buildDeregistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: [],
+      }),
+      applyRegistrationResponse: (json) => {
+        const result = json as { repos?: SubscriptionStatus[] };
+        this.subscribed = new Map();
+        this.loggedSkippedRepos.clear();
+        const lines: string[] = [];
+        const confirmed: string[] = [];
+        for (const status of result.repos ?? []) {
+          const wanted = options.subscriptions.find(
+            (subscription) => subscription.repo === status.repo
+          );
+          if (!status.isSubscribed || wanted === undefined) {
+            lines.push(
+              `not subscribed to ${status.repo}: ${status.detail ?? "unknown reason"}`
+            );
+            continue;
+          }
+          this.subscribed.set(status.repo, wanted);
+          confirmed.push(status.repo);
+        }
+        if (confirmed.length > 0) {
+          const kinds = [
+            ...new Set(options.subscriptions.flatMap((s) => [...s.events])),
+          ];
+          lines.push(
+            `subscribed to ${confirmed.join(", ")} for events: ${kinds.join(", ")}`
+          );
+        }
+        return lines;
+      },
+      shouldDispatch: (event) => this.shouldDispatch(event),
+      dispatch: ({ offset: _offset, ...envelope }) =>
+        options.dispatch(envelope),
+    };
+    this.core = new CursorRelayCore<DeploymentRelayEvent>({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      stateDir: options.stateDir,
+      adapter,
+      logger: options.logger,
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+      ...(options.pollWaitMs === undefined
+        ? {}
+        : { pollWaitMs: options.pollWaitMs }),
+    });
+  }
+
+  /**
+   * Whether an event from this principal's stream belongs to THIS relay.
+   * The stream is per-principal, and one API key can back several relays
+   * (other hosts, or an agent running its own alongside the host's), so each
+   * one re-checks the events against the subscriptions the server confirmed
+   * for it.
+   */
+  private shouldDispatch(event: DeploymentRelayEvent): boolean {
+    const envelope = event;
+    if (
+      envelope === null ||
+      typeof envelope !== "object" ||
+      typeof envelope.repo !== "string"
+    ) {
+      return false;
+    }
+    const subscription = this.subscribed.get(envelope.repo);
+    if (subscription === undefined) {
+      if (!this.loggedSkippedRepos.has(envelope.repo)) {
+        this.loggedSkippedRepos.add(envelope.repo);
+        this.options.logger(
+          `[agent-sdk] deployment-events: skipping events for ${envelope.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`
+        );
+      }
+      return false;
+    }
+    return deploymentEventMatches(subscription, envelope);
+  }
+
+  start(): void {
+    this.core.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.core.stop();
+  }
+}

package/src/internal/distribution.ts

@@ -97,6 +97,7 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["channels/slack", "channels/slack/index.js"],
   ["channels/github", "channels/github/index.js"],
   ["channels/origin", "channels/origin/index.js"],
+  ["channels/deployments", "channels/deployments/index.js"],
   ["skills", "skills.js"],
   ["schedules", "schedules.js"],
   ["reminders", "reminders.js"],

package/src/internal/install-cursor-skills.ts

@@ -1,10 +1,17 @@
 /**
  * Offer to install the package's coding-agent skills into the user's
- * personal Cursor skills dir under `~/.cursor/skills/agentkit/<skill>/`.
+ * personal Cursor skills dir under `~/.cursor/skills/agentsdk/<skill>/`.
  *
- * Cursor walks `~/.cursor/skills` recursively, so the `agentkit/` folder is
+ * Cursor walks `~/.cursor/skills` recursively, so the `agentsdk/` folder is
  * only organizational — identity comes from the leaf folder that holds
- * SKILL.md. Skipped for `--json` / non-TTY hosts.
+ * SKILL.md. Installed copies get `alwaysApply: true` so Cursor injects the
+ * skill body as a global rule instead of leaving it as an on-demand catalog
+ * entry. Skipped for `--json` / non-TTY hosts.
+ *
+ * Consumer installs (`npm install` / `npx` of `@cursor/july`) also copy
+ * these skills from a postinstall hook. That path never prompts and never
+ * fails the package install. The monorepo source checkout is not a consumer
+ * install, so `pnpm install` in everysphere does not overwrite `~/.cursor`.
  */
 
 import {
@@ -21,51 +28,86 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
+import { parseFrontmatter } from "./frontmatter.js";
 import { stdoutPalette } from "./terminal-style.js";
 
 /** Monorepo-only skill; excluded from the published package. */
 const SKIP_SKILL_DIRS = new Set(["operate"]);
 
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
-export const CURSOR_SKILLS_NAMESPACE = "agentkit";
+export const CURSOR_SKILLS_NAMESPACE = "agentsdk";
+
+/** Pre-rename install folder. Install deletes this so `/agentkit-*` rows disappear. */
+export const LEGACY_CURSOR_SKILLS_NAMESPACE = "agentkit";
 
 /** How long the `init` offer waits for an answer before skipping the install. */
 export const SKILL_PROMPT_TIMEOUT_MS = 45_000;
 
+/**
+ * Override the resolved `~/.cursor/skills` directory (not the user home).
+ * Used by the postinstall hook in tests and publish smoke.
+ */
+export const CURSOR_JULY_SKILLS_HOME_ENV = "CURSOR_JULY_SKILLS_HOME";
+
+/** Set to `1` to skip the postinstall skill copy. */
+export const CURSOR_JULY_SKIP_SKILL_INSTALL_ENV =
+  "CURSOR_JULY_SKIP_SKILL_INSTALL";
+
 export interface PackageSkill {
-  /** Frontmatter `name` (e.g. agentkit-create-agent). */
+  /** Frontmatter `name` (e.g. agentsdk-create-agent). */
   name: string;
-  /** Leaf install directory under agentkit/ (e.g. create-agent). */
+  /** Leaf install directory under agentsdk/ (e.g. create-agent). */
   leafDir: string;
   /** Absolute path to the source skill directory in the package. */
   sourceDir: string;
 }
 
-export function cursorSkillsHome(
-  home: string = process.env.HOME ?? homedir()
-): string {
-  const resolved = home.trim() === "" ? homedir() : home;
-  return join(resolved, ".cursor", "skills");
+export function cursorSkillsHome(home?: string): string {
+  if (home !== undefined) {
+    return join(home.trim() === "" ? homedir() : home, ".cursor", "skills");
+  }
+  const override = process.env[CURSOR_JULY_SKILLS_HOME_ENV]?.trim();
+  if (override !== undefined && override !== "") {
+    return override;
+  }
+  return join(homedir(), ".cursor", "skills");
+}
+
+/**
+ * True when this package root is an installed copy under `node_modules`
+ * (npm, pnpm, yarn, npx, global), not the everysphere source checkout.
+ */
+export function isConsumerPackageInstall(packageRoot: string): boolean {
+  // Segment check only — split on both separators so a Windows path still
+  // matches when this runs (or is tested) on POSIX. Do not rewrite the path.
+  return packageRoot.split(/[\\/]/).includes("node_modules");
 }
 
-/** `~/.cursor/skills/agentkit` — where package skills are installed. */
-export function agentkitCursorSkillsDir(
+/** `~/.cursor/skills/agentsdk` — where package skills are installed. */
+export function agentsdkCursorSkillsDir(
   skillsHome: string = cursorSkillsHome()
 ): string {
   return join(skillsHome, CURSOR_SKILLS_NAMESPACE);
 }
 
-/** Absolute install path for one skill: `…/agentkit/<leafDir>`. */
+/** Pre-rename `~/.cursor/skills/agentkit`. */
+export function legacyAgentkitCursorSkillsDir(
+  skillsHome: string = cursorSkillsHome()
+): string {
+  return join(skillsHome, LEGACY_CURSOR_SKILLS_NAMESPACE);
+}
+
+/** Absolute install path for one skill: `…/agentsdk/<leafDir>`. */
 export function skillInstallPath(
   skill: Pick<PackageSkill, "leafDir">,
   skillsHome: string = cursorSkillsHome()
 ): string {
-  return join(agentkitCursorSkillsDir(skillsHome), skill.leafDir);
+  return join(agentsdkCursorSkillsDir(skillsHome), skill.leafDir);
 }
 
 /**
  * Skills shipped next to the running package. Uses the frontmatter `name`
- * when present, otherwise `agentkit-<dir>`.
+ * when present, otherwise `agentsdk-<dir>`.
  */
 export async function listShippedPackageSkills(
   packageRoot: string = packageRootDir()
@@ -91,7 +133,9 @@ export async function listShippedPackageSkills(
       continue;
     }
     const raw = await readFile(skillMd, "utf8");
-    const name = parseSkillName(raw) ?? `agentkit-${entry.name}`;
+    const name =
+      parseFrontmatter(raw).data.name ||
+      `${CURSOR_SKILLS_NAMESPACE}-${entry.name}`;
     skills.push({ name, leafDir: entry.name, sourceDir });
   }
   skills.sort((a, b) => a.leafDir.localeCompare(b.leafDir));
@@ -99,7 +143,7 @@ export async function listShippedPackageSkills(
 }
 
 /**
- * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentkit/.
+ * Skills that do not yet have a SKILL.md under ~/.cursor/skills/agentsdk/.
  * Install still overwrites every shipped skill when the user confirms — this
  * helper is for messaging (fresh install vs update).
  */
@@ -125,18 +169,22 @@ export interface SkillInstallResult {
   installed: string[];
   /** Leaf dirs deleted because the package no longer ships them. */
   removed: string[];
+  /** True when leftover `~/.cursor/skills/agentkit` was deleted. */
+  removedLegacyNamespace: boolean;
 }
 
 /**
- * Copy each skill directory into `skillsHome/agentkit/<leafDir>/`.
+ * Copy each skill directory into `skillsHome/agentsdk/<leafDir>/`.
  * Always overwrites so a package upgrade refreshes local Cursor skills.
- * Strips monorepo-only frontmatter and removes leaf dirs no longer shipped.
+ * Strips monorepo-only frontmatter, sets `alwaysApply: true` so Cursor
+ * loads the body into context, and removes leaf dirs no longer shipped.
+ * Also deletes leftover `skillsHome/agentkit/` from the previous namespace.
  */
 export async function installCursorSkills(
   skills: readonly PackageSkill[],
   skillsHome: string = cursorSkillsHome()
 ): Promise<SkillInstallResult> {
-  const namespaceDir = agentkitCursorSkillsDir(skillsHome);
+  const namespaceDir = agentsdkCursorSkillsDir(skillsHome);
   await mkdir(namespaceDir, { recursive: true });
 
   const removed = await orphanLeaves(namespaceDir, skills);
@@ -161,7 +209,9 @@ export async function installCursorSkills(
     }
     installed.push(skill.leafDir);
   }
-  return { installed, removed };
+  const removedLegacyNamespace =
+    await removeLegacyCursorSkillsNamespace(skillsHome);
+  return { installed, removed, removedLegacyNamespace };
 }
 
 async function makeTreeWritable(root: string): Promise<void> {
@@ -202,13 +252,43 @@ async function orphanLeaves(
     .map((entry) => entry.name);
 }
 
-/** Drop monorepo `paths` globs and fix package doc links for ~/.cursor installs. */
+/** Drop leftover `skillsHome/agentkit` from the previous install namespace. */
+async function removeLegacyCursorSkillsNamespace(
+  skillsHome: string
+): Promise<boolean> {
+  const legacyDir = legacyAgentkitCursorSkillsDir(skillsHome);
+  try {
+    await stat(legacyDir);
+  } catch {
+    return false;
+  }
+  await rm(legacyDir, { recursive: true, force: true });
+  return true;
+}
+
+async function hasLegacyCursorSkillsNamespace(
+  skillsHome: string
+): Promise<boolean> {
+  try {
+    await stat(legacyAgentkitCursorSkillsDir(skillsHome));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drop monorepo `paths` globs, set `alwaysApply: true` so Cursor injects the
+ * body as a global rule, and fix package doc links for ~/.cursor installs.
+ */
 export function prepareSkillMarkdownForCursorInstall(content: string): string {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (match === null) {
     return content;
   }
-  const frontmatter = stripPathsFromFrontmatter(match[1] ?? "");
+  const frontmatter = withAlwaysApply(
+    stripPathsFromFrontmatter(match[1] ?? "")
+  );
   const body = content.slice(match[0].length);
   const adjustedBody = body.replace(
     /\[`docs\/([^`]+)`\]\(\.\.\/\.\.\/docs\/[^)]+\)/g,
@@ -235,11 +315,24 @@ function stripPathsFromFrontmatter(frontmatter: string): string {
   return out.join("\n");
 }
 
+/** Cursor loads `alwaysApply: true` skills as global rules, not catalog rows. */
+function withAlwaysApply(frontmatter: string): string {
+  const without = frontmatter
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*alwaysApply\s*:/.test(line))
+    .join("\n")
+    .replace(/\n+$/, "");
+  if (without === "") {
+    return "alwaysApply: true";
+  }
+  return `${without}\nalwaysApply: true`;
+}
+
 export interface SkillInstallPlan {
   shipped: PackageSkill[];
   /** Resolved `~/.cursor/skills`, to install into. */
   skillsHome: string;
-  /** Install target: `<skillsHome>/agentkit`. */
+  /** Install target: `<skillsHome>/agentsdk`. */
   directory: string;
   /** Leaf dirs the package ships. */
   leaves: string[];
@@ -247,6 +340,8 @@ export interface SkillInstallPlan {
   firstInstall: boolean;
   /** Installed leaf dirs the package dropped; installing deletes them. */
   orphans: string[];
+  /** True when leftover `skillsHome/agentkit` still exists. */
+  hasLegacyNamespace: boolean;
 }
 
 /** What an install would do, for the offer and for `install-skills`. */
@@ -255,19 +350,26 @@ export async function planSkillInstall(options?: {
   skillsHome?: string;
 }): Promise<SkillInstallPlan> {
   const skillsHome = options?.skillsHome ?? cursorSkillsHome();
-  const directory = agentkitCursorSkillsDir(skillsHome);
+  const directory = agentsdkCursorSkillsDir(skillsHome);
   const shipped = await listShippedPackageSkills(options?.packageRoot);
-  const missing = await findMissingCursorSkills({
-    packageRoot: options?.packageRoot,
-    skillsHome,
-  });
+  const present = await Promise.all(
+    shipped.map(async (skill) => {
+      try {
+        await access(join(skillInstallPath(skill, skillsHome), "SKILL.md"));
+        return true;
+      } catch {
+        return false;
+      }
+    })
+  );
   return {
     shipped,
     skillsHome,
     directory,
     leaves: shipped.map((skill) => skill.leafDir),
-    firstInstall: missing.length === shipped.length,
+    firstInstall: present.every((isPresent) => !isPresent),
     orphans: await orphanLeaves(directory, shipped),
+    hasLegacyNamespace: await hasLegacyCursorSkillsNamespace(skillsHome),
   };
 }
 
@@ -282,10 +384,73 @@ export function formatSkillInstall(
   if (result.removed.length > 0) {
     lines.push(`  removed:  ${result.removed.join(", ")}`);
   }
+  if (result.removedLegacyNamespace) {
+    lines.push(
+      `  removed:  ${legacyAgentkitCursorSkillsDir(plan.skillsHome)} (legacy namespace)`
+    );
+  }
   lines.push(`  location: ${plan.directory}`);
   return `${lines.join("\n")}\n`;
 }
 
+export type PackageInstallSkillSyncResult =
+  | { status: "installed"; installed: string[]; removed: string[] }
+  | {
+      status: "skipped";
+      reason: "opt-out" | "not-consumer" | "no-skills" | "error";
+    };
+
+export interface SyncCursorSkillsOnPackageInstallOptions {
+  packageRoot?: string;
+  skillsHome?: string;
+  env?: NodeJS.ProcessEnv;
+  /** Override the node_modules consumer check. */
+  consumer?: boolean;
+  out?: (text: string) => void;
+}
+
+/**
+ * Copy shipped coding-agent skills into ~/.cursor/skills/agentsdk during a
+ * consumer `npm install` / `npx`. Never throws: a failed copy must not fail
+ * the package install. No-op in the monorepo source tree and when
+ * `CURSOR_JULY_SKIP_SKILL_INSTALL=1`.
+ */
+export async function syncCursorSkillsOnPackageInstall(
+  options: SyncCursorSkillsOnPackageInstallOptions = {}
+): Promise<PackageInstallSkillSyncResult> {
+  try {
+    const env = options.env ?? process.env;
+    if (env[CURSOR_JULY_SKIP_SKILL_INSTALL_ENV] === "1") {
+      return { status: "skipped", reason: "opt-out" };
+    }
+
+    const packageRoot = options.packageRoot ?? packageRootDir();
+    const consumer = options.consumer ?? isConsumerPackageInstall(packageRoot);
+    if (!consumer) {
+      return { status: "skipped", reason: "not-consumer" };
+    }
+
+    const plan = await planSkillInstall({
+      packageRoot,
+      skillsHome: options.skillsHome,
+    });
+    if (plan.shipped.length === 0) {
+      return { status: "skipped", reason: "no-skills" };
+    }
+
+    const result = await installCursorSkills(plan.shipped, plan.skillsHome);
+    const out = options.out ?? ((text) => process.stderr.write(text));
+    out(formatSkillInstall(plan, result));
+    return {
+      status: "installed",
+      installed: result.installed,
+      removed: result.removed,
+    };
+  } catch {
+    return { status: "skipped", reason: "error" };
+  }
+}
+
 export interface OfferInstallCursorSkillsOptions {
   /** Skip when false (non-TTY / `--json`). */
   interactive?: boolean;
@@ -298,7 +463,7 @@ export interface OfferInstallCursorSkillsOptions {
 
 /**
  * On a TTY, offer to install/update every shipped package skill into
- * ~/.cursor/skills/agentkit (always overwriting). No-op when non-interactive
+ * ~/.cursor/skills/agentsdk (always overwriting). No-op when non-interactive
  * or the package ships no skills. An unanswered prompt skips the install
  * rather than blocking the caller — see `SKILL_PROMPT_TIMEOUT_MS`.
  */
@@ -334,6 +499,13 @@ export async function offerInstallCursorSkills(
   if (plan.orphans.length > 0) {
     out(c.dim(`  (deletes ${plan.orphans.join(", ")})\n`));
   }
+  if (plan.hasLegacyNamespace) {
+    out(
+      c.dim(
+        `  (deletes leftover ${legacyAgentkitCursorSkillsDir(plan.skillsHome)})\n`
+      )
+    );
+  }
 
   const confirm =
     options.confirm ??
@@ -365,23 +537,6 @@ export async function offerInstallCursorSkills(
   return { installed: result.installed, skipped: false };
 }
 
-function parseSkillName(skillMd: string): string | undefined {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
-  if (match === null) {
-    return undefined;
-  }
-  const nameLine = /^name:\s*(.+)\s*$/m.exec(match[1] ?? "");
-  if (nameLine === null) {
-    return undefined;
-  }
-  const raw = nameLine[1]?.trim();
-  if (raw === undefined || raw === "") {
-    return undefined;
-  }
-  // Strip optional quotes around the YAML scalar.
-  return raw.replace(/^["']|["']$/g, "");
-}
-
 export interface PromptYesNoOptions {
   defaultYes: boolean;
   out: (text: string) => void;