one-code-extension 0.1.4 → 0.3.1

package/extensions/skill/index.ts

@@ -12,35 +12,71 @@
  */
 
 import { readFileSync } from "node:fs";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import os from "node:os";
-import { join } from "node:path";
-import { discoverPlugins } from "../lib/plugins.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { pluginRoot } from "../lib/plugin-root.ts";
+import { defaultDiscoverRoots, discoverPlugins } from "../lib/plugins.ts";
 import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
-import { ccToolRenderers } from "../lib/tui-render.ts";
+import {
+	nextSkillState,
+	readSkillStates,
+	setSkillState,
+	type SkillScope,
+	type SkillState,
+	skillOverrideKey,
+	skillStateFor,
+} from "../lib/skill-overrides.ts";
+import { BUNDLED_SKILLS_DIR, estimateSkillTokens, promptTemplateNames, scanSkills, scopeForPath } from "../lib/skill-scan.ts";
+import { recordUsage } from "../lib/usage-tracker.ts";
+import { boundedDockHeight, ccToolRenderers, safeThemeBold, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
+import {
+	bareSkillMatches,
+	buildSkillBlock,
+	parseSkillCommand,
+	redactOffSkillMessages,
+	resolveSkill,
+	skillCommandCandidates,
+} from "./invoke.ts";
+import { decodeSkillsKey } from "./panel/keys.ts";
+import { skillListingText } from "./listing.ts";
+import { renderSkillsPanel, type SkillsPaint } from "./panel/render.ts";
+import { applySkillsKey, initialSkillsState, type SkillsRow, visibleRows } from "./panel/state.ts";
+import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
 
 interface IndexedSkill {
 	name: string;
 	description?: string;
 	path: string;
 	source: "project" | "plugin";
+	scope: SkillScope;
+	state: SkillState;
+	pluginName?: string;
 }
 
+/** Bounded dock like the /plugins panel — keeps the transcript visible above. */
+const SKILLS_PANEL_MAX_HEIGHT = 24;
+
 export default function skillExtension(pi: ExtensionAPI) {
 	/** pi resolves skills per turn; cache the latest list for the tool to use. */
 	let piSkills: IndexedSkill[] = [];
+	/** Session cwd, so project-level enabledPlugins settings apply to plugin skills. */
+	let sessionCwd: string | undefined;
 
-	pi.on("before_agent_start", (event) => {
+	pi.on("before_agent_start", (event, ctx) => {
+		sessionCwd = ctx.cwd;
 		const skills = event.systemPromptOptions.skills ?? [];
 		piSkills = skills.map((skill) => {
 			const record = skill as unknown as { name: string; description?: string; path?: string; filePath?: string };
+			const path = record.path ?? record.filePath ?? "";
 			return {
 				name: record.name,
 				description: record.description,
-				path: record.path ?? record.filePath ?? "",
+				path,
 				source: "project" as const,
+				scope: scopeForPath(path, os.homedir(), getAgentDir()),
+				state: "on" as const, // resolved per index() call below
 			};
 		});
 		// Claude Code lists skills as a <system-reminder> on the first user message
@@ -57,23 +93,78 @@ export default function skillExtension(pi: ExtensionAPI) {
 		}
 	});
 
-	const index = (): IndexedSkill[] => [
-		...piSkills.filter((skill) => skill.path),
-		...discoverPlugins(join(os.homedir(), ".claude")).skills.map((skill) => ({
+	/**
+	 * Description from a SKILL.md frontmatter, for skills pi hasn't resolved (the
+	 * pre-first-turn scan) and for plugin skills (discoverPlugins carries none).
+	 * Cached per path: the listing is rebuilt every turn and a description is
+	 * stable for the session anyway (the listing must stay byte-stable for the
+	 * cache prefix).
+	 */
+	const descriptionCache = new Map<string, string | undefined>();
+	const readDescription = (path: string): string | undefined => {
+		if (descriptionCache.has(path)) return descriptionCache.get(path);
+		const description = readDescriptionUncached(path);
+		descriptionCache.set(path, description);
+		return description;
+	};
+	const readDescriptionUncached = (path: string): string | undefined => {
+		try {
+			const { frontmatter } = parseFrontmatterLoosely(readFileSync(path, "utf-8")) as {
+				frontmatter?: { description?: unknown };
+			};
+			return typeof frontmatter?.description === "string" ? frontmatter.description : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+
+	// Per-skill availability comes from the skill-overrides store (the /skills
+	// panel cycles it, the /plugins panel manages plugin skills). The listing
+	// and the tool both re-read it, so a change applies live.
+	//
+	// During a turn, project/user skills come from `piSkills` — pi already
+	// resolved them for this turn (with descriptions), so no disk scan runs on
+	// the per-turn listing path. Before the first turn `piSkills` is empty, so
+	// the /skills command/panel falls back to a disk scan (reading each
+	// SKILL.md's frontmatter for its description) — that's the gap that made a
+	// fresh session's /skills show only plugin skills.
+	const index = (cwd = sessionCwd): IndexedSkill[] => {
+		const agentDir = getAgentDir();
+		const home = os.homedir();
+		const states = readSkillStates(pluginRoot(agentDir));
+		const resolved = piSkills.filter((skill) => skill.path);
+		const base =
+			resolved.length > 0
+				? resolved
+				: scanSkills(cwd ?? process.cwd(), home, agentDir, [], BUNDLED_SKILLS_DIR).map((skill) => ({
+						name: skill.name,
+						description: readDescription(skill.path),
+						path: skill.path,
+						source: "project" as const,
+						scope: skill.scope,
+						state: "on" as const,
+					}));
+		const project = base.map((skill) => ({
+			...skill,
+			state: skillStateFor(states, skillOverrideKey(skill.scope, skill.name)),
+		}));
+		// Plugin skills from discoverPlugins are already filtered to enabled by
+		// the same store; anything it returns is fully available (plugin skills
+		// aren't governed by skillOverrides — managed via /plugins).
+		const plugin = discoverPlugins(defaultDiscoverRoots(agentDir, cwd, home)).skills.map((skill) => ({
 			name: skill.name,
+			description: readDescription(skill.path),
 			path: skill.path,
 			source: "plugin" as const,
-		})),
-	];
-
-	const describe = () => {
-		const all = index();
-		if (all.length === 0) return "(no skills available)";
-		return all
-			.map((skill) => `- ${skill.name}${skill.description ? `: ${skill.description.split("\n")[0]}` : ""}`)
-			.join("\n");
+			scope: "plugin" as const,
+			state: "on" as const,
+			pluginName: skill.plugin,
+		}));
+		return [...project, ...plugin];
 	};
 
+	const describe = () => skillListingText(index());
+
 	pi.registerTool({
 		name: "skill",
 		label: "Skill",
@@ -83,7 +174,7 @@ export default function skillExtension(pi: ExtensionAPI) {
 			result: (_r, a, isError) => (isError ? undefined : a?.skill ? `Loaded ${a.skill}` : undefined),
 		}),
 		description:
-			"Invoke a skill: a packaged set of instructions for a particular kind of task. Call this when the task at hand matches an available skill, or when the user asks for one by name (including `/<name>`). Returns the skill's instructions to follow. Plugin skills are named `<plugin>:<skill>`. Use `list` to see what is available.",
+			"Invoke a skill.\n\nA skill is a packaged set of instructions the user or project has set up for a particular kind of task (deploy steps, a review checklist, a repo-specific workflow). Available skills appear in a system-reminder listing with one-line descriptions. When the task at hand is one a listed skill covers, call this tool first — the skill's instructions load into the turn for you to follow in place of your default approach. Users may also ask for one by name (`/<name>`, or \"slash command\"); that's a request to invoke it.\n\n- `skill`: exact name from the listing, no leading slash. Plugin skills are named `<plugin>:<skill>`.\n- `args`: optional arguments to pass through.\n\nOnly names from the listing (or that the user typed explicitly) are valid. Built-in CLI commands (`/help`, `/clear`, …) aren't skills. Use `list` to see what is available.",
 		promptSnippet: "Load packaged instructions for a task (see the skills listing)",
 		parameters: Type.Object({
 			skill: Type.Optional(Type.String({ description: "Exact skill name, no leading slash" })),
@@ -96,10 +187,11 @@ export default function skillExtension(pi: ExtensionAPI) {
 			// name the skill — fail loudly rather than silently returning the
 			// catalog, which a weak model reads as a non-sequitur (same archetype as
 			// the subagent tool; see docs/decisions/subagents-workflows.md).
+			const all = index();
 			if (params.list || (!params.skill && params.args == null)) {
 				return {
-					content: [{ type: "text", text: `Available skills:\n${describe()}` }],
-					details: { skills: index().map((s) => s.name) } as Record<string, unknown>,
+					content: [{ type: "text", text: `Available skills:\n${skillListingText(all)}` }],
+					details: { skills: all.map((s) => s.name) } as Record<string, unknown>,
 				};
 			}
 			if (!params.skill) {
@@ -107,7 +199,7 @@ export default function skillExtension(pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text",
-							text: `No \`skill\` given, but you passed \`args\` — this looks like an invocation that forgot to name the skill. Set \`skill\` to one of the names below, or call with \`list: true\` to just browse.\n\nAvailable skills:\n${describe()}`,
+							text: `No \`skill\` given, but you passed \`args\` — this looks like an invocation that forgot to name the skill. Set \`skill\` to one of the names below, or call with \`list: true\` to just browse.\n\nAvailable skills:\n${skillListingText(all)}`,
 						},
 					],
 					details: {} as Record<string, unknown>,
@@ -116,24 +208,40 @@ export default function skillExtension(pi: ExtensionAPI) {
 			}
 
 			const wanted = params.skill.replace(/^\//, "");
-			const all = index();
-			const found =
-				all.find((skill) => skill.name === wanted) ??
-				all.find((skill) => skill.name.toLowerCase() === wanted.toLowerCase()) ??
-				// A bare name matches a plugin skill when it is unambiguous.
-				all.find((skill) => skill.name.endsWith(`:${wanted}`));
+			// A bare name may match a plugin skill (`<plugin>:<name>`), but only
+			// when exactly one plugin ships it — otherwise resolving silently would
+			// run an arbitrary one, so ask which.
+			const bareMatches = bareSkillMatches(all, wanted);
+			const found = resolveSkill(all, wanted);
 
 			if (!found) {
+				const ambiguous = bareMatches.length > 1;
+				const text = ambiguous
+					? `"${params.skill}" is ambiguous — it matches ${bareMatches.map((s) => s.name).join(", ")}. Use the full \`<plugin>:${wanted}\` name.`
+					: `No skill named "${params.skill}".\n\nAvailable skills:\n${skillListingText(all)}`;
 				return {
-					content: [{ type: "text", text: `No skill named "${params.skill}".\n\nAvailable skills:\n${describe()}` }],
+					content: [{ type: "text", text }],
 					details: {} as Record<string, unknown>,
 					isError: true,
 				};
 			}
 
+			// "off" is the only state that refuses invocation (matching Claude Code,
+			// where invoking an off skill by name returns the skillOverrides error).
+			// "user-only" is invocable — it's just hidden from the model's listing,
+			// so the model won't auto-trigger it, but /skill-name still runs it.
+			if (found.state === "off") {
+				const where = found.source === "plugin" ? "/plugins" : "/skills";
+				return {
+					content: [{ type: "text", text: `Skill "${found.name}" is turned off — the user can re-enable it from ${where}.` }],
+					details: { skill: found.name, state: found.state } as Record<string, unknown>,
+					isError: true,
+				};
+			}
+
 			let body: string;
 			try {
-				const parsed = parseFrontmatter(readFileSync(found.path, "utf-8")) as { body: string };
+				const parsed = parseFrontmatterLoosely(readFileSync(found.path, "utf-8")) as { body: string };
 				body = parsed.body.trim();
 			} catch (error) {
 				return {
@@ -143,6 +251,8 @@ export default function skillExtension(pi: ExtensionAPI) {
 				};
 			}
 
+			recordUsage(pluginRoot(getAgentDir()), "skill", found.name);
+
 			// Resource paths in a skill are relative to its own directory, so the
 			// model needs to know where it lives to read references/ or scripts/.
 			const header = [
@@ -161,10 +271,226 @@ export default function skillExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	/**
+	 * Run a resolved skill the way a user-typed command does: refuse an "off"
+	 * skill (in EVERY mode — falling through would hand `/skill:` to pi's native
+	 * expansion, which knows nothing of the overrides store and would run it; a
+	 * headless run gets the refusal as a next-turn reminder instead of a UI
+	 * notice, never as silent execution), else re-deliver pi's exact `<skill>`
+	 * block as a hidden custom message. The model receives the same bytes pi's
+	 * own expansion would submit as a user turn (convertToLlm maps a custom
+	 * message to a user message regardless of `display`), but nothing renders.
+	 * Shared by the `/skill:<name>` interception and the bare `/<name>` commands.
+	 */
+	const deliverSkill = (
+		found: IndexedSkill,
+		args: string,
+		ctx: { hasUI: boolean; ui: { notify(message: string, level: "info" | "warning" | "error"): void } },
+		extra: { images?: Array<{ type: "image"; data: string; mimeType: string }>; streamingBehavior?: "steer" | "followUp" } = {},
+	): "handled" | "unavailable" => {
+		if (found.state === "off") {
+			const where = found.source === "plugin" ? "/plugins" : "/skills";
+			const message = `Skill "${found.name}" is turned off — enable it from ${where} to run it.`;
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			else pi.events.emit(REMINDER_CHANNEL, { text: message });
+			return "handled";
+		}
+		let body: string;
+		try {
+			body = stripFrontmatter(readFileSync(found.path, "utf-8")).trim();
+		} catch {
+			return "unavailable";
+		}
+		recordUsage(pluginRoot(getAgentDir()), "skill", found.name);
+		const block = buildSkillBlock({ name: found.name, filePath: found.path }, body, args);
+		// Carry any attached images alongside the block, as pi's native path would.
+		const content = extra.images?.length ? [{ type: "text" as const, text: block }, ...extra.images] : block;
+		pi.sendMessage(
+			{ customType: "one-code:skill-invocation", content, display: false, details: { skill: found.name, args } },
+			{ triggerTurn: true, ...(extra.streamingBehavior ? { deliverAs: extra.streamingBehavior } : {}) },
+		);
+		return "handled";
+	};
+
+	// A user-typed `/skill:<name>` normally runs pi's own expansion, which submits
+	// the skill's `<skill>` block as a *user message* — so loading a skill shows in
+	// the transcript as a new user turn. Intercept it here, suppress pi's
+	// expansion (return "handled"), and deliver through deliverSkill. An unknown
+	// name, an ambiguous plugin match, or an unreadable file falls through to
+	// pi's native handling. This hook only covers prompt(); paths that expand
+	// without an `input` event (steer/followUp) are caught by the context-hook
+	// redaction below.
+	pi.on("input", (event, ctx) => {
+		const cmd = parseSkillCommand(event.text);
+		if (!cmd) return { action: "continue" };
+		const found = resolveSkill(index(), cmd.name);
+		if (!found) return { action: "continue" };
+		const outcome = deliverSkill(found, cmd.args, ctx, {
+			images: event.images as Array<{ type: "image"; data: string; mimeType: string }> | undefined,
+			streamingBehavior: event.streamingBehavior,
+		});
+		return { action: outcome === "handled" ? "handled" : "continue" };
+	});
+
+	// Claude Code invokes a user/project skill as a bare `/<name>` (only plugin
+	// skills carry a `<plugin>:` prefix); pi registers `/skill:<name>`. Register
+	// each project/user/bundled skill as a bare extension command too, so
+	// `/simplify` works and autocompletes. pi runs extension commands before the
+	// `input` hook and before its own `/skill:`/template expansion — in prompt(),
+	// so interactive, `-p` and RPC alike — and emits session_start before it
+	// builds the autocomplete list, so aliases registered here are listed. A name
+	// another command already owns is skipped (pi would rename BOTH to `name:1`/
+	// `name:2`), as are pi's built-ins (matched by literal text before extensions
+	// see them) and `.claude/commands` templates (pi resolves those per turn,
+	// AFTER session_start, so they are pre-scanned from disk here — otherwise a
+	// bare skill command would shadow a same-named template for the whole
+	// session); those skills keep only their `/skill:` form. Commands can never
+	// be unregistered, so the handler resolves the skill afresh at invocation:
+	// a skill deleted or turned off since registration is refused, never run.
+	const registeredSkillCommands = new Set<string>();
+	const registerSkillCommands = (cwd: string | undefined) => {
+		let taken: string[];
+		try {
+			taken = pi.getCommands().map((command) => command.name);
+		} catch {
+			return; // not bound yet (load time) — session_start retries
+		}
+		const templates = promptTemplateNames(cwd ?? process.cwd(), os.homedir(), getAgentDir());
+		for (const skill of skillCommandCandidates(index(cwd), [...taken, ...templates, ...registeredSkillCommands])) {
+			registeredSkillCommands.add(skill.name);
+			pi.registerCommand(skill.name, {
+				description: skill.description ? `${skill.description} (skill)` : `Run the ${skill.name} skill`,
+				handler: async (args, ctx) => {
+					const found = resolveSkill(index(ctx.cwd), skill.name);
+					if (!found || deliverSkill(found, args.trim(), ctx) === "unavailable") {
+						ctx.ui.notify(`Skill "${skill.name}" is no longer available (its SKILL.md was removed or is unreadable).`, "error");
+					}
+				},
+			});
+		}
+	};
+	pi.on("session_start", (_event, ctx) => registerSkillCommands(ctx.cwd));
+	// pi's per-turn resolution (frontmatter `name`, description required) can
+	// surface skills the pre-turn disk scan missed; late registrations still
+	// execute (autocomplete lists them after a /reload). Gated on an unseen
+	// name so the steady state costs one Set lookup per skill per turn, not a
+	// re-index (before_agent_start runs every turn).
+	pi.on("before_agent_start", (_event, ctx) => {
+		if (piSkills.some((skill) => !registeredSkillCommands.has(skill.name))) registerSkillCommands(ctx.cwd);
+	});
+
+	// Fail-closed backstop for the `input` interception above: pi's steer() and
+	// followUp() expand `/skill:<name>` natively WITHOUT firing an `input` event
+	// (queued interactive messages after the first, RPC steer/followUp), so a
+	// turned-off skill's instructions can land in the session history anyway.
+	// Strip them from every outgoing request instead — the wire copy carries the
+	// refusal notice, the session file keeps the original bytes, and untouched
+	// requests return undefined so the message array stays byte-identical
+	// (prompt-cache stable). Override states are read lazily, only when a
+	// message actually contains a `<skill>` block.
+	pi.on("context", (event) => {
+		let states: Map<string, string> | undefined;
+		const isOff = (name: string) => {
+			states ??= new Map(index().map((skill) => [skill.name, skill.state]));
+			return states.get(name) === "off";
+		};
+		const redacted = redactOffSkillMessages(event.messages, isOff);
+		return redacted ? { messages: redacted } : undefined;
+	});
+
+	const buildSkillsRows = (cwd: string | undefined): SkillsRow[] =>
+		index(cwd).map((skill) => ({
+			key: skillOverrideKey(skill.scope, skill.name),
+			name: skill.name,
+			scope: skill.scope,
+			tokens: estimateSkillTokens(skill.path),
+			state: skill.state,
+			locked: skill.source === "plugin",
+			pluginName: skill.pluginName,
+		}));
+
+	// The /skills panel: a bounded dock (like /plugins) that cycles each
+	// project/user skill through on / name-only / user-only / off, persisting to
+	// the skill-overrides store live. Plugin skills show locked (managed via
+	// /plugins). Pure state/render live in ./panel; this owns repaint + writes.
+	const openSkillsPanel = async (ctx: ExtensionContext): Promise<void> => {
+		await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+			const paint: SkillsPaint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
+			const state = initialSkillsState();
+			let rows = buildSkillsRows(ctx.cwd);
+			let notice: string | undefined;
+			let cache: { width: number; lines: string[] } | undefined;
+			const repaint = () => {
+				cache = undefined;
+				tui.requestRender();
+			};
+			return {
+				render: (width: number) => {
+					if (cache?.width === width) return cache.lines;
+					const termRows = (tui as { terminal: { rows: number } }).terminal.rows;
+					const height = boundedDockHeight(termRows, SKILLS_PANEL_MAX_HEIGHT);
+					const lines = renderSkillsPanel({ state, rows, width, height, notice }, paint).map((line) =>
+						truncateLine(line, width),
+					);
+					cache = { width, lines };
+					return lines;
+				},
+				handleInput: (data: string) => {
+					const key = decodeSkillsKey(data);
+					if (!key) return;
+					const before = visibleRows(rows, state);
+					const anchorKey = before[state.cursor]?.key;
+					const sortBefore = state.sort;
+					const effect = applySkillsKey(state, key, before);
+					notice = undefined;
+					if (effect?.kind === "close") {
+						done(null);
+						return;
+					}
+					if (effect?.kind === "cycle") {
+						// The toggle changes only the state; token/scope/name are stable,
+						// so patch the one row instead of rescanning every skill from disk.
+						const next = nextSkillState(effect.row.state);
+						setSkillState(pluginRoot(getAgentDir()), effect.row.key, next);
+						rows = rows.map((row) => (row.key === effect.row.key ? { ...row, state: next } : row));
+					} else if (effect?.kind === "locked") {
+						notice = `${effect.row.name} is a plugin skill — manage it from /plugins.`;
+					}
+					// A sort toggle reorders the list; keep the same skill selected so a
+					// following Space acts on the row the user was looking at, not the one
+					// that slid into its index.
+					if (state.sort !== sortBefore && anchorKey) {
+						const idx = visibleRows(rows, state).findIndex((row) => row.key === anchorKey);
+						if (idx >= 0) state.cursor = idx;
+					}
+					repaint();
+				},
+				invalidate: () => {
+					cache = undefined;
+				},
+			};
+		});
+	};
+
 	pi.registerCommand("skills", {
-		description: "List available skills",
+		description: "View and manage skills (on / name-only / user-only / off)",
 		handler: async (_args, ctx) => {
-			ctx.ui.notify(`Available skills:\n${describe()}`, "info");
+			if (ctx.hasUI) {
+				await openSkillsPanel(ctx);
+				return;
+			}
+			// Non-interactive fallback: a flat listing with each skill's state.
+			const all = index(ctx.cwd);
+			if (all.length === 0) {
+				ctx.ui.notify("No skills available.", "info");
+				return;
+			}
+			const lines = all.map((skill) => {
+				const label = skill.source === "plugin" ? "plugin" : skill.state;
+				const desc = skill.description ? `: ${skill.description.split("\n")[0]}` : "";
+				return `- ${skill.name} [${label}]${desc}`;
+			});
+			ctx.ui.notify(`Skills:\n${lines.join("\n")}`, "info");
 		},
 	});
 }

package/extensions/skill/invoke.ts

@@ -0,0 +1,185 @@
+/**
+ * User-invoked skill commands (pure). pi registers each skill as a `/skill:<name>`
+ * slash command and, on invocation, expands it into a `<skill>` block that it
+ * submits as a *user message* — so loading a skill shows up in the transcript as
+ * a new user turn. One Code intercepts that command in the `input` hook and
+ * re-delivers the same block as a hidden message instead (see index.ts), so the
+ * model receives byte-identical content but nothing renders.
+ *
+ * These helpers mirror pi's own `_expandSkillCommand`/`formatSkillInvocation`
+ * exactly (same `/skill:` prefix, same block template) so the model sees the same
+ * bytes it would have without the interception — only the display changes.
+ */
+
+import { dirname } from "node:path";
+
+const SKILL_PREFIX = "/skill:";
+
+/** Parse a `/skill:<name> [args]` command; undefined if it is not one. */
+export function parseSkillCommand(text: string): { name: string; args: string } | undefined {
+	if (!text.startsWith(SKILL_PREFIX)) return undefined;
+	const rest = text.slice(SKILL_PREFIX.length);
+	const space = rest.indexOf(" ");
+	if (space === -1) return { name: rest, args: "" };
+	return { name: rest.slice(0, space), args: rest.slice(space + 1).trim() };
+}
+
+/** Skills whose name ends `:<wanted>` — a bare name's plugin-namespaced matches. */
+export function bareSkillMatches<T extends { name: string }>(all: T[], wanted: string): T[] {
+	return all.filter((skill) => skill.name.endsWith(`:${wanted}`));
+}
+
+/**
+ * Resolve a bare skill name against the available skills, matching the Skill
+ * tool's own resolution: exact, then case-insensitive, then a unique
+ * `<plugin>:<name>` suffix. Returns undefined when nothing matches or a bare
+ * name is ambiguous across plugins (so the caller falls back to pi's handling).
+ */
+export function resolveSkill<T extends { name: string }>(all: T[], wanted: string): T | undefined {
+	const bare = bareSkillMatches(all, wanted);
+	return (
+		all.find((skill) => skill.name === wanted) ??
+		all.find((skill) => skill.name.toLowerCase() === wanted.toLowerCase()) ??
+		(bare.length === 1 ? bare[0] : undefined)
+	);
+}
+
+/**
+ * Rebuild the exact `<skill>` block pi's `/skill:` expansion produces. `body` is
+ * the SKILL.md with frontmatter already stripped and trimmed; `filePath` is the
+ * skill file (its directory is the base for relative references, as pi does).
+ */
+export function buildSkillBlock(skill: { name: string; filePath: string }, body: string, args: string): string {
+	const block = `<skill name="${skill.name}" location="${skill.filePath}">
+References are relative to ${dirname(skill.filePath)}.
+
+${body}
+</skill>`;
+	return args ? `${block}\n\n${args}` : block;
+}
+
+/** Fast pre-check before the regex walk; also the marker `redactOffSkillText` scans for. */
+const SKILL_BLOCK_START = '<skill name="';
+const SKILL_BLOCK_RE = /<skill name="([^"]+)"[^>]*>[\s\S]*?<\/skill>/g;
+
+export const offSkillNotice = (name: string): string =>
+	`[Skill "${name}" is turned off — its instructions were removed. The user can re-enable it from /skills or /plugins.]`;
+
+/**
+ * Replace every `<skill>` block belonging to a turned-off skill with a short
+ * refusal notice. Returns the rewritten text, or undefined when nothing
+ * needed redacting (so callers keep the original object untouched).
+ *
+ * This is the fail-closed backstop behind the `input`-hook interception:
+ * pi's `steer()`/`followUp()` expand `/skill:<name>` natively WITHOUT firing
+ * the `input` event (queued interactive messages after the first, RPC
+ * steer/followUp), so an off skill's instructions can land in the session
+ * history. Redacting on the `context` hook strips them from every outgoing
+ * request — the session file keeps the original bytes, and the rewrite is
+ * deterministic for a fixed override state, so the request prefix stays
+ * byte-stable across turns (prompt-cache friendly).
+ */
+export function redactOffSkillText(text: string, isOff: (name: string) => boolean): string | undefined {
+	if (!text.includes(SKILL_BLOCK_START)) return undefined;
+	let changed = false;
+	const redacted = text.replace(SKILL_BLOCK_RE, (block, name: string) => {
+		if (!isOff(name)) return block;
+		changed = true;
+		return offSkillNotice(name);
+	});
+	return changed ? redacted : undefined;
+}
+
+/**
+ * Apply redactOffSkillText across a request's messages (user and custom roles,
+ * string or text-block content). Returns a rewritten copy, or undefined when
+ * no message needed redacting — callers must then keep the original array so
+ * untouched requests stay byte-identical.
+ */
+export function redactOffSkillMessages<M extends { role: string; content?: unknown }>(
+	messages: readonly M[],
+	isOff: (name: string) => boolean,
+): M[] | undefined {
+	let changed = false;
+	const out = messages.map((message) => {
+		if (message.role !== "user" && message.role !== "custom") return message;
+		if (typeof message.content === "string") {
+			const redacted = redactOffSkillText(message.content, isOff);
+			if (redacted === undefined) return message;
+			changed = true;
+			return { ...message, content: redacted };
+		}
+		if (!Array.isArray(message.content)) return message;
+		let blockChanged = false;
+		const blocks = message.content.map((block: { type?: string; text?: string }) => {
+			if (block?.type !== "text" || typeof block.text !== "string") return block;
+			const redacted = redactOffSkillText(block.text, isOff);
+			if (redacted === undefined) return block;
+			blockChanged = true;
+			return { ...block, text: redacted };
+		});
+		if (!blockChanged) return message;
+		changed = true;
+		return { ...message, content: blocks };
+	});
+	return changed ? out : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Bare `/<skill>` commands (Claude Code's invocation shape)
+
+/**
+ * pi's interactive built-ins, matched by literal text before anything reaches
+ * an extension — a skill of the same name can never be invoked bare, so no
+ * alias is registered for it (its `/skill:<name>` form still works).
+ */
+export const PI_BUILTIN_COMMANDS: ReadonlySet<string> = new Set([
+	"changelog",
+	"clone",
+	"compact",
+	"copy",
+	"debug",
+	"export",
+	"fork",
+	"hotkeys",
+	"import",
+	"login",
+	"logout",
+	"model",
+	"name",
+	"new",
+	"quit",
+	"reload",
+	"resume",
+	"scoped-models",
+	"session",
+	"settings",
+	"share",
+	"thinking",
+	"tree",
+	"trust",
+]);
+
+/** A skill name that can be a bare slash command: one token, no `:` (plugin skills stay `<plugin>:<skill>`, as in Claude Code). */
+export function isBareCommandName(name: string): boolean {
+	return /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name);
+}
+
+/**
+ * Which skills get a bare `/<name>` command, given the command names already
+ * taken (other extensions' commands, `.claude/commands` templates, pi's
+ * built-ins). Plugin skills are excluded (they keep `<plugin>:<skill>`), a
+ * name already taken keeps its owner (first-registered command wins; pi would
+ * otherwise rename BOTH to `name:1`/`name:2`), and a duplicate skill name
+ * registers once. Pure, so the collision policy is testable.
+ */
+export function skillCommandCandidates<T extends { name: string; source: string }>(skills: T[], taken: Iterable<string>): T[] {
+	const used = new Set<string>([...taken, ...PI_BUILTIN_COMMANDS]);
+	const out: T[] = [];
+	for (const skill of skills) {
+		if (skill.source === "plugin" || !isBareCommandName(skill.name) || used.has(skill.name)) continue;
+		used.add(skill.name);
+		out.push(skill);
+	}
+	return out;
+}