pi-subagents 0.13.4 → 0.14.1

package/render.ts

@@ -20,7 +20,6 @@ function getTermWidth(): number {
 	return process.stdout.columns || 120;
 }
 
-// Grapheme segmenter for proper Unicode handling (shared instance)
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 
 /**
@@ -35,42 +34,38 @@ const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 function truncLine(text: string, maxWidth: number): string {
 	if (visibleWidth(text) <= maxWidth) return text;
 
-	const targetWidth = maxWidth - 1; // Room for single ellipsis character
+	const targetWidth = maxWidth - 1;
 	let result = "";
 	let currentWidth = 0;
-	let activeStyles: string[] = []; // Track ALL active styles (not just last)
+	let activeStyles: string[] = [];
 	let i = 0;
 
 	while (i < text.length) {
-		// Check for ANSI escape code
 		const ansiMatch = text.slice(i).match(/^\x1b\[[0-9;]*m/);
 		if (ansiMatch) {
 			const code = ansiMatch[0];
 			result += code;
 
 			if (code === "\x1b[0m" || code === "\x1b[m") {
-				activeStyles = []; // Reset clears all styles
+				activeStyles = [];
 			} else {
-				activeStyles.push(code); // Stack styles (bold + color, etc.)
+				activeStyles.push(code);
 			}
 			i += code.length;
 			continue;
 		}
 
-		// Find end of non-ANSI text segment
 		let end = i;
 		while (end < text.length && !text.slice(end).match(/^\x1b\[[0-9;]*m/)) {
 			end++;
 		}
 
-		// Segment into graphemes for proper Unicode handling
 		const textPortion = text.slice(i, end);
 		for (const seg of segmenter.segment(textPortion)) {
 			const grapheme = seg.segment;
 			const graphemeWidth = visibleWidth(grapheme);
 
 			if (currentWidth + graphemeWidth > targetWidth) {
-				// Re-apply all active styles before ellipsis to preserve background/colors
 				return result + activeStyles.join("") + "…";
 			}
 
@@ -80,16 +75,11 @@ function truncLine(text: string, maxWidth: number): string {
 		i = end;
 	}
 
-	// Reached end without exceeding width (shouldn't happen given initial check)
 	return result + activeStyles.join("") + "…";
 }
 
-// Track last rendered widget state to avoid no-op re-renders
 let lastWidgetHash = "";
 
-/**
- * Compute a simple hash of job states for change detection
- */
 function computeWidgetHash(jobs: AsyncJobState[]): string {
 	return jobs.slice(0, MAX_WIDGET_JOBS).map(job =>
 		`${job.asyncId}:${job.status}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
@@ -124,13 +114,11 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		return;
 	}
 
-	// Check if anything changed since last render
-	// Always re-render if any displayed job is running (output tail updates constantly)
 	const displayedJobs = jobs.slice(0, MAX_WIDGET_JOBS);
 	const hasRunningJobs = displayedJobs.some(job => job.status === "running");
 	const newHash = computeWidgetHash(jobs);
 	if (!hasRunningJobs && newHash === lastWidgetHash) {
-		return; // Skip re-render, nothing changed
+		return;
 	}
 	lastWidgetHash = newHash;
 
@@ -194,12 +182,12 @@ export function renderSubagentResult(
 		const r = d.results[0];
 		const isRunning = r.progress?.status === "running";
 		const icon = isRunning
-			? theme.fg("warning", "...")
+			? theme.fg("warning", "running")
 			: r.detached
-				? theme.fg("warning", "↗")
+				? theme.fg("warning", "detached")
 				: r.exitCode === 0
 					? theme.fg("success", "ok")
-					: theme.fg("error", "X");
+					: theme.fg("error", "failed");
 		const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
 		const output = r.truncation?.text || getSingleResultOutput(r);
 
@@ -265,7 +253,7 @@ export function renderSubagentResult(
 			c.addChild(new Text(truncLine(theme.fg("dim", `Skills: ${r.skills.join(", ")}`), w), 0, 0));
 		}
 		if (r.skillsWarning) {
-			c.addChild(new Text(truncLine(theme.fg("warning", `⚠️ ${r.skillsWarning}`), w), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("warning", `Warning: ${r.skillsWarning}`), w), 0, 0));
 		}
 		if (r.attemptedModels && r.attemptedModels.length > 1) {
 			c.addChild(new Text(truncLine(theme.fg("dim", `Fallbacks: ${r.attemptedModels.join(" → ")}`), w), 0, 0));
@@ -291,12 +279,12 @@ export function renderSubagentResult(
 		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getSingleResultOutput(r)),
 	);
 	const icon = hasRunning
-		? theme.fg("warning", "...")
+		? theme.fg("warning", "running")
 		: hasEmptyWithoutTarget
-			? theme.fg("warning", "⚠")
+			? theme.fg("warning", "warning")
 			: ok === d.results.length
 				? theme.fg("success", "ok")
-				: theme.fg("error", "X");
+				: theme.fg("error", "failed");
 
 	const totalSummary =
 		d.progressSummary ||
@@ -323,17 +311,11 @@ export function renderSubagentResult(
 
 	const modeLabel = d.mode;
 	const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
-	// For parallel-in-chain, show task count (results) for consistency with step display
-	// For sequential chains, show logical step count
 	const hasParallelInChain = d.chainAgents?.some((a) => a.startsWith("["));
 	const totalCount = hasParallelInChain ? d.results.length : (d.totalSteps ?? d.results.length);
 	const currentStep = d.currentStepIndex !== undefined ? d.currentStepIndex + 1 : ok + 1;
 	const stepInfo = hasRunning ? ` ${currentStep}/${totalCount}` : ` ${ok}/${totalCount}`;
 	
-	// Build chain visualization: "scout → planner" with status icons
-	// Note: Only works correctly for sequential chains. Chains with parallel steps
-	// (indicated by "[agent1+agent2]" format) have multiple results per step,
-	// breaking the 1:1 mapping between chainAgents and results.
 	const chainVis = d.chainAgents?.length && !hasParallelInChain
 		? d.chainAgents
 				.map((agent, i) => {
@@ -345,14 +327,14 @@ export function renderSubagentResult(
 						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getSingleResultOutput(result));
 					const isCurrent = i === (d.currentStepIndex ?? d.results.length);
 					const stepIcon = isFailed
-						? theme.fg("error", "✗")
+						? theme.fg("error", "failed")
 						: isEmptyWithoutTarget
-							? theme.fg("warning", "⚠")
+							? theme.fg("warning", "warning")
 							: isComplete
-								? theme.fg("success", "✓")
+								? theme.fg("success", "done")
 								: isCurrent && hasRunning
-									? theme.fg("warning", "●")
-									: theme.fg("dim", "○");
+									? theme.fg("warning", "running")
+									: theme.fg("dim", "pending");
 					return `${stepIcon} ${agent}`;
 				})
 				.join(theme.fg("dim", " → "))
@@ -367,15 +349,10 @@ export function renderSubagentResult(
 			0,
 		),
 	);
-	// Show chain visualization
 	if (chainVis) {
 		c.addChild(new Text(truncLine(`  ${chainVis}`, w), 0, 0));
 	}
 
-	// === STATIC STEP LAYOUT (like clarification UI) ===
-	// Each step gets a fixed section with task/output/status
-	// Note: For chains with parallel steps, chainAgents indices don't map 1:1 to results
-	// (parallel steps produce multiple results). Fall back to result-based iteration.
 	const useResultsDirectly = hasParallelInChain || !d.chainAgents?.length;
 	const stepsToShow = useResultsDirectly ? d.results.length : d.chainAgents!.length;
 
@@ -388,9 +365,8 @@ export function renderSubagentResult(
 			: (d.chainAgents![i] || r?.agent || `step-${i + 1}`);
 
 		if (!r) {
-			// Pending step
 			c.addChild(new Text(truncLine(theme.fg("dim", `  Step ${i + 1}: ${agentName}`), w), 0, 0));
-			c.addChild(new Text(theme.fg("dim", `    status: ○ pending`), 0, 0));
+			c.addChild(new Text(theme.fg("dim", `    status: pending`), 0, 0));
 			c.addChild(new Spacer(1));
 			continue;
 		}
@@ -402,12 +378,12 @@ export function renderSubagentResult(
 
 		const resultOutput = getSingleResultOutput(r);
 		const statusIcon = rRunning
-			? theme.fg("warning", "●")
+			? theme.fg("warning", "running")
 			: r.exitCode !== 0
-				? theme.fg("error", "✗")
+				? theme.fg("error", "failed")
 				: hasEmptyTextOutputWithoutOutputTarget(r.task, resultOutput)
-					? theme.fg("warning", "⚠")
-					: theme.fg("success", "✓");
+					? theme.fg("warning", "warning")
+					: theme.fg("success", "done");
 		const stats = rProg ? ` | ${rProg.toolCount} tools, ${formatDuration(rProg.durationMs)}` : "";
 		const modelDisplay = r.model ? theme.fg("dim", ` (${r.model})`) : "";
 		const stepHeader = rRunning
@@ -430,7 +406,7 @@ export function renderSubagentResult(
 			c.addChild(new Text(truncLine(theme.fg("dim", `    skills: ${r.skills.join(", ")}`), w), 0, 0));
 		}
 		if (r.skillsWarning) {
-			c.addChild(new Text(truncLine(theme.fg("warning", `    ⚠️ ${r.skillsWarning}`), w), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("warning", `    Warning: ${r.skillsWarning}`), w), 0, 0));
 		}
 		if (r.attemptedModels && r.attemptedModels.length > 1) {
 			c.addChild(new Text(truncLine(theme.fg("dim", `    fallbacks: ${r.attemptedModels.join(" → ")}`), w), 0, 0));
@@ -440,7 +416,6 @@ export function renderSubagentResult(
 			if (rProg.skills?.length) {
 				c.addChild(new Text(truncLine(theme.fg("accent", `    skills: ${rProg.skills.join(", ")}`), w), 0, 0));
 			}
-			// Current tool for running step
 			if (rProg.currentTool) {
 				const maxToolArgsLen = Math.max(50, w - 20);
 				const toolArgsPreview = rProg.currentToolArgs
@@ -453,7 +428,6 @@ export function renderSubagentResult(
 					: rProg.currentTool;
 				c.addChild(new Text(truncLine(theme.fg("warning", `    > ${toolLine}`), w), 0, 0));
 			}
-			// Recent tools
 			if (rProg.recentTools?.length) {
 				for (const t of rProg.recentTools.slice(-3)) {
 					const maxArgsLen = Math.max(40, w - 30);
@@ -463,7 +437,6 @@ export function renderSubagentResult(
 					c.addChild(new Text(truncLine(theme.fg("dim", `      ${t.tool}: ${argsPreview}`), w), 0, 0));
 				}
 			}
-			// Recent output - let truncLine handle truncation entirely
 			const recentLines = (rProg.recentOutput ?? []).slice(-5);
 			for (const line of recentLines) {
 				c.addChild(new Text(truncLine(theme.fg("dim", `      ${line}`), w), 0, 0));

package/schemas.ts

@@ -83,7 +83,7 @@ export const SubagentParams = Type.Object({
 		enum: ["fresh", "fork"],
 		description: "'fresh' (default) or 'fork' to branch from parent session",
 	})),
-	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: <tmpdir>/pi-chain-runs/ (auto-cleaned after 24h)" })),
+	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: a user-scoped temp directory under <tmpdir>/ (auto-cleaned after 24h)" })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),

package/settings.ts

@@ -3,12 +3,10 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "./agents.ts";
 import { normalizeSkillInput } from "./skills.ts";
-
-const CHAIN_RUNS_DIR = path.join(os.tmpdir(), "pi-chain-runs");
+import { CHAIN_RUNS_DIR } from "./types.ts";
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 
 // =============================================================================
@@ -100,7 +98,9 @@ export function createChainDir(runId: string, baseDir?: string): string {
 export function removeChainDir(chainDir: string): void {
 	try {
 		fs.rmSync(chainDir, { recursive: true });
-	} catch {}
+	} catch {
+		// Chain cleanup is best-effort. Runs can already have cleaned their temp dir.
+	}
 }
 
 export function cleanupOldChainDirs(): void {
@@ -110,6 +110,8 @@ export function cleanupOldChainDirs(): void {
 	try {
 		dirs = fs.readdirSync(CHAIN_RUNS_DIR);
 	} catch {
+		// Startup cleanup is best-effort. If the scoped temp root is unreadable,
+		// skip cleanup instead of failing extension startup.
 		return;
 	}
 

package/single-output.ts

@@ -84,11 +84,11 @@ export function finalizeSingleOutput(params: {
 }): { displayOutput: string; savedPath?: string; saveError?: string } {
 	let displayOutput = params.truncatedOutput || params.fullOutput;
 	if (params.exitCode === 0 && params.savedPath) {
-		displayOutput += `\n\n📄 Output saved to: ${params.savedPath}`;
+		displayOutput += `\n\nOutput saved to: ${params.savedPath}`;
 		return { displayOutput, savedPath: params.savedPath };
 	}
 	if (params.exitCode === 0 && params.saveError && params.outputPath) {
-		displayOutput += `\n\n⚠️ Failed to save output to: ${params.outputPath}\n${params.saveError}`;
+		displayOutput += `\n\nFailed to save output to: ${params.outputPath}\n${params.saveError}`;
 		return { displayOutput, saveError: params.saveError };
 	}
 	return { displayOutput };

package/skills.ts

@@ -38,6 +38,11 @@ interface CachedSkillEntry {
 	order: number;
 }
 
+interface SkillSearchPath {
+	path: string;
+	source: SkillSource;
+}
+
 const skillCache = new Map<string, SkillCacheEntry>();
 const MAX_CACHE_SIZE = 50;
 
@@ -74,22 +79,45 @@ function isWithinPath(filePath: string, dir: string): boolean {
 	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function getPackageSkillPaths(packageRoot: string): string[] {
-	const pkgJsonPath = path.join(packageRoot, "package.json");
+function readOptionalJsonFile(filePath: string, label: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch (error) {
+		const code = typeof error === "object" && error !== null && "code" in error
+			? (error as { code?: unknown }).code
+			: undefined;
+		if (code === "ENOENT") return null;
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read ${label} '${filePath}': ${message}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+function readJsonFileBestEffort(filePath: string): unknown {
 	try {
-		const content = fs.readFileSync(pkgJsonPath, "utf-8");
-		const pkg = JSON.parse(content);
-		const piSkills = pkg?.pi?.skills;
-		if (!Array.isArray(piSkills)) return [];
-		return piSkills
-			.filter((s: unknown) => typeof s === "string")
-			.map((s: string) => path.resolve(packageRoot, s));
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
 	} catch {
-		// Package scanning is opportunistic; ignore malformed/missing package metadata.
-		return [];
+		// Package scans over installed dependencies are opportunistic.
+		return null;
 	}
 }
 
+function extractSkillPathsFromPackageRoot(packageRoot: string, source: SkillSource, bestEffort = false): SkillSearchPath[] {
+	const packageJsonPath = path.join(packageRoot, "package.json");
+	const pkg = bestEffort
+		? readJsonFileBestEffort(packageJsonPath)
+		: readOptionalJsonFile(packageJsonPath, "package manifest");
+	if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return [];
+	const pi = (pkg as { pi?: unknown }).pi;
+	if (!pi || typeof pi !== "object" || Array.isArray(pi)) return [];
+	const skills = (pi as { skills?: unknown }).skills;
+	if (!Array.isArray(skills)) return [];
+	return skills
+		.filter((entry): entry is string => typeof entry === "string")
+		.map((entry) => ({ path: path.resolve(packageRoot, entry), source }));
+}
+
 let cachedGlobalNpmRoot: string | null = null;
 
 function getGlobalNpmRoot(): string | null {
@@ -104,27 +132,25 @@ function getGlobalNpmRoot(): string | null {
 	}
 }
 
-function collectPackageSkillPaths(cwd: string): string[] {
-	const dirs = [
-		path.join(cwd, CONFIG_DIR, "npm", "node_modules"),
-		path.join(AGENT_DIR, "npm", "node_modules"),
+function collectInstalledPackageSkillPaths(cwd: string): SkillSearchPath[] {
+	const dirs: SkillSearchPath[] = [
+		{ path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"), source: "project-package" },
+		{ path: path.join(AGENT_DIR, "npm", "node_modules"), source: "user-package" },
 	];
-	
-	// Add global npm root if available (where pi installs global packages)
+
 	const globalRoot = getGlobalNpmRoot();
 	if (globalRoot) {
-		dirs.push(globalRoot);
+		dirs.push({ path: globalRoot, source: "user-package" });
 	}
-	
-	const results: string[] = [];
+
+	const results: SkillSearchPath[] = [];
 
 	for (const dir of dirs) {
-		if (!fs.existsSync(dir)) continue;
+		if (!fs.existsSync(dir.path)) continue;
 		let entries: fs.Dirent[];
 		try {
-			entries = fs.readdirSync(dir, { withFileTypes: true });
+			entries = fs.readdirSync(dir.path, { withFileTypes: true });
 		} catch {
-			// Ignore unreadable package roots and continue scanning other roots.
 			continue;
 		}
 
@@ -133,75 +159,125 @@ function collectPackageSkillPaths(cwd: string): string[] {
 			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
 
 			if (entry.name.startsWith("@")) {
-				const scopeDir = path.join(dir, entry.name);
+				const scopeDir = path.join(dir.path, entry.name);
 				let scopeEntries: fs.Dirent[];
 				try {
 					scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
 				} catch {
-					// Ignore unreadable scoped package directories and continue.
 					continue;
 				}
 				for (const scopeEntry of scopeEntries) {
 					if (scopeEntry.name.startsWith(".")) continue;
 					if (!scopeEntry.isDirectory() && !scopeEntry.isSymbolicLink()) continue;
 					const pkgRoot = path.join(scopeDir, scopeEntry.name);
-					results.push(...getPackageSkillPaths(pkgRoot));
+					results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
 				}
 				continue;
 			}
 
-			const pkgRoot = path.join(dir, entry.name);
-			results.push(...getPackageSkillPaths(pkgRoot));
+			const pkgRoot = path.join(dir.path, entry.name);
+			results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
 		}
 	}
 
 	return results;
 }
 
-function collectSettingsSkillPaths(cwd: string): string[] {
-	const results: string[] = [];
+function collectSettingsSkillPaths(cwd: string): SkillSearchPath[] {
+	const results: SkillSearchPath[] = [];
 	const settingsFiles = [
-		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR) },
-		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR },
+		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-settings" as const },
+		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-settings" as const },
 	];
 
-	for (const { file, base } of settingsFiles) {
-		try {
-			const content = fs.readFileSync(file, "utf-8");
-			const settings = JSON.parse(content);
-			const skills = settings?.skills;
-			if (!Array.isArray(skills)) continue;
-			for (const entry of skills) {
-				if (typeof entry !== "string") continue;
-				let resolved = entry;
-				if (resolved.startsWith("~/")) {
-					resolved = path.join(os.homedir(), resolved.slice(2));
-				} else if (!path.isAbsolute(resolved)) {
-					resolved = path.resolve(base, resolved);
-				}
-				results.push(resolved);
+	for (const { file, base, source } of settingsFiles) {
+		const settings = readOptionalJsonFile(file, "skills settings file");
+		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
+		const skills = (settings as { skills?: unknown }).skills;
+		if (!Array.isArray(skills)) continue;
+		for (const entry of skills) {
+			if (typeof entry !== "string") continue;
+			let resolved = entry;
+			if (resolved.startsWith("~/")) {
+				resolved = path.join(os.homedir(), resolved.slice(2));
+			} else if (!path.isAbsolute(resolved)) {
+				resolved = path.resolve(base, resolved);
 			}
-		} catch {
-			// Settings-provided skills are optional; ignore malformed or missing settings files.
+			results.push({ path: resolved, source });
+		}
+	}
+
+	return results;
+}
+
+function resolveSettingsPackageRoot(source: string, baseDir: string): string | undefined {
+	const trimmed = source.trim();
+	if (!trimmed) return undefined;
+	const normalized = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
+	if (normalized === "~") return os.homedir();
+	if (normalized.startsWith("~/")) return path.join(os.homedir(), normalized.slice(2));
+	if (path.isAbsolute(normalized)) return normalized;
+	if (normalized === "." || normalized === ".." || normalized.startsWith("./") || normalized.startsWith("../")) {
+		return path.resolve(baseDir, normalized);
+	}
+	return undefined;
+}
+
+function collectSettingsPackageSkillPaths(cwd: string): SkillSearchPath[] {
+	const settingsFiles = [
+		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-package" as const },
+		{ file: path.join(AGENT_DIR, "settings.json"), base: AGENT_DIR, source: "user-package" as const },
+	];
+	const results: SkillSearchPath[] = [];
+
+	for (const { file, base, source } of settingsFiles) {
+		const settings = readOptionalJsonFile(file, "skills settings file");
+		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
+		const packages = (settings as { packages?: unknown }).packages;
+		if (!Array.isArray(packages)) continue;
+
+		for (const entry of packages) {
+			const packageSource = typeof entry === "string"
+				? entry
+				: typeof entry === "object" && entry !== null && typeof (entry as { source?: unknown }).source === "string"
+					? (entry as { source: string }).source
+					: undefined;
+			if (!packageSource) continue;
+
+			const packageRoot = resolveSettingsPackageRoot(packageSource, base);
+			if (!packageRoot) continue;
+			results.push(...extractSkillPathsFromPackageRoot(packageRoot, source));
 		}
 	}
 
 	return results;
 }
 
-function buildSkillPaths(cwd: string): string[] {
-	const defaultSkillPaths = [
-		path.join(cwd, CONFIG_DIR, "skills"),
-		path.join(cwd, ".agents", "skills"),
-		path.join(AGENT_DIR, "skills"),
-		path.join(os.homedir(), ".agents", "skills"),
+function buildSkillPaths(cwd: string): SkillSearchPath[] {
+	const skillPaths: SkillSearchPath[] = [
+		{ path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
+		{ path: path.join(cwd, ".agents", "skills"), source: "project" },
+		{ path: path.join(AGENT_DIR, "skills"), source: "user" },
+		{ path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
+		...collectInstalledPackageSkillPaths(cwd),
+		...collectSettingsPackageSkillPaths(cwd),
+		...extractSkillPathsFromPackageRoot(cwd, "project-package"),
+		...collectSettingsSkillPaths(cwd),
 	];
-	const packagePaths = collectPackageSkillPaths(cwd);
-	const settingsPaths = collectSettingsSkillPaths(cwd);
-	return [...new Set([...defaultSkillPaths, ...packagePaths, ...settingsPaths])];
+
+	const deduped = new Map<string, SkillSearchPath>();
+	for (const entry of skillPaths) {
+		const resolvedPath = path.resolve(entry.path);
+		if (!deduped.has(resolvedPath)) {
+			deduped.set(resolvedPath, { path: resolvedPath, source: entry.source });
+		}
+	}
+	return [...deduped.values()];
 }
 
-function inferSkillSource(filePath: string, cwd: string): SkillSource {
+function inferSkillSource(filePath: string, cwd: string, sourceHint?: SkillSource): SkillSource {
+	if (sourceHint) return sourceHint;
+
 	const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
 	const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
 	const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
@@ -252,12 +328,12 @@ function maybeReadSkillDescription(filePath: string): string | undefined {
 	}
 }
 
-function collectFilesystemSkills(cwd: string, skillPaths: string[]): CachedSkillEntry[] {
+function collectFilesystemSkills(cwd: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {
 	const entries: CachedSkillEntry[] = [];
 	const seen = new Set<string>();
 	let order = 0;
 
-	const pushEntry = (name: string, filePath: string) => {
+	const pushEntry = (name: string, filePath: string, sourceHint?: SkillSource) => {
 		const resolvedFile = path.resolve(filePath);
 		if (seen.has(resolvedFile)) return;
 		if (!fs.existsSync(resolvedFile)) return;
@@ -265,60 +341,58 @@ function collectFilesystemSkills(cwd: string, skillPaths: string[]): CachedSkill
 		entries.push({
 			name,
 			filePath: resolvedFile,
-			source: inferSkillSource(resolvedFile, cwd),
+			source: inferSkillSource(resolvedFile, cwd, sourceHint),
 			description: maybeReadSkillDescription(resolvedFile),
 			order: order++,
 		});
 	};
 
 	for (const skillPath of skillPaths) {
-		if (!fs.existsSync(skillPath)) continue;
+		if (!fs.existsSync(skillPath.path)) continue;
 
 		let stat: fs.Stats;
 		try {
-			stat = fs.statSync(skillPath);
+			stat = fs.statSync(skillPath.path);
 		} catch {
-			// Ignore paths that disappear or become unreadable during discovery.
 			continue;
 		}
 
 		if (stat.isFile()) {
-			const fileName = path.basename(skillPath);
+			const fileName = path.basename(skillPath.path);
 			if (!fileName.toLowerCase().endsWith(".md")) continue;
 			const skillName = fileName.toLowerCase() === "skill.md"
-				? path.basename(path.dirname(skillPath))
+				? path.basename(path.dirname(skillPath.path))
 				: path.basename(fileName, path.extname(fileName));
-			pushEntry(skillName, skillPath);
+			pushEntry(skillName, skillPath.path, skillPath.source);
 			continue;
 		}
 
 		if (!stat.isDirectory()) continue;
 
-		const rootSkillFile = path.join(skillPath, "SKILL.md");
+		const rootSkillFile = path.join(skillPath.path, "SKILL.md");
 		if (fs.existsSync(rootSkillFile)) {
-			pushEntry(path.basename(skillPath), rootSkillFile);
+			pushEntry(path.basename(skillPath.path), rootSkillFile, skillPath.source);
 		}
 
 		let childEntries: fs.Dirent[];
 		try {
-			childEntries = fs.readdirSync(skillPath, { withFileTypes: true });
+			childEntries = fs.readdirSync(skillPath.path, { withFileTypes: true });
 		} catch {
-			// Ignore unreadable skill directories and continue scanning.
 			continue;
 		}
 
 		for (const child of childEntries) {
 			if (child.name.startsWith(".")) continue;
-			const childPath = path.join(skillPath, child.name);
+			const childPath = path.join(skillPath.path, child.name);
 			if (child.isDirectory() || child.isSymbolicLink()) {
 				const nestedSkillPath = path.join(childPath, "SKILL.md");
 				if (fs.existsSync(nestedSkillPath)) {
-					pushEntry(child.name, nestedSkillPath);
+					pushEntry(child.name, nestedSkillPath, skillPath.source);
 				}
 				continue;
 			}
 			if (child.isFile() && child.name.toLowerCase().endsWith(".md")) {
-				pushEntry(path.basename(child.name, path.extname(child.name)), childPath);
+				pushEntry(path.basename(child.name, path.extname(child.name)), childPath, skillPath.source);
 			}
 		}
 	}
@@ -418,6 +492,22 @@ export function resolveSkills(
 	return { resolved, missing };
 }
 
+export function resolveSkillsWithFallback(
+	skillNames: string[],
+	primaryCwd: string,
+	fallbackCwd?: string,
+): { resolved: ResolvedSkill[]; missing: string[] } {
+	const primary = resolveSkills(skillNames, primaryCwd);
+	if (!fallbackCwd || primary.missing.length === 0) return primary;
+	if (path.resolve(primaryCwd) === path.resolve(fallbackCwd)) return primary;
+
+	const fallback = resolveSkills(primary.missing, fallbackCwd);
+	return {
+		resolved: [...primary.resolved, ...fallback.resolved],
+		missing: fallback.missing,
+	};
+}
+
 export function buildSkillInjection(skills: ResolvedSkill[]): string {
 	if (skills.length === 0) return "";