pi-cursor-sdk 0.1.29 → 0.1.30

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.30 - 2026-06-01
+
+### Added
+
+- Preserve pi Agent Skills for Cursor runs by rewriting pi's skill catalog into Cursor-safe activation instructions and exposing `cursor_activate_skill` through the pi MCP bridge as `pi__cursor_activate_skill` when visible pi skills are available (#113).
+
+### Changed
+
+- Document that deprecated install warnings currently come from the closed-source Cursor SDK's `sqlite3@5.1.x` transitive dependency chain, and document root-project override limits/workarounds instead of relying on unsupported transitive package overrides (#115).
+
 ## 0.1.29 - 2026-06-01
 
 ### Added

package/README.md

@@ -34,7 +34,7 @@ If pi started without a key, run `/cursor-refresh-models` after `/login` to refr
 - pi 0.76.0 or newer
 - a Cursor SDK API key saved through `/login`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`
 
-No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.17`, so normal package installation brings in the SDK version this extension was built and tested against. This package declares a pi **minimum** of 0.76.0 with no maximum peer version, so users who update pi before this extension is republished are not blocked from trying the existing extension. The current validation baseline is pi 0.78.0 plus Cursor SDK 1.0.17; older pi or Cursor SDK compatibility paths are not maintained.
+No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.17`, so normal package installation brings in the SDK version this extension was built and tested against. The Cursor SDK currently depends on `sqlite3@^5.1.7`, whose install path can print deprecated transitive `node-gyp@8` dependency warnings such as `inflight`, `rimraf`, `glob`, `npmlog`, `gauge`, `are-we-there-yet`, and `tar@6`. Those warnings are non-fatal and come from the closed-source Cursor SDK dependency boundary; this package cannot force npm overrides into consumer projects. If you install from a root `package.json` you control, you may choose a root-level override such as `"overrides": { "sqlite3": "6.0.1" }`; pi package installs will still follow npm's normal transitive dependency rules. This package declares a pi **minimum** of 0.76.0 with no maximum peer version, so users who update pi before this extension is republished are not blocked from trying the existing extension. The current validation baseline is pi 0.78.0 plus Cursor SDK 1.0.17; older pi or Cursor SDK compatibility paths are not maintained.
 
 ## Install
 
@@ -259,7 +259,7 @@ Cursor runs use local Cursor SDK agents with two separate tool surfaces:
 
 Bridge capabilities are snapshotted from `pi.getActiveTools()` and `pi.getAllTools()` for each Cursor run, including per-tool prompt guidelines when pi exposes them. Cursor sees active bridgeable pi tools as collision-safe MCP names such as `pi__sem_reindex` only when they are exposed in that current run. Pi session output, tool cards, confirmations, hooks, renderers, history, and abort behavior use the real pi tool name, such as `sem_reindex`. The bridge queues Cursor's MCP call, emits a normal pi `toolCall`, waits for the matching pi `toolResult`, and resolves that result back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. The bridge does not call pi tool `execute()` handlers directly.
 
-Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when enabled, allowing Cursor to ask the user through pi UI instead of silently choosing a default.
+Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when enabled, allowing Cursor to ask the user through pi UI instead of silently choosing a default. When pi has visible Agent Skills loaded, the extension rewrites pi's skill catalog for Cursor and exposes `cursor_activate_skill` as `pi__cursor_activate_skill`; Cursor should call that bridge tool with a listed skill name to load the full `SKILL.md` and bundled resource list before applying the skill. If the bridge is disabled, the catalog remains available and instructs Cursor to fall back to reading the listed `SKILL.md` path directly.
 
 Cursor-native tool replay is separate from the bridge. Replay cards are display-only recorded Cursor SDK activity. They never re-run Cursor-side commands, reapply Cursor edits, call MCP servers, or mutate pi state. See [Cursor native tool replay](docs/cursor-native-tool-replay.md).
 

package/docs/cursor-model-ux-spec.md

@@ -24,7 +24,7 @@ Current implementation notes:
 - Local Cursor agents get two tool surfaces. First, Cursor keeps the Cursor SDK local-agent tool surface plus configured Cursor settings, plugins, and Cursor MCP servers. Second, pi-cursor-sdk exposes active pi tools through a default-on, tokenized loopback MCP bridge when bridgeable tools exist.
 - `buildCursorPiToolBridgeSnapshot()` is the runtime capability source for pi bridge tools. It snapshots `pi.getActiveTools()` and `pi.getAllTools()`, carries pi 0.77+ per-tool `promptGuidelines` into bridge MCP descriptions, filters internal replay names, hides overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) unless `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1`, and creates collision-safe MCP names such as `pi__sem_reindex`. Cursor discovers the current run's exposed bridge tools through MCP `listTools`. Bootstrap prompts include a compact callable-surface manifest from `buildCursorToolManifestText()` by default (`PI_CURSOR_TOOL_MANIFEST=1`); disable with `PI_CURSOR_TOOL_MANIFEST=0`. There is no per-turn visible tool list, status manifest, or footer manifest. User-facing summary: [Cursor tool surfaces in pi](./cursor-tool-surfaces.md).
 - Prompt text is the primary provider/bridge contract. Bootstrap prompts carry a short boundary block plus the callable-surface manifest by default (`PI_CURSOR_TOOL_MANIFEST=1`). MCP `listTools` descriptions use a one-line pointer to the bootstrap prompt instead of repeating the full contract (`buildCursorPiBridgeMcpToolDescription()`). Cursor must call the exposed `pi__*` MCP name, not the real pi tool name shown in pi history or transcripts. Pi emits and executes the real pi tool name. Maintainer debug: `/cursor-tools` prints bridge/manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and the current callable-surface snapshot.
-- The provider also registers `cursor_ask_question` for Cursor models when the bridge is enabled. Cursor sees it as `pi__cursor_ask_question`, and pi executes it through the normal tool path so interactive users can choose options from pi UI. In non-UI modes it reports that UI is unavailable so Cursor can state a default assumption instead. `PI_CURSOR_PI_TOOL_BRIDGE=0` disables the local bridge, including question bridging. Cloud Cursor agents remain out of scope for the bridge.
+- The provider also registers `cursor_ask_question` for Cursor models when the bridge is enabled. Cursor sees it as `pi__cursor_ask_question`, and pi executes it through the normal tool path so interactive users can choose options from pi UI. In non-UI modes it reports that UI is unavailable so Cursor can state a default assumption instead. When pi has visible Agent Skills loaded, the provider rewrites the skill catalog for Cursor and registers `cursor_activate_skill` as `pi__cursor_activate_skill`; pi executes it through the normal tool path so Cursor can load the full `SKILL.md` and skill resource list for the current pi-loaded skill source of truth. `PI_CURSOR_PI_TOOL_BRIDGE=0` disables the local bridge, including question and skill activation bridging. Cloud Cursor agents remain out of scope for the bridge.
 - The bridge queues MCP calls, emits provider `toolcall_*` events, waits for matching pi `toolResult` messages by `toolCallId`, resolves the result back into the same live Cursor SDK run without creating a new `Agent`, and never calls tool `execute()` handlers directly. The same-run resume invariant holds unless the run was disposed, aborted, or cancelled.
 - Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.17 has a 60-second MCP request default with no public per-server timeout option. The extension extends the verified Cursor SDK MCP `callTool` timeout path to 3600 seconds by default and shortens the verified first-send MCP initialize/listTools timeout paths to 10 seconds by default so unavailable configured MCP servers do not block the first reply for a full minute; unknown MCP protocol timeout stacks keep the SDK default. Users can override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`.
 - Bridge diagnostics are opt-in only: `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` writes typed, allowlisted, scrubbed single-line JSONL records to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`. Diagnostics are scrubbed operational logs, not anonymous telemetry. They intentionally include tool names, safe correlation IDs, run lifecycle, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. Correlation IDs are generated independently from the tokenized endpoint path, and Cursor MCP call IDs are hashed before serialization. Diagnostics must not include endpoint paths/URLs/path components/tokens, API keys, bearer tokens, cookies, session credentials, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, or local private session paths in tracked docs, and they must not call pi UI status, notification, or footer APIs. If tool names themselves are unacceptable for a release target, bridge debug diagnostics are not safe for shared logs under the current contract.

package/docs/cursor-native-tool-replay.md

@@ -23,7 +23,7 @@ Cursor SDK `plan` mode (`--cursor-mode plan` or `/cursor-mode plan`) can make Cu
 
 ## Local pi bridge summary
 
-The bridge is enabled by default when bridgeable active pi tools exist. Cursor sees bridge-owned MCP names such as `pi__sem_reindex`, while pi history and tool cards use the real pi tool name such as `sem_reindex`. The bridge hides overlapping built-in pi tools by default because Cursor already has native equivalents; extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. pi-cursor-sdk also registers `cursor_ask_question` for Cursor models when the bridge is enabled, exposed to Cursor as `pi__cursor_ask_question`, so Cursor can ask the user to choose instead of silently defaulting when the pi UI is available. The bridge does not call pi tool `execute()` handlers directly; it queues the request, emits a real pi `toolCall`, waits for the matching pi `toolResult`, and resolves the Cursor MCP call back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled.
+The bridge is enabled by default when bridgeable active pi tools exist. Cursor sees bridge-owned MCP names such as `pi__sem_reindex`, while pi history and tool cards use the real pi tool name such as `sem_reindex`. The bridge hides overlapping built-in pi tools by default because Cursor already has native equivalents; extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. pi-cursor-sdk also registers `cursor_ask_question` for Cursor models when the bridge is enabled, exposed to Cursor as `pi__cursor_ask_question`, so Cursor can ask the user to choose instead of silently defaulting when the pi UI is available. When pi has visible Agent Skills loaded, pi-cursor-sdk registers `cursor_activate_skill`, exposed as `pi__cursor_activate_skill`, so Cursor can load the full pi `SKILL.md` that corresponds to the current pi skill catalog. The bridge does not call pi tool `execute()` handlers directly; it queues the request, emits a real pi `toolCall`, waits for the matching pi `toolResult`, and resolves the Cursor MCP call back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled.
 
 Rollback, timeout, and diagnostics controls:
 

package/docs/cursor-tool-surfaces.md

@@ -8,7 +8,7 @@ pi-cursor-sdk runs Cursor models through the local `@cursor/sdk` agent runtime.
 | --- | --- | --- | --- |
 | **Cursor SDK host tools** | Cursor local agent | Yes | Native replay cards (`read`, `bash`, …) or neutral Cursor activity. Representative ToolType list: [SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix). |
 | **Configured Cursor MCP** | Cursor settings / `~/.cursor/mcp.json` | Yes (when loaded) | Neutral **Cursor MCP** activity cards on replay |
-| **Pi bridge (`pi__*`)** | pi-cursor-sdk loopback MCP | Yes, when exposed | Real pi tool names (`cursor_ask_question`, extension tools, …) |
+| **Pi bridge (`pi__*`)** | pi-cursor-sdk loopback MCP | Yes, when exposed | Real pi tool names (`cursor_ask_question`, `cursor_activate_skill`, extension tools, …) |
 
 **Not callable:** `cursor-replay-*` IDs in JSONL, pi history tool names used only for display, and transcript labels. Cursor must call exposed `pi__*` MCP names for bridged pi tools, not the pi card name.
 
@@ -27,7 +27,7 @@ Default behavior:
 - The pi bridge exposes **active pi tools** as `pi__*` MCP names when `PI_CURSOR_PI_TOOL_BRIDGE` is enabled (default on).
 - Overlapping pi builtins (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are **hidden** from the bridge unless `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1`.
 
-`pi-cursor-sdk` always registers `cursor_ask_question` for Cursor models when the bridge is on; Cursor sees `pi__cursor_ask_question`.
+`pi-cursor-sdk` always registers `cursor_ask_question` for Cursor models when the bridge is on; Cursor sees `pi__cursor_ask_question`. When pi has visible Agent Skills loaded, the extension also rewrites pi's skill catalog for Cursor and activates `cursor_activate_skill`; Cursor sees `pi__cursor_activate_skill` and should call it with a listed skill name before applying that skill. The activation result returns the full `SKILL.md`, the skill directory for relative paths, and a bounded list of bundled `scripts/`, `references/`, and `assets/` files without eagerly reading those resources.
 
 ```bash
 # Disable pi bridge entirely

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.29",
+	"version": "0.1.30",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

package/src/context.ts

@@ -114,10 +114,8 @@ function sanitizeSystemPromptForCursor(systemPrompt: string): string {
 		/Guidelines:\n[\s\S]*?\n\nPi documentation /g,
 		"Guidelines:\n- Be concise in your responses.\n- Show file paths clearly when working with files.\n\nPi documentation ",
 	);
-	sanitized = sanitized.replace(
-		/\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/g,
-		"",
-	);
+	// Keep the Agent Skills catalog. Cursor-specific skill activation wording is normalized
+	// by cursor-skill-tool.ts before this prompt reaches the Cursor SDK provider.
 	sanitized = sanitized.replace(/\n+Semantic code intelligence priority:[\s\S]*$/g, "");
 	return sanitized.trim();
 }

package/src/cursor-skill-tool.ts

@@ -0,0 +1,273 @@
+import type { Dirent } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BuildSystemPromptOptions,
+	ExtensionAPI,
+	ExtensionContext,
+	ExtensionHandler,
+	SessionStartEvent,
+	Skill,
+	TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { isCursorModel } from "./cursor-model.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-snapshot.js";
+
+export const CURSOR_ACTIVATE_SKILL_TOOL_NAME = "cursor_activate_skill";
+export const CURSOR_ACTIVATE_SKILL_MCP_NAME = "pi__cursor_activate_skill";
+
+const AVAILABLE_SKILLS_SECTION_PATTERN = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+const MAX_SKILL_RESOURCES = 80;
+const RESOURCE_DIR_NAMES = ["scripts", "references", "assets"] as const;
+
+type CursorSkillToolExtensionApi = Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> & {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
+};
+
+type CursorActivateSkillParams = {
+	name?: string;
+};
+
+interface CursorSkillActivationDetails {
+	name?: string;
+	filePath?: string;
+	baseDir?: string;
+	resources: string[];
+	availableSkillNames: string[];
+}
+
+let currentSkillsByName = new Map<string, Skill>();
+
+function escapeXml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/\"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+function getVisibleSkills(skills: readonly Skill[] | undefined): Skill[] {
+	return (skills ?? []).filter((skill) => !skill.disableModelInvocation);
+}
+
+function setCurrentSkills(skills: readonly Skill[] | undefined): void {
+	currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
+}
+
+function getAvailableSkillNames(): string[] {
+	return [...currentSkillsByName.keys()].sort();
+}
+
+function shouldExposeSkillTool(model: ExtensionContext["model"]): boolean {
+	return isCursorModel(model) && resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
+}
+
+function syncCursorSkillToolForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+	const activeToolNames = new Set(pi.getActiveTools());
+	const shouldBeActive = shouldExposeSkillTool(model);
+	const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	if (shouldBeActive === alreadyActive) return;
+	if (shouldBeActive) {
+		activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	} else {
+		activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+	}
+	pi.setActiveTools([...activeToolNames]);
+}
+
+export function formatCursorSkillsForPrompt(skills: readonly Skill[]): string {
+	const visibleSkills = getVisibleSkills(skills);
+	if (visibleSkills.length === 0) return "";
+
+	const lines = [
+		"\n\nThe following skills provide specialized instructions for specific tasks.",
+		`When a task matches a skill's description, call ${CURSOR_ACTIVATE_SKILL_MCP_NAME} with the skill name to load its full SKILL.md instructions before proceeding.`,
+		"If the pi bridge is disabled and the activation tool is unavailable, use Cursor's file-read capability on the listed SKILL.md location instead.",
+		"When a skill references relative paths, resolve them against the skill directory (the parent of SKILL.md / dirname of the path) and use absolute paths in tool calls.",
+		"",
+		"<available_skills>",
+	];
+	for (const skill of visibleSkills) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+		lines.push("  </skill>");
+	}
+	lines.push("</available_skills>");
+	return lines.join("\n");
+}
+
+export function resolveCursorSkillSystemPrompt(
+	systemPrompt: string,
+	model: ExtensionContext["model"],
+	systemPromptOptions?: BuildSystemPromptOptions,
+): string {
+	if (!isCursorModel(model)) return systemPrompt;
+	const skills = getVisibleSkills(systemPromptOptions?.skills);
+	if (skills.length === 0) return systemPrompt;
+	const replacement = formatCursorSkillsForPrompt(skills);
+	if (AVAILABLE_SKILLS_SECTION_PATTERN.test(systemPrompt)) {
+		return systemPrompt.replace(AVAILABLE_SKILLS_SECTION_PATTERN, replacement);
+	}
+	return `${systemPrompt}${replacement}`;
+}
+
+async function collectResourcePaths(root: string, absoluteDir: string, output: string[]): Promise<void> {
+	if (output.length >= MAX_SKILL_RESOURCES) return;
+	let entries: Dirent[];
+	try {
+		entries = await readdir(absoluteDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		if (output.length >= MAX_SKILL_RESOURCES) return;
+		const absolutePath = join(absoluteDir, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) {
+			await collectResourcePaths(root, absolutePath, output);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		output.push(relative(root, absolutePath).replace(/\\/g, "/"));
+	}
+}
+
+async function listSkillResourcePaths(baseDir: string): Promise<string[]> {
+	const resources: string[] = [];
+	for (const resourceDirName of RESOURCE_DIR_NAMES) {
+		await collectResourcePaths(baseDir, join(baseDir, resourceDirName), resources);
+		if (resources.length >= MAX_SKILL_RESOURCES) break;
+	}
+	return resources;
+}
+
+function buildActivationDetails(skill: Skill | undefined, resources: string[] = []): CursorSkillActivationDetails {
+	return {
+		name: skill?.name,
+		filePath: skill?.filePath,
+		baseDir: skill ? dirname(skill.filePath) : undefined,
+		resources,
+		availableSkillNames: getAvailableSkillNames(),
+	};
+}
+
+function formatSkillResources(resources: readonly string[]): string {
+	if (resources.length === 0) return "<skill_resources />";
+	return [
+		"<skill_resources>",
+		...resources.map((resource) => `  <file>${escapeXml(resource)}</file>`),
+		"</skill_resources>",
+	].join("\n");
+}
+
+function wrapSkillContent(skill: Skill, content: string, resources: readonly string[]): string {
+	const baseDir = dirname(skill.filePath);
+	return [
+		`<skill_content name=\"${escapeXml(skill.name)}\">`,
+		content.trim(),
+		"",
+		`Skill directory: ${baseDir}`,
+		"Relative paths in this skill are relative to the skill directory.",
+		formatSkillResources(resources),
+		"</skill_content>",
+	].join("\n");
+}
+
+export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
+	pi.registerTool({
+		name: CURSOR_ACTIVATE_SKILL_TOOL_NAME,
+		label: "Cursor skill",
+		description: "Load full pi Agent Skill instructions for Cursor. Use with a skill name from the current <available_skills> catalog before applying that skill.",
+		parameters: Type.Object({
+			name: Type.String({ description: "Skill name from the current <available_skills> catalog" }),
+		}),
+		promptGuidelines: [
+			`Use ${CURSOR_ACTIVATE_SKILL_TOOL_NAME} only for skill names listed in the current <available_skills> catalog.`,
+			"After loading a skill, follow its instructions and resolve relative skill paths against the returned skill directory.",
+		],
+		async execute(_toolCallId, params) {
+			const requestedName = (params as CursorActivateSkillParams).name?.trim();
+			if (!requestedName) {
+				return {
+					content: [{ type: "text" as const, text: "No skill name was provided." }],
+					details: buildActivationDetails(undefined),
+					isError: true,
+				};
+			}
+			const skill = currentSkillsByName.get(requestedName);
+			if (!skill) {
+				return {
+					content: [{ type: "text" as const, text: `Skill not available: ${requestedName}. Available skills: ${getAvailableSkillNames().join(", ") || "none"}.` }],
+					details: buildActivationDetails(undefined),
+					isError: true,
+				};
+			}
+
+			try {
+				const [content, resources] = await Promise.all([
+					readFile(skill.filePath, "utf8"),
+					listSkillResourcePaths(dirname(skill.filePath)),
+				]);
+				return {
+					content: [{ type: "text" as const, text: wrapSkillContent(skill, content, resources) }],
+					details: buildActivationDetails(skill, resources),
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Failed to load skill ${requestedName} from ${skill.filePath}: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
+					details: buildActivationDetails(skill),
+					isError: true,
+				};
+			}
+		},
+	});
+
+	const clearSkillsAndSync = (model: ExtensionContext["model"]): void => {
+		setCurrentSkills([]);
+		syncCursorSkillToolForModel(pi, model);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		clearSkillsAndSync(ctx.model);
+	});
+	pi.on("model_select", (event) => {
+		clearSkillsAndSync(event.model);
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		if (!isCursorModel(ctx.model)) setCurrentSkills([]);
+		syncCursorSkillToolForModel(pi, ctx.model);
+	});
+	pi.on("before_agent_start", (event, ctx) => {
+		if (isCursorModel(ctx.model)) {
+			setCurrentSkills(event.systemPromptOptions?.skills);
+		} else {
+			setCurrentSkills([]);
+		}
+		syncCursorSkillToolForModel(pi, ctx.model);
+		const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions);
+		if (resolved === event.systemPrompt) return undefined;
+		return { systemPrompt: resolved };
+	});
+}
+
+export const __testUtils = {
+	AVAILABLE_SKILLS_SECTION_PATTERN,
+	buildActivationDetails,
+	setCurrentSkills,
+	listSkillResourcePaths,
+	wrapSkillContent,
+};

package/src/index.ts

@@ -4,6 +4,7 @@ import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display.js";
 import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
+import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionCwd } from "./cursor-session-cwd.js";
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context.js";
 import { registerCursorSessionAgent } from "./cursor-session-agent.js";
@@ -18,6 +19,7 @@ type CursorExtensionApi =
 	& Parameters<typeof registerCursorRuntimeControls>[0]
 	& Parameters<typeof registerCursorNativeToolDisplay>[0]
 	& Parameters<typeof registerCursorQuestionTool>[0]
+	& Parameters<typeof registerCursorSkillTool>[0]
 	& Parameters<typeof registerCursorPiToolBridge>[0]
 	& Parameters<typeof registerCursorAgentsContextDedup>[0];
 
@@ -46,6 +48,7 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorRuntimeControls(pi);
 	registerCursorNativeToolDisplay(pi);
 	registerCursorQuestionTool(pi);
+	registerCursorSkillTool(pi);
 	registerCursorPiToolBridge(pi);
 	registerCursorAgentsContextDedup(pi);
 	let fallbackIssue: CursorModelFallbackIssue | undefined;