gsd-pi 2.38.0-dev.eeb3520 → 2.39.0-dev.20aba06

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "description": "Coding agent CLI (vendored from pi-mono)",
   "type": "module",
   "piConfig": {

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -25,6 +25,7 @@ import type {
 } from "@gsd/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@gsd/pi-ai";
 import { modelsAreEqual, resetApiProviders, supportsXhigh } from "@gsd/pi-ai";
+import { Type } from "@sinclair/typebox";
 import { getDocsPath } from "../config.js";
 import { getErrorMessage } from "../utils/error.js";
 import { theme } from "../modes/interactive/theme/theme.js";
@@ -732,9 +733,10 @@ export class AgentSession {
 	 * Changes take effect on the next agent turn.
 	 */
 	setActiveToolsByName(toolNames: string[]): void {
+		const requestedToolNames = [...new Set([...toolNames, ...this._getBuiltinToolNames()])];
 		const tools: AgentTool[] = [];
 		const validToolNames: string[] = [];
-		for (const name of toolNames) {
+		for (const name of requestedToolNames) {
 			const tool = this._toolRegistry.get(name);
 			if (tool) {
 				tools.push(tool);
@@ -743,6 +745,7 @@ export class AgentSession {
 		}
 		this.agent.setTools(tools);
 
+
 		// Rebuild base system prompt with new tool set
 		this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
 		this.agent.setSystemPrompt(this._baseSystemPrompt);
@@ -858,6 +861,48 @@ export class AgentSession {
 		return Array.from(unique);
 	}
 
+	private _findSkillByName(skillName: string) {
+		return this.resourceLoader.getSkills().skills.find((skill) => skill.name === skillName);
+	}
+
+	private _formatMissingSkillMessage(skillName: string): string {
+		const availableSkills = this.resourceLoader.getSkills().skills.map((skill) => skill.name).join(", ") || "(none)";
+		return `Skill "${skillName}" not found. Available skills: ${availableSkills}`;
+	}
+
+	private _emitSkillExpansionError(skillFilePath: string, err: unknown): void {
+		this._extensionRunner?.emitError({
+			extensionPath: skillFilePath,
+			event: "skill_expansion",
+			error: getErrorMessage(err),
+		});
+	}
+
+	private _renderSkillInvocation(skill: { name: string; filePath: string; baseDir: string }, args?: string): string {
+		const content = readFileSync(skill.filePath, "utf-8");
+		const body = stripFrontmatter(content).trim();
+		const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+		return args && args.trim() ? `${skillBlock}\n\n${args.trim()}` : skillBlock;
+	}
+
+	private _expandSkillByName(skillName: string, args?: string): string {
+		const skill = this._findSkillByName(skillName);
+		if (!skill) {
+			throw new Error(this._formatMissingSkillMessage(skillName));
+		}
+
+		try {
+			return this._renderSkillInvocation(skill, args);
+		} catch (err) {
+			this._emitSkillExpansionError(skill.filePath, err);
+			throw err;
+		}
+	}
+
+	private _formatSkillInvocation(skillName: string, args?: string): string {
+		return this._expandSkillByName(skillName, args);
+	}
+
 	private _rebuildSystemPrompt(toolNames: string[]): string {
 		const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
 		const toolSnippets: Record<string, string> = {};
@@ -1103,25 +1148,78 @@ export class AgentSession {
 		const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
 		const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
 
-		const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);
-		if (!skill) return text; // Unknown skill, pass through
+		if (!this._findSkillByName(skillName)) return text;
 
 		try {
-			const content = readFileSync(skill.filePath, "utf-8");
-			const body = stripFrontmatter(content).trim();
-			const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
-			return args ? `${skillBlock}\n\n${args}` : skillBlock;
-		} catch (err) {
-			// Emit error like extension commands do
-			this._extensionRunner?.emitError({
-				extensionPath: skill.filePath,
-				event: "skill_expansion",
-				error: getErrorMessage(err),
-			});
-			return text; // Return original on error
+			return this._formatSkillInvocation(skillName, args);
+		} catch {
+			return text;
 		}
 	}
 
+	private _createBuiltInSkillTool(): AgentTool {
+		const skillSchema = Type.Object({
+			skill: Type.String({ description: "The skill name. E.g., 'commit', 'review-pr', or 'pdf'" }),
+			args: Type.Optional(Type.String({ description: "Optional arguments for the skill" })),
+		});
+
+		return {
+			name: "Skill",
+			label: "Skill",
+			description:
+				"Execute a skill within the main conversation. Use this tool when users ask for a slash command or reference a skill by name. Returns the expanded skill block and appends args after it.",
+			parameters: skillSchema,
+			execute: async (_toolCallId, params: unknown) => {
+				const input = params as { skill: string; args?: string };
+				try {
+					return {
+						content: [
+							{
+								type: "text",
+								text: this._expandSkillByName(input.skill, input.args),
+							},
+						],
+						details: undefined,
+					};
+				} catch (err) {
+					return {
+						content: [{ type: "text", text: getErrorMessage(err) }],
+						details: undefined,
+					};
+				}
+			},
+		};
+	}
+
+	private _getBuiltinToolNames(): string[] {
+		return this._getBuiltinTools().map((tool) => tool.name);
+	}
+
+	private _getBuiltinTools(): AgentTool[] {
+		return [this._createBuiltInSkillTool()];
+	}
+
+	private _getRegisteredToolDefinitions(): ToolDefinition[] {
+		const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+		return registeredTools.map((tool) => tool.definition);
+	}
+
+	private _getBuiltinToolDefinitions(): ToolDefinition[] {
+		return this._getBuiltinTools().map((tool) => ({
+			name: tool.name,
+			label: tool.label,
+			description: tool.description,
+			parameters: tool.parameters,
+			execute: async () => ({ content: [], details: undefined }),
+		}));
+	}
+
+	getRenderableToolDefinition(toolName: string): ToolDefinition | undefined {
+		return [...this._getBuiltinToolDefinitions(), ...this._getRegisteredToolDefinitions()].find(
+			(tool) => tool.name === toolName,
+		);
+	}
+
 	/**
 	 * Queue a steering message to interrupt the agent mid-run.
 	 * Delivered after current tool execution, skips remaining tools.
@@ -1967,8 +2065,12 @@ export class AgentSession {
 		const wrappedExtensionTools = this._extensionRunner
 			? wrapRegisteredTools(allCustomTools, this._extensionRunner)
 			: [];
+		const builtinTools = this._getBuiltinTools();
 
 		const toolRegistry = new Map(this._baseToolRegistry);
+		for (const tool of builtinTools) {
+			toolRegistry.set(tool.name, tool);
+		}
 		for (const tool of wrappedExtensionTools as AgentTool[]) {
 			toolRegistry.set(tool.name, tool);
 		}
@@ -2694,14 +2796,11 @@ export class AgentSession {
 	async exportToHtml(outputPath?: string): Promise<string> {
 		const themeName = this.settingsManager.getTheme();
 
-		// Create tool renderer if we have an extension runner (for custom tool HTML rendering)
-		let toolRenderer: ToolHtmlRenderer | undefined;
-		if (this._extensionRunner) {
-			toolRenderer = createToolHtmlRenderer({
-				getToolDefinition: (name) => this._extensionRunner!.getToolDefinition(name),
-				theme,
-			});
-		}
+		// Create tool renderer for extension and built-in tool HTML rendering
+		const toolRenderer = createToolHtmlRenderer({
+			getToolDefinition: (name) => this.getRenderableToolDefinition(name),
+			theme,
+		});
 
 		return await exportSessionToHtml(this.sessionManager, this.state, {
 			outputPath,

package/packages/pi-coding-agent/src/core/extensions/loader.ts

@@ -23,6 +23,12 @@ import * as _bundledYaml from "yaml";
 import * as _bundledMcpClient from "@modelcontextprotocol/sdk/client";
 import * as _bundledMcpStdio from "@modelcontextprotocol/sdk/client/stdio.js";
 import * as _bundledMcpStreamableHttp from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import * as _bundledMcpSse from "@modelcontextprotocol/sdk/client/sse.js";
+import * as _bundledMcpServer from "@modelcontextprotocol/sdk/server";
+import * as _bundledMcpServerStdio from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as _bundledMcpServerSse from "@modelcontextprotocol/sdk/server/sse.js";
+import * as _bundledMcpServerStreamableHttp from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import * as _bundledMcpTypes from "@modelcontextprotocol/sdk/types.js";
 import { getAgentDir, isBunBinary } from "../../config.js";
 // NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,
 // avoiding a circular dependency. Extensions can import from @gsd/pi-coding-agent.
@@ -44,8 +50,11 @@ import type {
 	ToolDefinition,
 } from "./types.js";
 
-/** Modules available to extensions via virtualModules (for compiled Bun binary) */
-const VIRTUAL_MODULES: Record<string, unknown> = {
+/**
+ * Statically imported modules for Bun binary virtualModules.
+ * Maps specifier -> module object for subpaths that must be available in compiled binaries.
+ */
+const STATIC_BUNDLED_MODULES: Record<string, unknown> = {
 	"@sinclair/typebox": _bundledTypebox,
 	"@gsd/pi-agent-core": _bundledPiAgentCore,
 	"@gsd/pi-tui": _bundledPiTui,
@@ -58,6 +67,17 @@ const VIRTUAL_MODULES: Record<string, unknown> = {
 	"@modelcontextprotocol/sdk/client/stdio.js": _bundledMcpStdio,
 	"@modelcontextprotocol/sdk/client/streamableHttp": _bundledMcpStreamableHttp,
 	"@modelcontextprotocol/sdk/client/streamableHttp.js": _bundledMcpStreamableHttp,
+	"@modelcontextprotocol/sdk/client/sse": _bundledMcpSse,
+	"@modelcontextprotocol/sdk/client/sse.js": _bundledMcpSse,
+	"@modelcontextprotocol/sdk/server": _bundledMcpServer,
+	"@modelcontextprotocol/sdk/server/stdio": _bundledMcpServerStdio,
+	"@modelcontextprotocol/sdk/server/stdio.js": _bundledMcpServerStdio,
+	"@modelcontextprotocol/sdk/server/sse": _bundledMcpServerSse,
+	"@modelcontextprotocol/sdk/server/sse.js": _bundledMcpServerSse,
+	"@modelcontextprotocol/sdk/server/streamableHttp": _bundledMcpServerStreamableHttp,
+	"@modelcontextprotocol/sdk/server/streamableHttp.js": _bundledMcpServerStreamableHttp,
+	"@modelcontextprotocol/sdk/types": _bundledMcpTypes,
+	"@modelcontextprotocol/sdk/types.js": _bundledMcpTypes,
 	// Aliases for external PI ecosystem packages that import from the original scope
 	"@mariozechner/pi-agent-core": _bundledPiAgentCore,
 	"@mariozechner/pi-tui": _bundledPiTui,
@@ -66,9 +86,198 @@ const VIRTUAL_MODULES: Record<string, unknown> = {
 	"@mariozechner/pi-coding-agent": _bundledPiCodingAgent,
 };
 
+/** Modules available to extensions via virtualModules (for compiled Bun binary) */
+const VIRTUAL_MODULES: Record<string, unknown> = { ...STATIC_BUNDLED_MODULES };
+
 const require = createRequire(import.meta.url);
 const EXTENSION_TIMING_ENABLED = process.env.GSD_STARTUP_TIMING === "1" || process.env.PI_TIMING === "1";
 
+/**
+ * Bundled npm packages whose subpath exports should be auto-resolved for extensions.
+ * Each package listed here will have its `exports` field read from package.json,
+ * and all subpath exports will be registered as jiti aliases (Node.js mode) so that
+ * extensions can import any standard subpath without hitting jiti's CJS double-resolve bug.
+ */
+const BUNDLED_PACKAGES_WITH_EXPORTS = [
+	"@modelcontextprotocol/sdk",
+	"yaml",
+];
+
+/**
+ * Read a package's `exports` field and return alias entries mapping
+ * specifiers (e.g. `@modelcontextprotocol/sdk/server`) to resolved file paths.
+ *
+ * Handles:
+ * - Explicit subpath exports: `./client` -> `@pkg/client`
+ * - Wildcard exports (`./*`): scans the package's dist directory for actual files
+ * - Both `.js`-suffixed and bare specifiers for each subpath
+ */
+function resolveSubpathExports(packageName: string): Record<string, string> {
+	const aliases: Record<string, string> = {};
+
+	let packageJsonPath: string;
+	try {
+		// Resolve the package's root directory via its package.json
+		packageJsonPath = require.resolve(`${packageName}/package.json`);
+	} catch {
+		// Package doesn't allow importing package.json via exports — find it manually
+		try {
+			const anyEntry = require.resolve(packageName);
+			// Walk up from the resolved entry to find package.json
+			let dir = path.dirname(anyEntry);
+			while (dir !== path.dirname(dir)) {
+				const candidate = path.join(dir, "package.json");
+				if (fs.existsSync(candidate)) {
+					try {
+						const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+						if (pkg.name === packageName) {
+							packageJsonPath = candidate;
+							break;
+						}
+					} catch {
+						// not valid JSON, keep walking
+					}
+				}
+				dir = path.dirname(dir);
+			}
+		} catch {
+			return aliases;
+		}
+		if (!packageJsonPath!) return aliases;
+	}
+
+	let pkg: { exports?: Record<string, unknown> };
+	try {
+		pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+	} catch {
+		return aliases;
+	}
+
+	const exports = pkg.exports;
+	if (!exports || typeof exports !== "object") return aliases;
+
+	const packageDir = path.dirname(packageJsonPath);
+
+	for (const [subpath, target] of Object.entries(exports)) {
+		if (subpath === ".") continue; // Root export handled by static imports
+
+		// Handle wildcard exports like "./*"
+		if (subpath.includes("*")) {
+			resolveWildcardExports(packageName, packageDir, subpath, target, aliases);
+			continue;
+		}
+
+		// Explicit subpath: "./client" -> "@pkg/client"
+		const specifier = `${packageName}/${subpath.replace(/^\.\//, "")}`;
+
+		try {
+			const resolved = require.resolve(specifier);
+			aliases[specifier] = resolved;
+
+			// Add .js-suffixed variant if the specifier doesn't already end in .js
+			if (!specifier.endsWith(".js")) {
+				const jsSpecifier = `${specifier}.js`;
+				try {
+					const jsResolved = require.resolve(jsSpecifier);
+					aliases[jsSpecifier] = jsResolved;
+				} catch {
+					// .js variant doesn't resolve — that's fine
+				}
+			}
+
+			// Add bare variant (without .js) if it ends in .js
+			if (specifier.endsWith(".js")) {
+				const bareSpecifier = specifier.slice(0, -3);
+				try {
+					const bareResolved = require.resolve(bareSpecifier);
+					aliases[bareSpecifier] = bareResolved;
+				} catch {
+					// bare variant doesn't resolve — that's fine
+				}
+			}
+		} catch {
+			// Subpath doesn't resolve — skip it
+		}
+	}
+
+	return aliases;
+}
+
+/**
+ * Resolve wildcard export patterns (e.g. `./*`) by scanning the package's
+ * file structure to find all matching files and generate alias entries.
+ */
+function resolveWildcardExports(
+	packageName: string,
+	packageDir: string,
+	subpathPattern: string,
+	target: unknown,
+	aliases: Record<string, string>,
+): void {
+	// Extract the target directory pattern from the export target
+	// e.g. { "require": "./dist/cjs/*" } -> "dist/cjs"
+	let targetDir: string | null = null;
+
+	if (typeof target === "string") {
+		targetDir = target.replace(/\/\*$/, "").replace(/^\.\//, "");
+	} else if (target && typeof target === "object") {
+		const targetObj = target as Record<string, unknown>;
+		// Prefer "require" for CJS compatibility with jiti, fall back to "import"
+		const resolved = targetObj.require ?? targetObj.import ?? targetObj.default;
+		if (typeof resolved === "string") {
+			targetDir = resolved.replace(/\/\*$/, "").replace(/^\.\//, "");
+		}
+	}
+
+	if (!targetDir) return;
+
+	const fullTargetDir = path.join(packageDir, targetDir);
+	if (!fs.existsSync(fullTargetDir)) return;
+
+	// Scan for .js files and generate specifiers
+	const subpathPrefix = subpathPattern.replace(/\/?\*$/, "").replace(/^\.\//, "");
+	scanDirForExports(packageName, fullTargetDir, subpathPrefix, aliases);
+}
+
+/**
+ * Recursively scan a directory for .js files and register them as aliases.
+ */
+function scanDirForExports(
+	packageName: string,
+	dir: string,
+	relativePath: string,
+	aliases: Record<string, string>,
+): void {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		const entryRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+
+		if (entry.isDirectory()) {
+			// Skip examples/test directories — extensions don't need them
+			if (entry.name === "examples" || entry.name === "__tests__" || entry.name === "test") continue;
+			scanDirForExports(packageName, path.join(dir, entry.name), entryRelative, aliases);
+		} else if (entry.name.endsWith(".js") && !entry.name.endsWith(".d.js")) {
+			const filePath = path.join(dir, entry.name);
+			const specifier = `${packageName}/${entryRelative}`;
+			// Only add if not already covered by an explicit export
+			if (!(specifier in aliases)) {
+				aliases[specifier] = filePath;
+			}
+			// Also add bare (no .js) variant
+			const bareSpecifier = specifier.replace(/\.js$/, "");
+			if (!(bareSpecifier in aliases)) {
+				aliases[bareSpecifier] = filePath;
+			}
+		}
+	}
+}
+
 function logExtensionTiming(extensionPath: string, ms: number, outcome: "loaded" | "failed"): void {
 	if (!EXTENSION_TIMING_ENABLED) return;
 	console.error(`[startup] extension ${outcome}: ${extensionPath} (${ms}ms)`);
@@ -100,7 +309,19 @@ function getAliases(): Record<string, string> {
 		return fileURLToPath(import.meta.resolve(specifier));
 	};
 
+	// Auto-discover subpath exports from bundled npm packages.
+	// This ensures extensions can import any standard subpath (e.g. @modelcontextprotocol/sdk/server)
+	// without hitting jiti's CJS double-resolve bug.
+	const autoDiscovered: Record<string, string> = {};
+	for (const packageName of BUNDLED_PACKAGES_WITH_EXPORTS) {
+		const subpathAliases = resolveSubpathExports(packageName);
+		Object.assign(autoDiscovered, subpathAliases);
+	}
+
 	_aliases = {
+		// Auto-discovered subpath exports (lowest priority — overridden by manual entries below)
+		...autoDiscovered,
+		// Manual entries for workspace packages and packages needing special resolution
 		"@gsd/pi-coding-agent": packageIndex,
 		"@gsd/pi-agent-core": resolveWorkspaceOrImport("agent/dist/index.js", "@gsd/pi-agent-core"),
 		"@gsd/pi-tui": resolveWorkspaceOrImport("tui/dist/index.js", "@gsd/pi-tui"),
@@ -108,11 +329,6 @@ function getAliases(): Record<string, string> {
 		"@gsd/pi-ai/oauth": resolveWorkspaceOrImport("ai/dist/oauth.js", "@gsd/pi-ai/oauth"),
 		"@sinclair/typebox": typeboxRoot,
 		"yaml": yamlRoot,
-		"@modelcontextprotocol/sdk/client": require.resolve("@modelcontextprotocol/sdk/client"),
-		"@modelcontextprotocol/sdk/client/stdio": require.resolve("@modelcontextprotocol/sdk/client/stdio.js"),
-		"@modelcontextprotocol/sdk/client/stdio.js": require.resolve("@modelcontextprotocol/sdk/client/stdio.js"),
-		"@modelcontextprotocol/sdk/client/streamableHttp": require.resolve("@modelcontextprotocol/sdk/client/streamableHttp.js"),
-		"@modelcontextprotocol/sdk/client/streamableHttp.js": require.resolve("@modelcontextprotocol/sdk/client/streamableHttp.js"),
 		// Aliases for external PI ecosystem packages that import from the original scope
 		"@mariozechner/pi-coding-agent": packageIndex,
 		"@mariozechner/pi-agent-core": resolveWorkspaceOrImport("agent/dist/index.js", "@gsd/pi-agent-core"),

package/packages/pi-coding-agent/src/core/package-manager.ts

@@ -414,7 +414,13 @@ function resolveExtensionEntries(dir: string): string[] | null {
 	const packageJsonPath = join(dir, "package.json");
 	if (existsSync(packageJsonPath)) {
 		const manifest = readPiManifestFile(packageJsonPath);
-		if (manifest?.extensions?.length) {
+		if (manifest) {
+			// When a pi manifest exists, it is authoritative — don't fall through
+			// to index.ts/index.js auto-detection. This allows library directories
+			// (like cmux) to opt out by declaring "pi": {} with no extensions.
+			if (!manifest.extensions?.length) {
+				return null;
+			}
 			const entries: string[] = [];
 			for (const extPath of manifest.extensions) {
 				const resolvedExtPath = resolve(dir, extPath);
@@ -422,9 +428,7 @@ function resolveExtensionEntries(dir: string): string[] | null {
 					entries.push(resolvedExtPath);
 				}
 			}
-			if (entries.length > 0) {
-				return entries;
-			}
+			return entries.length > 0 ? entries : null;
 		}
 	}
 

package/packages/pi-coding-agent/src/core/skill-tool.test.ts

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+
+import { Agent } from "@gsd/pi-agent-core";
+import { AuthStorage } from "./auth-storage.js";
+import { AgentSession } from "./agent-session.js";
+import { ModelRegistry } from "./model-registry.js";
+import { DefaultResourceLoader } from "./resource-loader.js";
+import { SessionManager } from "./session-manager.js";
+import { SettingsManager } from "./settings-manager.js";
+
+let testDir: string;
+
+function writeSkill(cwd: string, name: string, description: string, body = `# ${name}\n`): string {
+	const skillDir = join(cwd, ".pi", "skills", name);
+	mkdirSync(skillDir, { recursive: true });
+	const skillPath = join(skillDir, "SKILL.md");
+	writeFileSync(skillPath, `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}`);
+	return skillPath;
+}
+
+describe("Skill tool", () => {
+	beforeEach(() => {
+		testDir = mkdtempSync(join(tmpdir(), "skill-tool-test-"));
+	});
+
+	afterEach(() => {
+		rmSync(testDir, { recursive: true, force: true });
+	});
+
+	async function createSession() {
+		const agentDir = join(testDir, "agent-home");
+		const authStorage = AuthStorage.inMemory({});
+		const modelRegistry = new ModelRegistry(authStorage, join(agentDir, "models.json"));
+		const settingsManager = SettingsManager.inMemory();
+		const resourceLoader = new DefaultResourceLoader({
+			cwd: testDir,
+			agentDir,
+			settingsManager,
+			noExtensions: true,
+			noPromptTemplates: true,
+			noThemes: true,
+		});
+		await resourceLoader.reload();
+
+		return new AgentSession({
+			agent: new Agent(),
+			sessionManager: SessionManager.inMemory(testDir),
+			settingsManager,
+			cwd: testDir,
+			resourceLoader,
+			modelRegistry,
+		});
+	}
+
+	it("resolves a project-level skill to the exact skill block format", async () => {
+		const skillPath = writeSkill(
+			testDir,
+			"swift-testing",
+			"Use for Swift Testing assertions and verification patterns.",
+			"# Swift Testing\nUse this skill.\n",
+		);
+		const session = await createSession();
+
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+
+		const result = await tool.execute("call-1", { skill: "swift-testing" });
+		assert.equal(
+			result.content[0]?.type === "text" ? result.content[0].text : "",
+			`<skill name="swift-testing" location="${skillPath}">\nReferences are relative to ${join(testDir, ".pi", "skills", "swift-testing")}.\n\n# Swift Testing\nUse this skill.\n</skill>`,
+		);
+	});
+
+	it("returns a helpful error for unknown skills", async () => {
+		writeSkill(testDir, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
+		const session = await createSession();
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+
+		const result = await tool.execute("call-2", { skill: "nonexistent" });
+		const message = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(message, /^Skill "nonexistent" not found\. Available skills: /);
+		assert.match(message, /swift-testing/);
+	});
+});

package/packages/pi-coding-agent/src/core/skills.ts

@@ -81,6 +81,12 @@ export interface LoadSkillsResult {
 	diagnostics: ResourceDiagnostic[];
 }
 
+let loadedSkills: Skill[] = [];
+
+export function getLoadedSkills(): Skill[] {
+	return [...loadedSkills];
+}
+
 /**
  * Validate skill name per Agent Skills spec.
  * Returns array of validation error messages (empty if valid).
@@ -293,7 +299,8 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
 
 	const lines = [
 		"\n\nThe following skills provide specialized instructions for specific tasks.",
-		"Use the read tool to load a skill's file when the task matches its description.",
+		"Use the Skill tool with the exact skill name from <available_skills> when the task matches its description.",
+		"If the Skill tool reports an unknown skill, do not guess: use an exact name from <available_skills> or tell the user the skill is unavailable.",
 		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
 		"",
 		"<available_skills>",
@@ -449,8 +456,10 @@ export function loadSkills(options: LoadSkillsOptions = {}): LoadSkillsResult {
 		}
 	}
 
+	loadedSkills = Array.from(skillMap.values());
+
 	return {
-		skills: Array.from(skillMap.values()),
+		skills: [...loadedSkills],
 		diagnostics: [...allDiagnostics, ...collisionDiagnostics],
 	};
 }

package/packages/pi-coding-agent/src/index.ts

@@ -213,6 +213,7 @@ export {
 // Skills
 export {
 	formatSkillsForPrompt,
+	getLoadedSkills,
 	type LoadSkillsFromDirOptions,
 	type LoadSkillsResult,
 	loadSkills,