@oh-my-pi/pi-coding-agent 13.2.0 → 13.3.0

package/src/discovery/mcp-json.ts

@@ -7,12 +7,12 @@
  * Priority: 5 (low, as this is a fallback after tool-specific providers)
  */
 import * as path from "node:path";
-import { logger } from "@oh-my-pi/pi-utils";
+import { logger, tryParseJson } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
 import { readFile } from "../capability/fs";
 import { type MCPServer, mcpCapability } from "../capability/mcp";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
-import { createSourceMeta, expandEnvVarsDeep, parseJSON } from "./helpers";
+import { createSourceMeta, expandEnvVarsDeep } from "./helpers";
 
 const PROVIDER_ID = "mcp-json";
 const DISPLAY_NAME = "MCP Config";
@@ -115,7 +115,7 @@ async function loadMCPJsonFile(
 		return { items, warnings };
 	}
 
-	const config = parseJSON<MCPConfigFile>(content);
+	const config = tryParseJson<MCPConfigFile>(content);
 	if (!config) {
 		warnings.push(`Failed to parse JSON in ${path}`);
 		return { items, warnings };

package/src/discovery/opencode.ts

@@ -16,7 +16,7 @@
  * Priority: 55 (tool-specific provider)
  */
 import * as path from "node:path";
-import { logger } from "@oh-my-pi/pi-utils";
+import { logger, tryParseJson } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
 import { type ContextFile, contextFileCapability } from "../capability/context-file";
 import { type ExtensionModule, extensionModuleCapability } from "../capability/extension-module";
@@ -35,8 +35,7 @@ import {
 	getProjectPath,
 	getUserPath,
 	loadFilesFromDir,
-	loadSkillsFromDir,
-	parseJSON,
+	scanSkillsFromDir,
 } from "./helpers";
 
 const PROVIDER_ID = "opencode";
@@ -51,7 +50,7 @@ async function loadJsonConfig(configPath: string): Promise<Record<string, unknow
 	const content = await readFile(configPath);
 	if (!content) return null;
 
-	const parsed = parseJSON<Record<string, unknown>>(content);
+	const parsed = tryParseJson<Record<string, unknown>>(content);
 	if (!parsed) {
 		logger.warn("Failed to parse OpenCode JSON config", { path: configPath });
 		return null;
@@ -190,7 +189,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 
 	if (userSkillsDir) {
 		promises.push(
-			loadSkillsFromDir(ctx, {
+			scanSkillsFromDir(ctx, {
 				dir: userSkillsDir,
 				providerId: PROVIDER_ID,
 				level: "user",
@@ -200,7 +199,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 
 	if (projectSkillsDir) {
 		promises.push(
-			loadSkillsFromDir(ctx, {
+			scanSkillsFromDir(ctx, {
 				dir: projectSkillsDir,
 				providerId: PROVIDER_ID,
 				level: "project",
@@ -307,7 +306,7 @@ async function loadSettings(ctx: LoadContext): Promise<LoadResult<Settings>> {
 	if (userConfigPath) {
 		const content = await readFile(userConfigPath);
 		if (content) {
-			const parsed = parseJSON<Record<string, unknown>>(content);
+			const parsed = tryParseJson<Record<string, unknown>>(content);
 			if (parsed) {
 				items.push({
 					path: userConfigPath,
@@ -325,7 +324,7 @@ async function loadSettings(ctx: LoadContext): Promise<LoadResult<Settings>> {
 	const projectConfigPath = path.join(ctx.cwd, "opencode.json");
 	const content = await readFile(projectConfigPath);
 	if (content) {
-		const parsed = parseJSON<Record<string, unknown>>(content);
+		const parsed = tryParseJson<Record<string, unknown>>(content);
 		if (parsed) {
 			items.push({
 				path: projectConfigPath,

package/src/discovery/ssh.ts

@@ -5,13 +5,13 @@
  * Priority: 5 (low, project/user config discovery)
  */
 import * as path from "node:path";
-import { getSSHConfigPath } from "@oh-my-pi/pi-utils/dirs";
+import { getSSHConfigPath, tryParseJson } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
 import { readFile } from "../capability/fs";
 import { type SSHHost, sshCapability } from "../capability/ssh";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 import { expandTilde } from "../tools/path-utils";
-import { createSourceMeta, expandEnvVarsDeep, parseJSON } from "./helpers";
+import { createSourceMeta, expandEnvVarsDeep } from "./helpers";
 
 const PROVIDER_ID = "ssh-json";
 const DISPLAY_NAME = "SSH Config";
@@ -95,7 +95,7 @@ async function loadSshJsonFile(
 	if (content === null) {
 		return { items, warnings };
 	}
-	const parsed = parseJSON<SSHConfigFile>(content);
+	const parsed = tryParseJson<SSHConfigFile>(content);
 	if (!parsed) {
 		warnings.push(`Failed to parse JSON in ${filePath}`);
 		return { items, warnings };

package/src/discovery/vscode.ts

@@ -4,11 +4,12 @@
  * Loads config from `.vscode` directory (project-only).
  * Supports MCP server discovery from `mcp.json` with nested `mcp.servers` structure.
  */
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
 import { readFile } from "../capability/fs";
 import { type MCPServer, mcpCapability } from "../capability/mcp";
 import type { LoadContext, LoadResult } from "../capability/types";
-import { createSourceMeta, expandEnvVarsDeep, getProjectPath, parseJSON } from "./helpers";
+import { createSourceMeta, expandEnvVarsDeep, getProjectPath } from "./helpers";
 
 const PROVIDER_ID = "vscode";
 const DISPLAY_NAME = "VS Code";
@@ -57,7 +58,7 @@ async function loadMCPConfig(
 		return { items, warnings };
 	}
 
-	const parsed = parseJSON<{ mcp?: { servers?: Record<string, unknown> } }>(content);
+	const parsed = tryParseJson<{ mcp?: { servers?: Record<string, unknown> } }>(content);
 	if (!parsed) {
 		warnings.push(`Invalid JSON in ${path}`);
 		return { items, warnings };

package/src/discovery/windsurf.ts

@@ -10,6 +10,8 @@
  * - Rules from .windsurf/rules/*.md and ~/.codeium/windsurf/memories/global_rules.md
  * - Legacy .windsurfrules file
  */
+
+import { tryParseJson } from "@oh-my-pi/pi-utils";
 import { registerProvider } from "../capability";
 import { readFile } from "../capability/fs";
 import { type MCPServer, mcpCapability } from "../capability/mcp";
@@ -22,7 +24,6 @@ import {
 	getProjectPath,
 	getUserPath,
 	loadFilesFromDir,
-	parseJSON,
 } from "./helpers";
 
 const PROVIDER_ID = "windsurf";
@@ -78,7 +79,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 	for (const { content, path, scope } of configs) {
 		if (!content || !path) continue;
 
-		const config = parseJSON<{ mcpServers?: Record<string, unknown> }>(content);
+		const config = tryParseJson<{ mcpServers?: Record<string, unknown> }>(content);
 		if (!config?.mcpServers) continue;
 
 		for (const [name, serverConfig] of Object.entries(config.mcpServers)) {

package/src/exa/company.ts

@@ -22,5 +22,5 @@ Parameters:
 	Type.Object({
 		company_name: Type.String({ description: "Name of the company to research" }),
 	}),
-	"company_research",
+	"company_research_exa",
 );

package/src/exa/factory.ts

@@ -31,12 +31,7 @@ export function createExaTool(
 		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
 			try {
 				const apiKey = await findApiKey();
-				if (!apiKey) {
-					return {
-						content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
-						details: { error: "EXA_API_KEY not found", toolName: name },
-					};
-				}
+				// Exa MCP endpoint is publicly accessible; API key is optional
 				const args = transformParams ? transformParams(params as Record<string, unknown>) : params;
 				const response = await callExaTool(mcpToolName, args, apiKey);
 

package/src/exa/linkedin.ts

@@ -22,5 +22,5 @@ Parameters:
 	Type.Object({
 		query: Type.String({ description: "LinkedIn search query" }),
 	}),
-	"linkedin_search",
+	"linkedin_search_exa",
 );

package/src/exa/mcp-client.ts

@@ -17,8 +17,11 @@ export function findApiKey(): string | null {
 }
 
 /** Fetch available tools from Exa MCP */
-export async function fetchExaTools(apiKey: string, toolNames: string[]): Promise<MCPTool[]> {
-	const url = `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}&toolNames=${encodeURIComponent(toolNames.join(","))}`;
+export async function fetchExaTools(apiKey: string | null, toolNames: string[]): Promise<MCPTool[]> {
+	const params = new URLSearchParams();
+	if (apiKey) params.set("exaApiKey", apiKey);
+	params.set("toolNames", toolNames.join(","));
+	const url = `https://mcp.exa.ai/mcp?${params.toString()}`;
 	const response = (await callMCP(url, "tools/list")) as MCPToolsResponse;
 
 	if (response.error) {
@@ -43,8 +46,15 @@ export async function fetchWebsetsTools(apiKey: string): Promise<MCPTool[]> {
 }
 
 /** Call a tool on Exa MCP (simplified: toolName as first arg for easier use) */
-export async function callExaTool(toolName: string, args: Record<string, unknown>, apiKey: string): Promise<unknown> {
-	const url = `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(apiKey)}&tools=${encodeURIComponent(toolName)}`;
+export async function callExaTool(
+	toolName: string,
+	args: Record<string, unknown>,
+	apiKey: string | null,
+): Promise<unknown> {
+	const params = new URLSearchParams();
+	if (apiKey) params.set("exaApiKey", apiKey);
+	params.set("tools", toolName);
+	const url = `https://mcp.exa.ai/mcp?${params.toString()}`;
 	const response = (await callMCP(url, "tools/call", {
 		name: toolName,
 		arguments: args,
@@ -174,15 +184,16 @@ export class MCPWrappedTool implements CustomTool<TSchema, ExaRenderDetails> {
 	): Promise<CustomToolResult<ExaRenderDetails>> {
 		try {
 			const apiKey = await findApiKey();
-			if (!apiKey) {
+			// Websets tools require an API key; basic Exa MCP tools work without one
+			if (!apiKey && this.config.isWebsetsTool) {
 				return {
-					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
-					details: { error: "EXA_API_KEY not found", toolName: this.config.name },
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY required for Websets tools" }],
+					details: { error: "EXA_API_KEY required for Websets tools", toolName: this.config.name },
 				};
 			}
 
 			const response = this.config.isWebsetsTool
-				? await callWebsetsTool(apiKey, this.config.mcpToolName, params as Record<string, unknown>)
+				? await callWebsetsTool(apiKey!, this.config.mcpToolName, params as Record<string, unknown>)
 				: await callExaTool(this.config.mcpToolName, params as Record<string, unknown>, apiKey);
 
 			if (isSearchResponse(response)) {

package/src/exa/search.ts

@@ -143,7 +143,7 @@ Similar parameters to exa_search, optimized for research depth.`,
 		),
 	}),
 	"web_search_exa",
-	{ transformParams: params => ({ ...params, type: "deep" }) },
+	{ transformParams: params => ({ ...params, type: "auto" }) },
 );
 
 /** exa_search_code - Code-focused search */
@@ -195,7 +195,7 @@ Parameters:
 			}),
 		),
 	}),
-	"crawling",
+	"crawling_exa",
 );
 
 export const searchTools: CustomTool<any, ExaRenderDetails>[] = [

package/src/exa/types.ts

@@ -122,11 +122,11 @@ export const EXA_TOOL_MAPPINGS = {
 	// Search tools
 	web_search_exa: "exa_search",
 	get_code_context_exa: "exa_search_code",
-	crawling: "exa_crawl",
+	crawling_exa: "exa_crawl",
 	// LinkedIn
-	linkedin_search: "exa_linkedin",
+	linkedin_search_exa: "exa_linkedin",
 	// Company
-	company_research: "exa_company",
+	company_research_exa: "exa_company",
 	// Researcher
 	deep_researcher_start: "exa_researcher_start",
 	deep_researcher_check: "exa_researcher_poll",

package/src/exec/bash-executor.ts

@@ -7,6 +7,7 @@ import { Shell } from "@oh-my-pi/pi-natives";
 import { Settings } from "../config/settings";
 import { OutputSink } from "../session/streaming-output";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
+import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
 export interface BashExecutorOptions {
 	cwd?: string;
@@ -97,7 +98,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			{
 				command: finalCommand,
 				cwd: options?.cwd,
-				env: options?.env,
+				env: options?.env ? { ...NON_INTERACTIVE_ENV, ...options.env } : NON_INTERACTIVE_ENV,
 				timeoutMs: options?.timeout,
 				signal,
 			},

package/src/exec/non-interactive-env.ts

@@ -0,0 +1,43 @@
+export const NON_INTERACTIVE_ENV: Readonly<Record<string, string>> = {
+	// Disable pagers so commands don't block on interactive views.
+	PAGER: "cat",
+	GIT_PAGER: "cat",
+	MANPAGER: "cat",
+	SYSTEMD_PAGER: "cat",
+	BAT_PAGER: "cat",
+	DELTA_PAGER: "cat",
+	GH_PAGER: "cat",
+	GLAB_PAGER: "cat",
+	PSQL_PAGER: "cat",
+	MYSQL_PAGER: "cat",
+	AWS_PAGER: "",
+	HOMEBREW_PAGER: "cat",
+	LESS: "FRX",
+	// Disable editor and terminal credential prompts.
+	GIT_EDITOR: "true",
+	VISUAL: "true",
+	EDITOR: "true",
+	GIT_TERMINAL_PROMPT: "0",
+	SSH_ASKPASS: "/usr/bin/false",
+	CI: "1",
+	// Package manager defaults for unattended execution.
+	npm_config_yes: "true",
+	npm_config_update_notifier: "false",
+	npm_config_fund: "false",
+	npm_config_audit: "false",
+	npm_config_progress: "false",
+	PNPM_DISABLE_SELF_UPDATE_CHECK: "true",
+	PNPM_UPDATE_NOTIFIER: "false",
+	YARN_ENABLE_TELEMETRY: "0",
+	YARN_ENABLE_PROGRESS_BARS: "0",
+	// Cross-language/tooling non-interactive defaults.
+	CARGO_TERM_PROGRESS_WHEN: "never",
+	DEBIAN_FRONTEND: "noninteractive",
+	PIP_NO_INPUT: "1",
+	PIP_DISABLE_PIP_VERSION_CHECK: "1",
+	TF_INPUT: "0",
+	TF_IN_AUTOMATION: "1",
+	GH_PROMPT_DISABLED: "1",
+	COMPOSER_NO_INTERACTION: "1",
+	CLOUDSDK_CORE_DISABLE_PROMPTS: "1",
+};

package/src/export/custom-share.ts

@@ -6,7 +6,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getAgentDir } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDir } from "@oh-my-pi/pi-utils";
 
 export interface CustomShareResult {
 	/** URL to display/open (optional - script may handle everything itself) */

package/src/export/html/index.ts

@@ -1,7 +1,6 @@
 import * as path from "node:path";
 import type { AgentState } from "@oh-my-pi/pi-agent-core";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { APP_NAME } from "@oh-my-pi/pi-utils/dirs";
+import { APP_NAME, isEnoent } from "@oh-my-pi/pi-utils";
 import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/theme";
 import { type SessionEntry, type SessionHeader, SessionManager } from "../../session/session-manager";
 // Pre-generated template (created by scripts/generate-template.ts at publish time)

package/src/extensibility/custom-commands/loader.ts

@@ -7,8 +7,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as piCodingAgent from "@oh-my-pi/pi-coding-agent";
-import { isEnoent, logger } from "@oh-my-pi/pi-utils";
-import { getAgentDir, getProjectDir } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDir, getProjectDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import * as typebox from "@sinclair/typebox";
 import { getConfigDirs } from "../../config";
 import { execCommand } from "../../exec/exec";

package/src/extensibility/plugins/installer.ts

@@ -1,7 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { getAgentDir, getProjectDir } from "@oh-my-pi/pi-utils/dirs";
+import { getAgentDir, getProjectDir, isEnoent } from "@oh-my-pi/pi-utils";
 import { extractPackageName } from "./parser";
 import type { InstalledPlugin } from "./types";
 

package/src/extensibility/plugins/loader.ts

@@ -6,8 +6,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { getPluginsLockfile, getPluginsNodeModules, getPluginsPackageJson } from "@oh-my-pi/pi-utils/dirs";
+import { getPluginsLockfile, getPluginsNodeModules, getPluginsPackageJson, isEnoent } from "@oh-my-pi/pi-utils";
 import { getConfigDirPaths } from "../../config";
 import type { InstalledPlugin, PluginManifest, PluginRuntimeConfig, ProjectPluginOverrides } from "./types";
 

package/src/extensibility/plugins/manager.ts

@@ -1,6 +1,5 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 import {
 	getPluginsDir,
 	getPluginsLockfile,
@@ -8,7 +7,9 @@ import {
 	getPluginsPackageJson,
 	getProjectDir,
 	getProjectPluginOverridesPath,
-} from "@oh-my-pi/pi-utils/dirs";
+	isEnoent,
+	logger,
+} from "@oh-my-pi/pi-utils";
 import { extractPackageName, parsePluginSpec } from "./parser";
 import type {
 	DoctorCheck,

package/src/extensibility/skills.ts

@@ -1,18 +1,12 @@
 import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { logger } from "@oh-my-pi/pi-utils";
-import { getProjectDir } from "@oh-my-pi/pi-utils/dirs";
+import * as os from "node:os";
+import { getProjectDir } from "@oh-my-pi/pi-utils";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
-import type { Skill as CapabilitySkill, SkillFrontmatter as ImportedSkillFrontmatter } from "../discovery";
-import { loadCapability } from "../discovery";
+import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
+import { scanSkillsFromDir } from "../discovery/helpers";
 import { expandTilde } from "../tools/path-utils";
-import { parseFrontmatter } from "../utils/frontmatter";
-import { addIgnoreRules, createIgnoreMatcher, type IgnoreMatcher, shouldIgnore } from "../utils/ignore-files";
-
-// Re-export SkillFrontmatter for backward compatibility
-export type { ImportedSkillFrontmatter as SkillFrontmatter };
 
 export interface Skill {
 	name: string;
@@ -41,91 +35,31 @@ export interface LoadSkillsFromDirOptions {
 	source: string;
 }
 
-async function readFileContent(filePath: string): Promise<string | null> {
-	try {
-		return await fs.readFile(filePath, "utf-8");
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Load skills from a directory recursively.
- * Skills are directories containing a SKILL.md file with frontmatter including a description.
- * Respects .gitignore, .ignore, and .fdignore files.
- */
 export async function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Promise<LoadSkillsResult> {
-	const skills: Skill[] = [];
-	const warnings: SkillWarning[] = [];
-	const seenPaths = new Set<string>();
-	const rootDir = options.dir;
-
-	async function addSkill(skillFile: string, skillDir: string, dirName: string): Promise<void> {
-		if (seenPaths.has(skillFile)) return;
-		try {
-			const content = await fs.readFile(skillFile, "utf-8");
-			const { frontmatter } = parseFrontmatter(content, { source: skillFile });
-			const name = (frontmatter.name as string) || dirName;
-			const description = frontmatter.description as string;
-
-			if (description) {
-				seenPaths.add(skillFile);
-				skills.push({
-					name,
-					description,
-					filePath: skillFile,
-					baseDir: skillDir,
-					source: options.source,
-				});
-			}
-		} catch (error) {
-			logger.warn("Failed to load skill", { path: skillFile, error: String(error) });
-		}
-	}
-
-	async function scanDir(dir: string, ig: IgnoreMatcher): Promise<void> {
-		try {
-			// Add ignore rules from this directory
-			await addIgnoreRules(ig, dir, rootDir, readFileContent);
-
-			// First check if this directory itself is a skill
-			const selfSkillFile = path.join(dir, "SKILL.md");
-			try {
-				const s = await fs.stat(selfSkillFile);
-				if (s.isFile()) {
-					await addSkill(selfSkillFile, dir, path.basename(dir));
-					// This directory is a skill, don't recurse
-					return;
-				}
-			} catch {
-				// No SKILL.md in this directory
-			}
-
-			// Recurse into subdirectories
-			const entries = await fs.readdir(dir, { withFileTypes: true });
-
-			for (const entry of entries) {
-				if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-
-				const fullPath = path.join(dir, entry.name);
-				const isDir = entry.isDirectory();
-
-				// Check if this entry should be ignored
-				if (shouldIgnore(ig, rootDir, fullPath, isDir)) continue;
-
-				if (isDir) {
-					await scanDir(fullPath, ig);
-				}
-			}
-		} catch (err) {
-			warnings.push({ skillPath: dir, message: `Failed to read directory: ${err}` });
-		}
-	}
-
-	const ig = createIgnoreMatcher();
-	await scanDir(options.dir, ig);
+	const [rawProviderId, rawLevel] = options.source.split(":", 2);
+	const providerId = rawProviderId || "custom";
+	const level: "user" | "project" = rawLevel === "project" ? "project" : "user";
+	const result = await scanSkillsFromDir(
+		{ cwd: getProjectDir(), home: os.homedir() },
+		{
+			dir: options.dir,
+			providerId,
+			level,
+			requireDescription: true,
+		},
+	);
 
-	return { skills, warnings };
+	return {
+		skills: result.items.map(capSkill => ({
+			name: capSkill.name,
+			description: typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
+			filePath: capSkill.path,
+			baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
+			source: options.source,
+			_source: capSkill._source,
+		})),
+		warnings: (result.warnings ?? []).map(message => ({ skillPath: options.dir, message })),
+	};
 }
 
 export interface LoadSkillsOptions extends SkillsSettings {
@@ -225,45 +159,55 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 				message: `name collision: "${capSkill.name}" already loaded from ${existing.filePath}, skipping this one`,
 			});
 		} else {
-			// Transform capability skill to legacy format
-			const skill: Skill = {
+			skillMap.set(capSkill.name, {
 				name: capSkill.name,
-				description: capSkill.frontmatter?.description || "",
+				description: typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
 				filePath: capSkill.path,
 				baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
 				source: `${capSkill._source.provider}:${capSkill.level}`,
 				_source: capSkill._source,
-			};
-			skillMap.set(capSkill.name, skill);
+			});
 			realPathSet.add(resolvedPath);
 		}
 	}
 
-	// Process custom directories - scan directly without using full provider system
-	const allCustomSkills: Array<{ skill: Skill; path: string }> = [];
-	const customScanResults = await Promise.all(
-		customDirectories.map(dir => loadSkillsFromDir({ dir: expandTilde(dir), source: "custom" })),
+	const customDirectoryResults = await Promise.all(
+		customDirectories.map(async dir => {
+			const expandedDir = expandTilde(dir);
+			const scanResult = await scanSkillsFromDir(
+				{ cwd, home: os.homedir() },
+				{
+					dir: expandedDir,
+					providerId: "custom",
+					level: "user",
+					requireDescription: true,
+				},
+			);
+			return { expandedDir, scanResult };
+		}),
 	);
-	for (const customSkills of customScanResults) {
-		for (const s of customSkills.skills) {
-			if (matchesIgnorePatterns(s.name)) continue;
-			if (!matchesIncludePatterns(s.name)) continue;
+
+	const allCustomSkills: Array<{ skill: Skill; path: string }> = [];
+	for (const { expandedDir, scanResult } of customDirectoryResults) {
+		for (const capSkill of scanResult.items) {
+			if (matchesIgnorePatterns(capSkill.name)) continue;
+			if (!matchesIncludePatterns(capSkill.name)) continue;
 			allCustomSkills.push({
 				skill: {
-					name: s.name,
-					description: s.description,
-					filePath: s.filePath,
-					baseDir: s.filePath.replace(/\/SKILL\.md$/, ""),
+					name: capSkill.name,
+					description:
+						typeof capSkill.frontmatter?.description === "string" ? capSkill.frontmatter.description : "",
+					filePath: capSkill.path,
+					baseDir: capSkill.path.replace(/\/SKILL\.md$/, ""),
 					source: "custom:user",
-					_source: { provider: "custom", providerName: "Custom", path: s.filePath, level: "user" },
+					_source: { ...capSkill._source, providerName: "Custom" },
 				},
-				path: s.filePath,
+				path: capSkill.path,
 			});
 		}
-		collisionWarnings.push(...customSkills.warnings);
+		collisionWarnings.push(...(scanResult.warnings ?? []).map(message => ({ skillPath: expandedDir, message })));
 	}
 
-	// Batch resolve custom skill paths
 	const customRealPaths = await Promise.all(
 		allCustomSkills.map(async ({ path }) => {
 			try {
@@ -293,6 +237,6 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	return {
 		skills: Array.from(skillMap.values()),
-		warnings: [...result.warnings.map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
+		warnings: [...(result.warnings ?? []).map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
 	};
 }

package/src/index.ts

@@ -6,8 +6,7 @@ export { StringEnum } from "@oh-my-pi/pi-ai";
 // Re-export TUI components for custom tool rendering
 export { Container, Markdown, Spacer, Text } from "@oh-my-pi/pi-tui";
 // Logging
-export { logger } from "@oh-my-pi/pi-utils";
-export { getAgentDir, VERSION } from "@oh-my-pi/pi-utils/dirs";
+export { getAgentDir, logger, VERSION } from "@oh-my-pi/pi-utils";
 export { formatKeyHint, formatKeyHints } from "./config/keybindings";
 export { ModelRegistry } from "./config/model-registry";
 // Prompt templates
@@ -89,7 +88,6 @@ export {
 	loadSkills,
 	loadSkillsFromDir,
 	type Skill,
-	type SkillFrontmatter,
 	type SkillWarning,
 } from "./extensibility/skills";
 // Slash commands