pi-cursor-sdk 0.1.29 → 0.1.31

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.1.31 - 2026-06-01
+
+### Added
+
+- Add Cursor `:fast` and `:slow` virtual model aliases for models with a Cursor SDK `fast` parameter so subagents and workflow-spawned agents can choose fast/slow independently of saved `/cursor-fast` defaults (#112).
+
+## 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
 
@@ -168,7 +168,7 @@ pi --model cursor/gpt-5.5@272k:xhigh
 pi --model cursor/gpt-5.5@1m --thinking medium
 ```
 
-Cursor-only parameters are not encoded into pi model IDs. Cursor `context` becomes a pi-visible model variant because it changes pi's native `contextWindow`; Cursor `fast` and Cursor SDK conversation mode are extension state, not model identity. Alias model IDs use their selected SDK ID for Cursor-only state such as fast defaults, with read fallback for older defaults keyed by the underlying Cursor base model.
+Cursor `context` becomes a pi-visible model variant because it changes pi's native `contextWindow`. For models that expose Cursor's boolean `fast` parameter, the extension also registers virtual `:fast` and `:slow` model aliases such as `cursor/composer-2-5:slow` and `cursor/gpt-5.5@1m:fast`. Those aliases are selection-only controls for subagents and workflow-spawned agents: they send the same Cursor SDK model ID plus an explicit `fast=true` or `fast=false` param, and they take precedence over saved `/cursor-fast` session/global defaults. Cursor SDK conversation mode remains extension state, not model identity. Alias model IDs use their selected SDK ID for Cursor-only state such as fast defaults, with read fallback for older defaults keyed by the underlying Cursor base model.
 
 ## Thinking support
 
@@ -190,7 +190,7 @@ Some Cursor SDK models do not expose a `reasoning`, `effort`, or `thinking` para
 
 ## Fast mode
 
-Use `/cursor-fast` to persistently toggle fast mode for the selected Cursor model when the model supports Cursor's `fast` parameter.
+Use `/cursor-fast` to persistently toggle fast mode for the selected unsuffixed Cursor model when the model supports Cursor's `fast` parameter.
 
 Fast preferences are remembered per selected Cursor SDK model ID or alias and stored:
 
@@ -204,7 +204,16 @@ pi --model cursor/gpt-5.5@1m --cursor-fast -p "Say ok only"
 pi --model cursor/composer-2-5 --cursor-no-fast -p "Say ok only"
 ```
 
-Composer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~/.pi/agent/cursor-sdk.json`.
+For per-agent control, select the virtual model alias instead of mutating the shared saved default:
+
+```bash
+pi --model cursor/composer-2-5:slow -p "Say ok only"
+pi --model cursor/gpt-5.5@1m:fast -p "Say ok only"
+```
+
+The `:fast` and `:slow` aliases are available only for Cursor models whose catalog exposes a `fast` parameter. They override saved `/cursor-fast` session/global defaults while leaving `--cursor-fast` and `--cursor-no-fast` as explicit process-level force flags. `/cursor-fast` does not persist a new default while a virtual fast/slow alias is selected; switch to the unsuffixed model first.
+
+Composer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` or a `:slow` virtual alias for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~/.pi/agent/cursor-sdk.json`.
 
 In interactive mode, the footer only shows fast mode when fast is enabled and Cursor mode when it is non-default. Fast and plan mode share one Cursor status value, so they do not overwrite each other:
 
@@ -218,7 +227,7 @@ If you do not see `cursor fast`, fast mode is off. If you do not see `cursor pla
 
 ## Cursor SDK mode
 
-Cursor SDK conversation mode is Cursor-only extension state. It is not a pi model variant, not pi thinking/reasoning, not Cursor `fast`, and not pi's separate read-only plan-mode extension.
+Cursor SDK conversation mode is Cursor-only extension state. It is not a pi model variant, not pi thinking/reasoning, not a `:fast`/`:slow` virtual fast alias, and not pi's separate read-only plan-mode extension.
 
 Default mode is `agent`. Start a one-shot run in a specific mode:
 
@@ -259,7 +268,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

@@ -10,7 +10,7 @@ Current implementation notes:
 
 - Cursor context variants use `base@context` pi model IDs.
 - Cursor `reasoning`, `effort`, and boolean `thinking` parameters are driven by pi native thinking when the Cursor SDK exposes those controls.
-- Cursor `fast` is extension state, not model identity.
+- Cursor `fast` is extension state by default; models that expose `fast` also get selection-only `:fast` / `:slow` virtual aliases for per-agent overrides.
 - Cursor SDK `mode` (`agent` or `plan`) is extension session state, not model identity, pi thinking, Cursor `fast`, or pi's separate plan-mode extension.
 - Cursor status uses one coordinated `ctx.ui.setStatus("cursor", ...)` value for fast and non-default plan mode; the default pi footer remains intact.
 - Installed `@cursor/sdk` user messages accept images, and Cursor models are treated as image-capable; registered input metadata is `text` plus `image`.
@@ -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.
@@ -136,7 +136,7 @@ Use native pi abstractions wherever possible:
 | Cursor `reasoning` | pi native thinking via `thinkingLevelMap` |
 | Cursor `effort` | pi native thinking via `thinkingLevelMap` |
 | Cursor `thinking=false` | pi native `off` |
-| Cursor `fast` | extension state, not model identity |
+| Cursor `fast` | extension state plus `:fast` / `:slow` virtual aliases for per-agent overrides |
 | Cursor SDK `mode` | extension session state; `agent` by default, `plan` via SDK-native mode |
 | Footer | default pi footer plus optional extension status |
 
@@ -156,7 +156,7 @@ Rules:
 - Register one pi model for each Cursor base model and each unambiguous SDK alias when there is no Cursor `context` parameter.
 - Register one pi model per Cursor `context` value for each Cursor base model and each unambiguous SDK alias when the model exposes a `context` parameter.
 - Skip SDK aliases that collide with another base model ID or are shared by multiple base models; those aliases can resolve differently from the pi row metadata.
-- Do not encode `reasoning`, `effort`, `thinking`, `fast`, or Cursor SDK `mode` into pi model IDs.
+- Do not encode `reasoning`, `effort`, `thinking`, or Cursor SDK `mode` into pi model IDs. For models with a Cursor `fast` parameter, also register selection-only `:fast` and `:slow` virtual model aliases that do not change pi-native metadata.
 - Prefer stable, readable `@<context>` suffixes that do not conflict with pi's final `:<thinking>` suffix parser.
 - Sort Cursor models by base ID, then context value in Cursor SDK order before calling `pi.registerProvider()`. Registration order matters for `/model` display and model cycling; `--list-models` sorts output separately.
 
@@ -168,6 +168,9 @@ cursor/gpt-5.5@272k
 cursor/claude-opus-4-8@1m
 cursor/claude-opus-4-8@300k
 cursor/composer-2-5
+cursor/composer-2-5:fast
+cursor/composer-2-5:slow
+cursor/gpt-5.5@1m:fast
 ```
 
 Avoid colon-based context IDs in the first implementation unless this spec is intentionally changed:
@@ -190,7 +193,7 @@ Reason:
 
 - `@1m` keeps context visually separate from pi's native `:medium` thinking suffix.
 - Context variants make `contextWindow` accurate in `--list-models`, the native footer, context overflow checks, and compaction logic.
-- `fast` is intentionally not a model variant because it does not affect pi model metadata and would double list noise.
+- `:fast` / `:slow` are virtual aliases, not separate Cursor SDK base models: they keep the same context/thinking metadata and only force the outgoing Cursor `fast` param. They exist so subagents and workflow-spawned agents can choose fast/slow without mutating shared `/cursor-fast` defaults.
 
 ### Metadata Per Registered Model
 
@@ -362,17 +365,18 @@ fast=false <-> fast=true
 
 Rules:
 
-- `fast` is extension state, not pi model identity.
-- Toggle with `/cursor-fast`.
-- Store per-session and global per-base-model preferences.
-- When calling `Agent.create()`, include the selected `fast` value in Cursor model params.
+- Unsuffixed models use extension state from `/cursor-fast`, per-session entries, and global defaults.
+- `:fast` / `:slow` virtual model aliases force fast on/off for that selected agent and override saved defaults without writing state.
+- Toggle unsuffixed models with `/cursor-fast`; do not persist a new default while a virtual fast alias is selected.
+- Store per-session and global per-base-model preferences for unsuffixed models.
+- When calling `Agent.create()` or `agent.send()`, include the selected `fast` value in Cursor model params.
 - Show `fast` through `ctx.ui.setStatus()` when enabled.
-- Support a first-pass CLI flag, `--cursor-fast`, to force fast mode for one run when the selected model supports it.
+- Keep `--cursor-fast` and `--cursor-no-fast` as explicit process-level force flags.
 
 Reason:
 
 - `fast` does not affect pi `contextWindow`, thinking levels, or input support.
-- Registering fast/non-fast variants would make `--list-models` noisy without improving native pi behavior.
+- The virtual aliases trade small `--list-models` noise for per-agent selection that works with subagents and dynamic workflows, where mutating a shared global fast default is the wrong abstraction.
 
 Status example:
 
@@ -521,7 +525,7 @@ Reason:
 - pi supports one final `:<thinking>` suffix.
 - Cursor-only parameters are not generic pi CLI parameters.
 - Context is already represented by the registered pi model ID.
-- `fast` is controlled by saved extension defaults or the first-pass `--cursor-fast` extension flag.
+- `fast` is controlled by saved extension defaults, `:fast` / `:slow` virtual model aliases, or the `--cursor-fast` / `--cursor-no-fast` extension flags.
 - Cursor SDK `mode` is controlled by `/cursor-mode` session state or the first-pass `--cursor-mode` extension flag; it is never encoded in `--model`.
 
 For print mode:
@@ -529,7 +533,7 @@ For print mode:
 - no keybindings,
 - use selected context model variant,
 - use `--thinking` or `:medium` for reasoning/effort,
-- use saved global `fast` defaults unless `--cursor-fast` is present,
+- use saved global `fast` defaults unless a virtual `:fast` / `:slow` model alias or force flag is present,
 - use Cursor SDK `agent` mode unless `/cursor-mode` session state or `--cursor-mode` overrides it.
 
 Fast flag example:

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.31",
 	"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/cursor-state.ts

@@ -138,6 +138,10 @@ function getFastPreferenceModelId(metadata: NonNullable<ReturnType<typeof getCur
 	return metadata.selectionModelId || metadata.baseModelId;
 }
 
+function getVirtualFastBaseModelId(modelId: string): string {
+	return modelId.replace(/:(?:fast|slow)$/, "");
+}
+
 function getStoredFastPreference(metadata: NonNullable<ReturnType<typeof getCursorModelMetadata>>): boolean | undefined {
 	const preferenceModelId = getFastPreferenceModelId(metadata);
 	return (
@@ -153,6 +157,7 @@ function getEffectiveFast(modelId: string): boolean | undefined {
 	if (!metadata?.supportsFast) return undefined;
 	if (cliForceNoFast) return false;
 	if (cliForceFast) return true;
+	if (metadata.fastOverride !== undefined) return metadata.fastOverride;
 	return getStoredFastPreference(metadata) ?? metadata.defaultFast;
 }
 
@@ -344,6 +349,14 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				ctx.ui.notify("Cursor fast is forced by --cursor-fast", "info");
 				return;
 			}
+			if (metadata.fastOverride !== undefined) {
+				const state = metadata.fastOverride ? "enabled" : "disabled";
+				ctx.ui.notify(
+					`Cursor fast is fixed ${state} by selected model ${metadata.piModelId}; choose ${getVirtualFastBaseModelId(metadata.piModelId)} to use /cursor-fast preferences`,
+					"info",
+				);
+				return;
+			}
 
 			const preferenceModelId = getFastPreferenceModelId(metadata);
 			const current = getEffectiveFast(metadata.piModelId) ?? false;

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;

package/src/model-discovery.ts

@@ -88,6 +88,7 @@ export interface CursorModelMetadata {
 	contextWindow: number;
 	supportsFast: boolean;
 	defaultFast: boolean;
+	fastOverride?: boolean;
 	supportsReasoning: boolean;
 	thinkingLevelMap?: ThinkingLevelMap;
 	parameterIds: {
@@ -205,19 +206,35 @@ function getParamValue(params: ModelParameterValue[], id: string): string | unde
 	return params.find((param) => param.id === id)?.value;
 }
 
-function encodePiModelId(modelId: string, context?: string): string {
-	return context ? `${modelId}@${context}` : modelId;
+function encodePiModelId(modelId: string, context?: string, fastOverride?: boolean): string {
+	const contextQualified = context ? `${modelId}@${context}` : modelId;
+	if (fastOverride === true) return `${contextQualified}:fast`;
+	if (fastOverride === false) return `${contextQualified}:slow`;
+	return contextQualified;
 }
 
-function getModelName(item: ModelListItem, context?: string, alias?: string): string {
+function getModelName(item: ModelListItem, context?: string, alias?: string, fastOverride?: boolean): string {
 	const displayName = item.displayName || item.id;
-	const baseName = alias ? `${displayName} (${alias})` : displayName;
+	const qualifiers: string[] = [];
+	if (alias) qualifiers.push(alias);
+	if (fastOverride === true) qualifiers.push("fast");
+	if (fastOverride === false) qualifiers.push("slow");
+	const baseName = qualifiers.length > 0 ? `${displayName} (${qualifiers.join(", ")})` : displayName;
 	return context ? `${baseName} @ ${context}` : baseName;
 }
 
+function getFastOverrideBasePiModelId(piModelId: string): string {
+	return piModelId.replace(/:(?:fast|slow)$/, "");
+}
+
 function getContextWindow(contextWindowCache: Map<string, number>, piModelId: string, context?: string, baseModelId?: string): number {
-	return (
+	const fastOverrideBasePiModelId = getFastOverrideBasePiModelId(piModelId);
+	const contextWindowOverride =
 		contextWindowCache.get(piModelId) ??
+		(fastOverrideBasePiModelId !== piModelId ? contextWindowCache.get(fastOverrideBasePiModelId) : undefined);
+
+	return (
+		contextWindowOverride ??
 		(context ? parseContextWindow(context) : undefined) ??
 		(baseModelId ? contextWindowCache.get(baseModelId) : undefined) ??
 		contextWindowCache.get("default") ??
@@ -232,6 +249,7 @@ function toMetadata(
 	defaultParams: ModelParameterValue[],
 	context: string | undefined,
 	contextWindowCache: Map<string, number>,
+	fastOverride?: boolean,
 ): CursorModelMetadata {
 	const thinkingLevelMap = getThinkingLevelMap(item);
 	const fastValue = getParamValue(defaultParams, "fast")?.toLowerCase();
@@ -245,6 +263,7 @@ function toMetadata(
 		contextWindow: getContextWindow(contextWindowCache, piModelId, context, item.id),
 		supportsFast: getParameter(item, "fast") !== undefined,
 		defaultFast: fastValue === "true",
+		...(fastOverride !== undefined ? { fastOverride } : {}),
 		supportsReasoning: thinkingLevelMap !== undefined,
 		...(thinkingLevelMap ? { thinkingLevelMap } : {}),
 		parameterIds: {
@@ -310,16 +329,21 @@ function toModelConfigs(
 	const contexts = contextValues.length > 0 ? contextValues : [undefined];
 	const configs: ProviderModelConfig[] = [];
 
+	const fastOverrides = getParameter(item, "fast") === undefined ? [undefined] : [undefined, true, false];
+
 	for (const selectionModelId of getModelIds(item, reservedBaseModelIds, ambiguousAliases)) {
 		const alias = selectionModelId === item.id ? undefined : selectionModelId;
 		for (const context of contexts) {
-			const params = context ? replaceParam(defaultParams, "context", context) : defaultParams;
-			const piModelId = encodePiModelId(selectionModelId, context);
-			if (usedPiModelIds.has(piModelId)) continue;
-			usedPiModelIds.add(piModelId);
-			const metadata = toMetadata(item, piModelId, selectionModelId, params, context, contextWindowCache);
-			metadataByPiModelId.set(piModelId, metadata);
-			configs.push(toModelConfig(metadata, getModelName(item, context, alias)));
+			const contextParams = context ? replaceParam(defaultParams, "context", context) : defaultParams;
+			for (const fastOverride of fastOverrides) {
+				const params = fastOverride === undefined ? contextParams : replaceParam(contextParams, "fast", fastOverride ? "true" : "false");
+				const piModelId = encodePiModelId(selectionModelId, context, fastOverride);
+				if (usedPiModelIds.has(piModelId)) continue;
+				usedPiModelIds.add(piModelId);
+				const metadata = toMetadata(item, piModelId, selectionModelId, params, context, contextWindowCache, fastOverride);
+				metadataByPiModelId.set(piModelId, metadata);
+				configs.push(toModelConfig(metadata, getModelName(item, context, alias, fastOverride)));
+			}
 		}
 	}