@ashx-j/lunr 0.1.0

package/dist/builtin-extensions/pi-subagents/src/agents/proactive-skills.js

@@ -0,0 +1,151 @@
+const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
+const DEFAULT_MIN_REFERENCES = 2;
+const DEFAULT_MAX_RECOMMENDATIONS = 3;
+const DEFAULT_PREFERRED_AGENT = "reviewer";
+const FALLBACK_AGENT_ORDER = ["reviewer", "context-builder", "delegate"];
+const MAX_RECOMMENDATION_CAP = 5;
+function positiveInteger(value) {
+    if (typeof value !== "number")
+        return undefined;
+    if (!Number.isInteger(value) || !Number.isFinite(value) || value < 1)
+        return undefined;
+    return value;
+}
+export function resolveProactiveSkillSubagentsConfig(config) {
+    if (config === false) {
+        return {
+            enabled: false,
+            minReferences: DEFAULT_MIN_REFERENCES,
+            maxRecommendations: DEFAULT_MAX_RECOMMENDATIONS,
+            preferredAgent: DEFAULT_PREFERRED_AGENT,
+        };
+    }
+    const maxRecommendations = positiveInteger(config?.maxRecommendations) ?? DEFAULT_MAX_RECOMMENDATIONS;
+    return {
+        enabled: config?.enabled ?? true,
+        minReferences: positiveInteger(config?.minReferences) ?? DEFAULT_MIN_REFERENCES,
+        maxRecommendations: Math.min(maxRecommendations, MAX_RECOMMENDATION_CAP),
+        preferredAgent: typeof config?.preferredAgent === "string" && config.preferredAgent.trim()
+            ? config.preferredAgent.trim()
+            : DEFAULT_PREFERRED_AGENT,
+    };
+}
+function normalizeSkillNames(value) {
+    if (value === false || value === true || value === undefined || value === null)
+        return [];
+    if (Array.isArray(value)) {
+        return [...new Set(value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean))];
+    }
+    if (typeof value === "string") {
+        return [...new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean))];
+    }
+    return [];
+}
+function collectStepSkills(step, out) {
+    for (const skill of normalizeSkillNames(step.skills ?? step.skill)) {
+        out.add(skill);
+    }
+    const parallel = step.parallel;
+    if (!parallel)
+        return;
+    if (Array.isArray(parallel)) {
+        for (const child of parallel) {
+            if (child && typeof child === "object" && !Array.isArray(child)) {
+                collectStepSkills(child, out);
+            }
+        }
+        return;
+    }
+    if (typeof parallel === "object") {
+        collectStepSkills(parallel, out);
+    }
+}
+function chooseRecommendationAgent(agents, preferredAgent) {
+    const enabled = agents.filter((agent) => !agent.disabled);
+    if (enabled.some((agent) => agent.name === preferredAgent))
+        return preferredAgent;
+    for (const name of FALLBACK_AGENT_ORDER) {
+        if (enabled.some((agent) => agent.name === name))
+            return name;
+    }
+    return enabled[0]?.name;
+}
+function addSource(counts, skill, source) {
+    if (skill === SUBAGENT_ORCHESTRATION_SKILL)
+        return;
+    const sources = counts.get(skill) ?? new Set();
+    sources.add(source);
+    counts.set(skill, sources);
+}
+export function recommendProactiveSkillSubagents(input) {
+    const config = resolveProactiveSkillSubagentsConfig(input.config);
+    if (!config.enabled)
+        return [];
+    const agent = chooseRecommendationAgent(input.agents, config.preferredAgent);
+    if (!agent)
+        return [];
+    const availableByName = input.availableSkills
+        ? new Map(input.availableSkills.map((skill) => [skill.name, skill]))
+        : undefined;
+    const counts = new Map();
+    for (const candidate of input.agents) {
+        if (candidate.disabled)
+            continue;
+        for (const skill of candidate.skills ?? []) {
+            addSource(counts, skill, `agent:${candidate.name}`);
+        }
+    }
+    for (const chain of input.chains ?? []) {
+        const chainSkills = new Set();
+        for (const step of chain.steps) {
+            collectStepSkills(step, chainSkills);
+        }
+        for (const skill of chainSkills) {
+            addSource(counts, skill, `chain:${chain.name}`);
+        }
+    }
+    return [...counts.entries()]
+        .filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))
+        .map(([skill, sources]) => ({
+        skill,
+        agent,
+        references: sources.size,
+        sources: [...sources].sort((a, b) => a.localeCompare(b)),
+        description: availableByName?.get(skill)?.description,
+        reason: `referenced by ${sources.size} configured agents/chains`,
+    }))
+        .sort((a, b) => b.references - a.references || a.skill.localeCompare(b.skill))
+        .slice(0, config.maxRecommendations);
+}
+export function formatProactiveSkillSubagentRecommendations(recommendations) {
+    if (recommendations.length === 0)
+        return [];
+    return [
+        "Proactive skill subagent suggestions:",
+        ...recommendations.map((recommendation) => {
+            const sampleSources = recommendation.sources.slice(0, 3).join(", ");
+            const extra = recommendation.sources.length > 3 ? `, +${recommendation.sources.length - 3} more` : "";
+            const description = recommendation.description ? ` - ${recommendation.description}` : "";
+            return `- ${recommendation.skill} via ${recommendation.agent} (${recommendation.reason}; ${sampleSources}${extra})${description}`;
+        }),
+        "Guardrails: use these for broad tasks where a skill-specialist pass is useful; keep fanout small, use fresh context unless private/session context is explicitly needed, and skip when the user asks for a direct answer.",
+    ];
+}
+export function buildProactiveSkillSubagentRecommendationLines(input) {
+    if (!resolveProactiveSkillSubagentsConfig(input.config).enabled)
+        return [];
+    let availableSkills;
+    try {
+        availableSkills = input.discoverAvailableSkills();
+    }
+    catch {
+        availableSkills = [];
+    }
+    return formatProactiveSkillSubagentRecommendations(recommendProactiveSkillSubagents({
+        agents: input.agents,
+        chains: input.chains,
+        availableSkills,
+        config: input.config,
+    }));
+}
+//# sourceMappingURL=proactive-skills.js.map

package/dist/builtin-extensions/pi-subagents/src/agents/proactive-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive-skills.js","sourceRoot":"","sources":["../../../../../src/builtin-extensions/pi-subagents/src/agents/proactive-skills.ts"],"names":[],"mappings":"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","sourcesContent":["// @ts-nocheck\nimport type { AgentConfig, ChainConfig, ChainStepConfig } from \"./agents.ts\";\nimport type { ProactiveSkillSubagentsConfig } from \"../shared/types.ts\";\n\nconst SUBAGENT_ORCHESTRATION_SKILL = \"pi-subagents\";\nconst DEFAULT_MIN_REFERENCES = 2;\nconst DEFAULT_MAX_RECOMMENDATIONS = 3;\nconst DEFAULT_PREFERRED_AGENT = \"reviewer\";\nconst FALLBACK_AGENT_ORDER = [\"reviewer\", \"context-builder\", \"delegate\"];\nconst MAX_RECOMMENDATION_CAP = 5;\n\nexport interface ResolvedProactiveSkillSubagentsConfig {\n\tenabled: boolean;\n\tminReferences: number;\n\tmaxRecommendations: number;\n\tpreferredAgent: string;\n}\n\nexport interface ProactiveSkillSubagentRecommendation {\n\tskill: string;\n\tagent: string;\n\treferences: number;\n\tsources: string[];\n\tdescription?: string;\n\treason: string;\n}\n\nexport interface AvailableSkill {\n\tname: string;\n\tdescription?: string;\n}\n\nfunction positiveInteger(value: unknown): number | undefined {\n\tif (typeof value !== \"number\") return undefined;\n\tif (!Number.isInteger(value) || !Number.isFinite(value) || value < 1) return undefined;\n\treturn value;\n}\n\nexport function resolveProactiveSkillSubagentsConfig(\n\tconfig?: ProactiveSkillSubagentsConfig | false,\n): ResolvedProactiveSkillSubagentsConfig {\n\tif (config === false) {\n\t\treturn {\n\t\t\tenabled: false,\n\t\t\tminReferences: DEFAULT_MIN_REFERENCES,\n\t\t\tmaxRecommendations: DEFAULT_MAX_RECOMMENDATIONS,\n\t\t\tpreferredAgent: DEFAULT_PREFERRED_AGENT,\n\t\t};\n\t}\n\n\tconst maxRecommendations = positiveInteger(config?.maxRecommendations) ?? DEFAULT_MAX_RECOMMENDATIONS;\n\treturn {\n\t\tenabled: config?.enabled ?? true,\n\t\tminReferences: positiveInteger(config?.minReferences) ?? DEFAULT_MIN_REFERENCES,\n\t\tmaxRecommendations: Math.min(maxRecommendations, MAX_RECOMMENDATION_CAP),\n\t\tpreferredAgent: typeof config?.preferredAgent === \"string\" && config.preferredAgent.trim()\n\t\t\t? config.preferredAgent.trim()\n\t\t\t: DEFAULT_PREFERRED_AGENT,\n\t};\n}\n\nfunction normalizeSkillNames(value: unknown): string[] {\n\tif (value === false || value === true || value === undefined || value === null) return [];\n\tif (Array.isArray(value)) {\n\t\treturn [...new Set(value.filter((entry): entry is string => typeof entry === \"string\").map((entry) => entry.trim()).filter(Boolean))];\n\t}\n\tif (typeof value === \"string\") {\n\t\treturn [...new Set(value.split(\",\").map((entry) => entry.trim()).filter(Boolean))];\n\t}\n\treturn [];\n}\n\nfunction collectStepSkills(step: ChainStepConfig, out: Set<string>): void {\n\tfor (const skill of normalizeSkillNames(step.skills ?? (step as { skill?: unknown }).skill)) {\n\t\tout.add(skill);\n\t}\n\n\tconst parallel = step.parallel;\n\tif (!parallel) return;\n\tif (Array.isArray(parallel)) {\n\t\tfor (const child of parallel) {\n\t\t\tif (child && typeof child === \"object\" && !Array.isArray(child)) {\n\t\t\t\tcollectStepSkills(child as ChainStepConfig, out);\n\t\t\t}\n\t\t}\n\t\treturn;\n\t}\n\tif (typeof parallel === \"object\") {\n\t\tcollectStepSkills(parallel as ChainStepConfig, out);\n\t}\n}\n\nfunction chooseRecommendationAgent(agents: AgentConfig[], preferredAgent: string): string | undefined {\n\tconst enabled = agents.filter((agent) => !agent.disabled);\n\tif (enabled.some((agent) => agent.name === preferredAgent)) return preferredAgent;\n\tfor (const name of FALLBACK_AGENT_ORDER) {\n\t\tif (enabled.some((agent) => agent.name === name)) return name;\n\t}\n\treturn enabled[0]?.name;\n}\n\nfunction addSource(counts: Map<string, Set<string>>, skill: string, source: string): void {\n\tif (skill === SUBAGENT_ORCHESTRATION_SKILL) return;\n\tconst sources = counts.get(skill) ?? new Set<string>();\n\tsources.add(source);\n\tcounts.set(skill, sources);\n}\n\nexport function recommendProactiveSkillSubagents(input: {\n\tagents: AgentConfig[];\n\tchains?: ChainConfig[];\n\tavailableSkills?: AvailableSkill[];\n\tconfig?: ProactiveSkillSubagentsConfig | false;\n}): ProactiveSkillSubagentRecommendation[] {\n\tconst config = resolveProactiveSkillSubagentsConfig(input.config);\n\tif (!config.enabled) return [];\n\n\tconst agent = chooseRecommendationAgent(input.agents, config.preferredAgent);\n\tif (!agent) return [];\n\n\tconst availableByName = input.availableSkills\n\t\t? new Map(input.availableSkills.map((skill) => [skill.name, skill]))\n\t\t: undefined;\n\tconst counts = new Map<string, Set<string>>();\n\n\tfor (const candidate of input.agents) {\n\t\tif (candidate.disabled) continue;\n\t\tfor (const skill of candidate.skills ?? []) {\n\t\t\taddSource(counts, skill, `agent:${candidate.name}`);\n\t\t}\n\t}\n\n\tfor (const chain of input.chains ?? []) {\n\t\tconst chainSkills = new Set<string>();\n\t\tfor (const step of chain.steps) {\n\t\t\tcollectStepSkills(step, chainSkills);\n\t\t}\n\t\tfor (const skill of chainSkills) {\n\t\t\taddSource(counts, skill, `chain:${chain.name}`);\n\t\t}\n\t}\n\n\treturn [...counts.entries()]\n\t\t.filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))\n\t\t.map(([skill, sources]) => ({\n\t\t\tskill,\n\t\t\tagent,\n\t\t\treferences: sources.size,\n\t\t\tsources: [...sources].sort((a, b) => a.localeCompare(b)),\n\t\t\tdescription: availableByName?.get(skill)?.description,\n\t\t\treason: `referenced by ${sources.size} configured agents/chains`,\n\t\t}))\n\t\t.sort((a, b) => b.references - a.references || a.skill.localeCompare(b.skill))\n\t\t.slice(0, config.maxRecommendations);\n}\n\nexport function formatProactiveSkillSubagentRecommendations(\n\trecommendations: ProactiveSkillSubagentRecommendation[],\n): string[] {\n\tif (recommendations.length === 0) return [];\n\treturn [\n\t\t\"Proactive skill subagent suggestions:\",\n\t\t...recommendations.map((recommendation) => {\n\t\t\tconst sampleSources = recommendation.sources.slice(0, 3).join(\", \");\n\t\t\tconst extra = recommendation.sources.length > 3 ? `, +${recommendation.sources.length - 3} more` : \"\";\n\t\t\tconst description = recommendation.description ? ` - ${recommendation.description}` : \"\";\n\t\t\treturn `- ${recommendation.skill} via ${recommendation.agent} (${recommendation.reason}; ${sampleSources}${extra})${description}`;\n\t\t}),\n\t\t\"Guardrails: use these for broad tasks where a skill-specialist pass is useful; keep fanout small, use fresh context unless private/session context is explicitly needed, and skip when the user asks for a direct answer.\",\n\t];\n}\n\nexport function buildProactiveSkillSubagentRecommendationLines(input: {\n\tagents: AgentConfig[];\n\tchains?: ChainConfig[];\n\tconfig?: ProactiveSkillSubagentsConfig | false;\n\tdiscoverAvailableSkills: () => AvailableSkill[];\n}): string[] {\n\tif (!resolveProactiveSkillSubagentsConfig(input.config).enabled) return [];\n\tlet availableSkills: AvailableSkill[];\n\ttry {\n\t\tavailableSkills = input.discoverAvailableSkills();\n\t} catch {\n\t\tavailableSkills = [];\n\t}\n\treturn formatProactiveSkillSubagentRecommendations(recommendProactiveSkillSubagents({\n\t\tagents: input.agents,\n\t\tchains: input.chains,\n\t\tavailableSkills,\n\t\tconfig: input.config,\n\t}));\n}\n"]}

package/dist/builtin-extensions/pi-subagents/src/agents/skills.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Skill resolution and caching for subagent extension
+ */
+export type SkillSource = "project" | "user" | "project-package" | "user-package" | "project-settings" | "user-settings" | "extension" | "builtin" | "unknown";
+interface ResolvedSkill {
+    name: string;
+    path: string;
+    content: string;
+    description?: string;
+    source: SkillSource;
+}
+export declare function resolveSkillPath(skillName: string, cwd: string): {
+    path: string;
+    source: SkillSource;
+} | undefined;
+export declare function resolveSkills(skillNames: string[], cwd: string, localSkillPaths?: string[], localBaseDir?: string): {
+    resolved: ResolvedSkill[];
+    missing: string[];
+};
+export declare function resolveSkillsWithFallback(skillNames: string[], primaryCwd: string, fallbackCwd?: string, localSkillPaths?: string[], localBaseDir?: string): {
+    resolved: ResolvedSkill[];
+    missing: string[];
+};
+export declare function buildSkillInjection(skills: ResolvedSkill[]): string;
+export declare function normalizeSkillInput(input: string | string[] | boolean | undefined): string[] | false | undefined;
+export declare function discoverAvailableSkills(cwd: string): Array<{
+    name: string;
+    source: SkillSource;
+    description?: string;
+}>;
+export declare function clearSkillCache(): void;
+export {};
+//# sourceMappingURL=skills.d.ts.map

package/dist/builtin-extensions/pi-subagents/src/agents/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../../../src/builtin-extensions/pi-subagents/src/agents/skills.ts"],"names":[],"mappings":"AACA;;GAEG;AAQH,MAAM,MAAM,WAAW,GACpB,SAAS,GACT,MAAM,GACN,iBAAiB,GACjB,cAAc,GACd,kBAAkB,GAClB,eAAe,GACf,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEb,UAAU,aAAa;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;CACpB;AAshBD,wBAAgB,gBAAgB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACT;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,SAAS,CAKnD;AAsCD,wBAAgB,aAAa,CAC5B,UAAU,EAAE,MAAM,EAAE,EACpB,GAAG,EAAE,MAAM,EACX,eAAe,CAAC,EAAE,MAAM,EAAE,EAC1B,YAAY,CAAC,EAAE,MAAM,GACnB;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkClD;AAED,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,EAAE,EAC1B,YAAY,CAAC,EAAE,MAAM,GACnB;IAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAUlD;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAmBnE;AASD,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,GAC5C,MAAM,EAAE,GAAG,KAAK,GAAG,SAAS,CAsB9B;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAUD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAGtC","sourcesContent":["// @ts-nocheck\n/**\n * Skill resolution and caching for subagent extension\n */\n\nimport { execSync } from \"node:child_process\";\nimport * as fs from \"node:fs\";\nimport * as os from \"node:os\";\nimport * as path from \"node:path\";\nimport { getAgentDir, getProjectConfigDir } from \"../shared/utils.ts\";\n\nexport type SkillSource =\n\t| \"project\"\n\t| \"user\"\n\t| \"project-package\"\n\t| \"user-package\"\n\t| \"project-settings\"\n\t| \"user-settings\"\n\t| \"extension\"\n\t| \"builtin\"\n\t| \"unknown\";\n\ninterface ResolvedSkill {\n\tname: string;\n\tpath: string;\n\tcontent: string;\n\tdescription?: string;\n\tsource: SkillSource;\n}\n\ninterface SkillCacheEntry {\n\tmtime: number;\n\tskill: ResolvedSkill;\n}\n\ninterface CachedSkillEntry {\n\tname: string;\n\tfilePath: string;\n\tsource: SkillSource;\n\tdescription?: string;\n\torder: number;\n}\n\ninterface SkillSearchPath {\n\tpath: string;\n\tsource: SkillSource;\n}\n\nconst skillCache = new Map<string, SkillCacheEntry>();\nconst MAX_CACHE_SIZE = 50;\n\nlet loadSkillsCache: { cwd: string; agentDir: string; skills: CachedSkillEntry[]; timestamp: number } | null = null;\nconst LOAD_SKILLS_CACHE_TTL_MS = 5000;\n\nconst SUBAGENT_ORCHESTRATION_SKILL = \"pi-subagents\";\n\nconst SOURCE_PRIORITY: Record<SkillSource, number> = {\n\tproject: 700,\n\t\"project-settings\": 650,\n\t\"project-package\": 600,\n\tuser: 300,\n\t\"user-settings\": 250,\n\t\"user-package\": 200,\n\textension: 150,\n\tbuiltin: 100,\n\tunknown: 0,\n};\n\nfunction stripSkillFrontmatter(content: string): string {\n\tconst normalized = content.replace(/\\r\\n/g, \"\\n\");\n\tif (!normalized.startsWith(\"---\")) return normalized;\n\n\tconst endIndex = normalized.indexOf(\"\\n---\", 3);\n\tif (endIndex === -1) return normalized;\n\n\treturn normalized.slice(endIndex + 4).trim();\n}\n\nfunction isWithinPath(filePath: string, dir: string): boolean {\n\tconst relative = path.relative(dir, filePath);\n\treturn relative === \"\" || (!relative.startsWith(\"..\") && !path.isAbsolute(relative));\n}\n\nfunction readOptionalJsonFile(filePath: string, label: string): unknown {\n\ttry {\n\t\treturn JSON.parse(fs.readFileSync(filePath, \"utf-8\"));\n\t} catch (error) {\n\t\tconst code = typeof error === \"object\" && error !== null && \"code\" in error\n\t\t\t? (error as { code?: unknown }).code\n\t\t\t: undefined;\n\t\tif (code === \"ENOENT\") return null;\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tthrow new Error(`Failed to read ${label} '${filePath}': ${message}`, {\n\t\t\tcause: error instanceof Error ? error : undefined,\n\t\t});\n\t}\n}\n\nfunction readJsonFileBestEffort(filePath: string): unknown {\n\ttry {\n\t\treturn JSON.parse(fs.readFileSync(filePath, \"utf-8\"));\n\t} catch {\n\t\t// Package scans over installed dependencies are opportunistic.\n\t\treturn null;\n\t}\n}\n\nfunction extractSkillPathsFromPackageRoot(packageRoot: string, source: SkillSource, bestEffort = false): SkillSearchPath[] {\n\tconst packageJsonPath = path.join(packageRoot, \"package.json\");\n\tconst pkg = bestEffort\n\t\t? readJsonFileBestEffort(packageJsonPath)\n\t\t: readOptionalJsonFile(packageJsonPath, \"package manifest\");\n\tif (!pkg || typeof pkg !== \"object\" || Array.isArray(pkg)) return [];\n\tconst pi = (pkg as { pi?: unknown }).pi;\n\tif (!pi || typeof pi !== \"object\" || Array.isArray(pi)) return [];\n\tconst skills = (pi as { skills?: unknown }).skills;\n\tif (!Array.isArray(skills)) return [];\n\treturn skills\n\t\t.filter((entry): entry is string => typeof entry === \"string\")\n\t\t.map((entry) => ({ path: path.resolve(packageRoot, entry), source }));\n}\n\nlet cachedGlobalNpmRoot: string | null = null;\n\nfunction getGlobalNpmRoot(): string | null {\n\tif (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;\n\ttry {\n\t\tcachedGlobalNpmRoot = execSync(\"npm root -g\", { encoding: \"utf-8\", timeout: 5000 }).trim();\n\t\treturn cachedGlobalNpmRoot;\n\t} catch {\n\t\t// Global npm root is optional in constrained environments.\n\t\tcachedGlobalNpmRoot = \"\"; // Empty string means \"tried but failed\"\n\t\treturn null;\n\t}\n}\n\nfunction collectInstalledPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {\n\tconst projectConfigDir = getProjectConfigDir(cwd);\n\tconst dirs: SkillSearchPath[] = [\n\t\t{ path: path.join(projectConfigDir, \"npm\", \"node_modules\"), source: \"project-package\" },\n\t\t{ path: path.join(agentDir, \"npm\", \"node_modules\"), source: \"user-package\" },\n\t];\n\n\tconst globalRoot = getGlobalNpmRoot();\n\tif (globalRoot) {\n\t\tdirs.push({ path: globalRoot, source: \"user-package\" });\n\t}\n\n\tconst results: SkillSearchPath[] = [];\n\n\tfor (const dir of dirs) {\n\t\tif (!fs.existsSync(dir.path)) continue;\n\t\tlet entries: fs.Dirent[];\n\t\ttry {\n\t\t\tentries = fs.readdirSync(dir.path, { withFileTypes: true });\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\n\t\tfor (const entry of entries) {\n\t\t\tif (entry.name.startsWith(\".\")) continue;\n\t\t\tif (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\n\t\t\tif (entry.name.startsWith(\"@\")) {\n\t\t\t\tconst scopeDir = path.join(dir.path, entry.name);\n\t\t\t\tlet scopeEntries: fs.Dirent[];\n\t\t\t\ttry {\n\t\t\t\t\tscopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });\n\t\t\t\t} catch {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tfor (const scopeEntry of scopeEntries) {\n\t\t\t\t\tif (scopeEntry.name.startsWith(\".\")) continue;\n\t\t\t\t\tif (!scopeEntry.isDirectory() && !scopeEntry.isSymbolicLink()) continue;\n\t\t\t\t\tconst pkgRoot = path.join(scopeDir, scopeEntry.name);\n\t\t\t\t\tresults.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst pkgRoot = path.join(dir.path, entry.name);\n\t\t\tresults.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));\n\t\t}\n\t}\n\n\treturn results;\n}\n\nfunction collectSettingsSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {\n\tconst results: SkillSearchPath[] = [];\n\tconst projectConfigDir = getProjectConfigDir(cwd);\n\tconst settingsFiles = [\n\t\t{ file: path.join(projectConfigDir, \"settings.json\"), base: projectConfigDir, source: \"project-settings\" as const },\n\t\t{ file: path.join(agentDir, \"settings.json\"), base: agentDir, source: \"user-settings\" as const },\n\t];\n\n\tfor (const { file, base, source } of settingsFiles) {\n\t\tconst settings = readOptionalJsonFile(file, \"skills settings file\");\n\t\tif (!settings || typeof settings !== \"object\" || Array.isArray(settings)) continue;\n\t\tconst skills = (settings as { skills?: unknown }).skills;\n\t\tif (!Array.isArray(skills)) continue;\n\t\tfor (const entry of skills) {\n\t\t\tif (typeof entry !== \"string\") continue;\n\t\t\tlet resolved = entry;\n\t\t\tif (resolved.startsWith(\"~/\")) {\n\t\t\t\tresolved = path.join(os.homedir(), resolved.slice(2));\n\t\t\t} else if (!path.isAbsolute(resolved)) {\n\t\t\t\tresolved = path.resolve(base, resolved);\n\t\t\t}\n\t\t\tresults.push({ path: resolved, source });\n\t\t}\n\t}\n\n\treturn results;\n}\n\nfunction isSafePackagePath(value: string): boolean {\n\treturn value.length > 0\n\t\t&& !path.isAbsolute(value)\n\t\t&& value.split(/[\\\\/]/).every((part) => part.length > 0 && part !== \".\" && part !== \"..\");\n}\n\nfunction parseNpmPackageName(source: string): string | undefined {\n\tconst spec = source.slice(4).trim();\n\tif (!spec) return undefined;\n\tconst match = spec.match(/^(@?[^@]+(?:\\/[^@]+)?)(?:@(.+))?$/);\n\tconst packageName = match?.[1] ?? spec;\n\treturn isSafePackagePath(packageName) ? packageName : undefined;\n}\n\nfunction stripGitRef(repoPath: string): string {\n\tconst atIndex = repoPath.indexOf(\"@\");\n\tconst hashIndex = repoPath.indexOf(\"#\");\n\tconst refIndex = [atIndex, hashIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];\n\treturn refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);\n}\n\nfunction parseGitPackagePath(source: string): { host: string; repoPath: string } | undefined {\n\tconst spec = source.slice(4).trim();\n\tif (!spec) return undefined;\n\n\tlet host = \"\";\n\tlet repoPath = \"\";\n\tconst scpLike = spec.match(/^git@([^:]+):(.+)$/);\n\tif (scpLike) {\n\t\thost = scpLike[1] ?? \"\";\n\t\trepoPath = scpLike[2] ?? \"\";\n\t} else if (/^[a-z][a-z0-9+.-]*:\\/\\//i.test(spec)) {\n\t\ttry {\n\t\t\tconst url = new URL(spec);\n\t\t\thost = url.hostname;\n\t\t\trepoPath = url.pathname.replace(/^\\/+/, \"\");\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t} else {\n\t\tconst slashIndex = spec.indexOf(\"/\");\n\t\tif (slashIndex < 0) return undefined;\n\t\thost = spec.slice(0, slashIndex);\n\t\trepoPath = spec.slice(slashIndex + 1);\n\t}\n\n\tconst normalizedPath = stripGitRef(repoPath).replace(/\\.git$/, \"\").replace(/^\\/+/, \"\");\n\tif (!host || !isSafePackagePath(host) || !isSafePackagePath(normalizedPath) || normalizedPath.split(/[\\\\/]/).length < 2) {\n\t\treturn undefined;\n\t}\n\treturn { host, repoPath: normalizedPath };\n}\n\nfunction resolveSettingsPackageRoot(source: string, baseDir: string): string | undefined {\n\tconst trimmed = source.trim();\n\tif (!trimmed) return undefined;\n\tif (trimmed.startsWith(\"git:\")) {\n\t\tconst parsed = parseGitPackagePath(trimmed);\n\t\treturn parsed ? path.join(baseDir, \"git\", parsed.host, parsed.repoPath) : undefined;\n\t}\n\tif (trimmed.startsWith(\"npm:\")) {\n\t\tconst packageName = parseNpmPackageName(trimmed);\n\t\treturn packageName ? path.join(baseDir, \"npm\", \"node_modules\", packageName) : undefined;\n\t}\n\tconst normalized = trimmed.startsWith(\"file:\") ? trimmed.slice(5) : trimmed;\n\tif (normalized === \"~\") return os.homedir();\n\tif (normalized.startsWith(\"~/\")) return path.join(os.homedir(), normalized.slice(2));\n\tif (path.isAbsolute(normalized)) return normalized;\n\tif (normalized === \".\" || normalized === \"..\" || normalized.startsWith(\"./\") || normalized.startsWith(\"../\")) {\n\t\treturn path.resolve(baseDir, normalized);\n\t}\n\treturn undefined;\n}\n\nfunction collectSettingsPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {\n\tconst projectConfigDir = getProjectConfigDir(cwd);\n\tconst settingsFiles = [\n\t\t{ file: path.join(projectConfigDir, \"settings.json\"), base: projectConfigDir, source: \"project-package\" as const },\n\t\t{ file: path.join(agentDir, \"settings.json\"), base: agentDir, source: \"user-package\" as const },\n\t];\n\tconst results: SkillSearchPath[] = [];\n\n\tfor (const { file, base, source } of settingsFiles) {\n\t\tconst settings = readOptionalJsonFile(file, \"skills settings file\");\n\t\tif (!settings || typeof settings !== \"object\" || Array.isArray(settings)) continue;\n\t\tconst packages = (settings as { packages?: unknown }).packages;\n\t\tif (!Array.isArray(packages)) continue;\n\n\t\tfor (const entry of packages) {\n\t\t\tconst packageSource = typeof entry === \"string\"\n\t\t\t\t? entry\n\t\t\t\t: typeof entry === \"object\" && entry !== null && typeof (entry as { source?: unknown }).source === \"string\"\n\t\t\t\t\t? (entry as { source: string }).source\n\t\t\t\t\t: undefined;\n\t\t\tif (!packageSource) continue;\n\n\t\t\tconst packageRoot = resolveSettingsPackageRoot(packageSource, base);\n\t\t\tif (!packageRoot) continue;\n\t\t\tresults.push(...extractSkillPathsFromPackageRoot(packageRoot, source));\n\t\t}\n\t}\n\n\treturn results;\n}\n\nfunction buildSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {\n\tconst projectConfigDir = getProjectConfigDir(cwd);\n\tconst skillPaths: SkillSearchPath[] = [\n\t\t{ path: path.join(projectConfigDir, \"skills\"), source: \"project\" },\n\t\t{ path: path.join(cwd, \".agents\", \"skills\"), source: \"project\" },\n\t\t{ path: path.join(agentDir, \"skills\"), source: \"user\" },\n\t\t{ path: path.join(os.homedir(), \".agents\", \"skills\"), source: \"user\" },\n\t\t...collectInstalledPackageSkillPaths(cwd, agentDir),\n\t\t...collectSettingsPackageSkillPaths(cwd, agentDir),\n\t\t...extractSkillPathsFromPackageRoot(cwd, \"project-package\"),\n\t\t...collectSettingsSkillPaths(cwd, agentDir),\n\t];\n\n\tconst deduped = new Map<string, SkillSearchPath>();\n\tfor (const entry of skillPaths) {\n\t\tconst resolvedPath = path.resolve(entry.path);\n\t\tconst existing = deduped.get(resolvedPath);\n\t\tif (!existing || (SOURCE_PRIORITY[entry.source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {\n\t\t\tdeduped.set(resolvedPath, { path: resolvedPath, source: entry.source });\n\t\t}\n\t}\n\treturn [...deduped.values()];\n}\n\nfunction inferSkillSource(filePath: string, cwd: string, agentDir: string, sourceHint?: SkillSource): SkillSource {\n\tif (sourceHint) return sourceHint;\n\n\tconst projectConfigRoot = path.resolve(getProjectConfigDir(cwd));\n\tconst projectSkillsRoot = path.resolve(projectConfigRoot, \"skills\");\n\tconst projectPackagesRoot = path.resolve(projectConfigRoot, \"npm\", \"node_modules\");\n\tconst projectAgentsRoot = path.resolve(cwd, \".agents\");\n\tconst userSkillsRoot = path.resolve(agentDir, \"skills\");\n\tconst userPackagesRoot = path.resolve(agentDir, \"npm\", \"node_modules\");\n\tconst userAgentRoot = path.resolve(agentDir);\n\tconst userAgentsRoot = path.resolve(os.homedir(), \".agents\");\n\n\tif (isWithinPath(filePath, projectPackagesRoot)) return \"project-package\";\n\tif (isWithinPath(filePath, projectSkillsRoot) || isWithinPath(filePath, projectAgentsRoot)) return \"project\";\n\tif (isWithinPath(filePath, projectConfigRoot)) return \"project-settings\";\n\n\tif (isWithinPath(filePath, userPackagesRoot)) return \"user-package\";\n\tif (isWithinPath(filePath, userSkillsRoot) || isWithinPath(filePath, userAgentsRoot)) return \"user\";\n\tif (isWithinPath(filePath, userAgentRoot)) return \"user-settings\";\n\n\tconst globalRoot = getGlobalNpmRoot();\n\tif (globalRoot && isWithinPath(filePath, globalRoot)) return \"user-package\";\n\n\treturn \"unknown\";\n}\n\nfunction chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candidate: CachedSkillEntry): CachedSkillEntry {\n\tif (!existing) return candidate;\n\tconst existingPriority = SOURCE_PRIORITY[existing.source] ?? 0;\n\tconst candidatePriority = SOURCE_PRIORITY[candidate.source] ?? 0;\n\tif (candidatePriority > existingPriority) return candidate;\n\tif (candidatePriority < existingPriority) return existing;\n\treturn candidate.order < existing.order ? candidate : existing;\n}\n\nfunction maybeReadSkillDescription(filePath: string): string | undefined {\n\ttry {\n\t\tconst content = fs.readFileSync(filePath, \"utf-8\");\n\t\tconst normalized = content.replace(/\\r\\n/g, \"\\n\");\n\t\tif (!normalized.startsWith(\"---\")) return undefined;\n\n\t\tconst endIndex = normalized.indexOf(\"\\n---\", 3);\n\t\tif (endIndex === -1) return undefined;\n\n\t\tconst frontmatter = normalized.slice(3, endIndex).trim();\n\t\tconst match = frontmatter.match(/^description:\\s*(.+)$/m);\n\t\tif (!match) return undefined;\n\t\treturn match[1]?.trim().replace(/^['\\\"]|['\\\"]$/g, \"\");\n\t} catch {\n\t\t// Description parsing is best-effort metadata extraction.\n\t\treturn undefined;\n\t}\n}\n\nfunction collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {\n\tconst entries: CachedSkillEntry[] = [];\n\tconst seen = new Map<string, number>();\n\tconst visitedDirectories = new Map<string, number>();\n\tlet order = 0;\n\n\tconst pushEntry = (name: string, filePath: string, sourceHint?: SkillSource) => {\n\t\tconst resolvedFile = path.resolve(filePath);\n\t\tif (!fs.existsSync(resolvedFile)) return;\n\t\tconst source = inferSkillSource(resolvedFile, cwd, agentDir, sourceHint);\n\t\tconst existingIndex = seen.get(resolvedFile);\n\t\tif (existingIndex !== undefined) {\n\t\t\tconst existing = entries[existingIndex];\n\t\t\tif (existing && (SOURCE_PRIORITY[source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {\n\t\t\t\tentries[existingIndex] = {\n\t\t\t\t\t...existing,\n\t\t\t\t\tname,\n\t\t\t\t\tsource,\n\t\t\t\t\tdescription: maybeReadSkillDescription(resolvedFile),\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tseen.set(resolvedFile, entries.length);\n\t\tentries.push({\n\t\t\tname,\n\t\t\tfilePath: resolvedFile,\n\t\t\tsource,\n\t\t\tdescription: maybeReadSkillDescription(resolvedFile),\n\t\t\torder: order++,\n\t\t});\n\t};\n\n\tconst shouldSkipDirectory = (name: string) => name.startsWith(\".\") || name === \"node_modules\";\n\n\tconst markDirectoryVisited = (dirPath: string, sourceHint?: SkillSource): boolean => {\n\t\tlet resolvedDir: string;\n\t\ttry {\n\t\t\tresolvedDir = fs.realpathSync(dirPath);\n\t\t} catch {\n\t\t\tresolvedDir = path.resolve(dirPath);\n\t\t}\n\t\tconst priority = sourceHint ? SOURCE_PRIORITY[sourceHint] ?? 0 : SOURCE_PRIORITY.unknown;\n\t\tconst previousPriority = visitedDirectories.get(resolvedDir);\n\t\tif (previousPriority !== undefined && previousPriority >= priority) return false;\n\t\tvisitedDirectories.set(resolvedDir, priority);\n\t\treturn true;\n\t};\n\n\tconst walkSkillDirectories = (dirPath: string, sourceHint?: SkillSource) => {\n\t\tif (!markDirectoryVisited(dirPath, sourceHint)) return;\n\n\t\tconst skillFile = path.join(dirPath, \"SKILL.md\");\n\t\tif (fs.existsSync(skillFile)) {\n\t\t\tpushEntry(path.basename(dirPath), skillFile, sourceHint);\n\t\t\treturn;\n\t\t}\n\n\t\tlet entriesInDir: fs.Dirent[];\n\t\ttry {\n\t\t\tentriesInDir = fs.readdirSync(dirPath, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (const entry of entriesInDir) {\n\t\t\tif (shouldSkipDirectory(entry.name)) continue;\n\t\t\tif (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\n\t\t\tconst entryPath = path.join(dirPath, entry.name);\n\t\t\tlet stat: fs.Stats;\n\t\t\ttry {\n\t\t\t\tstat = fs.statSync(entryPath);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (stat.isDirectory()) {\n\t\t\t\twalkSkillDirectories(entryPath, sourceHint);\n\t\t\t}\n\t\t}\n\t};\n\n\tfor (const skillPath of skillPaths) {\n\t\tif (!fs.existsSync(skillPath.path)) continue;\n\n\t\tlet stat: fs.Stats;\n\t\ttry {\n\t\t\tstat = fs.statSync(skillPath.path);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (stat.isFile()) {\n\t\t\tconst fileName = path.basename(skillPath.path);\n\t\t\tif (!fileName.toLowerCase().endsWith(\".md\")) continue;\n\t\t\tconst skillName = fileName.toLowerCase() === \"skill.md\"\n\t\t\t\t? path.basename(path.dirname(skillPath.path))\n\t\t\t\t: path.basename(fileName, path.extname(fileName));\n\t\t\tpushEntry(skillName, skillPath.path, skillPath.source);\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (!stat.isDirectory()) continue;\n\n\t\tconst rootSkillFile = path.join(skillPath.path, \"SKILL.md\");\n\t\tif (fs.existsSync(rootSkillFile)) {\n\t\t\tpushEntry(path.basename(skillPath.path), rootSkillFile, skillPath.source);\n\t\t\tcontinue;\n\t\t}\n\n\t\tmarkDirectoryVisited(skillPath.path, skillPath.source);\n\n\t\tlet childEntries: fs.Dirent[];\n\t\ttry {\n\t\t\tchildEntries = fs.readdirSync(skillPath.path, { withFileTypes: true });\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\n\t\tfor (const child of childEntries) {\n\t\t\tif (child.name.startsWith(\".\")) continue;\n\t\t\tconst childPath = path.join(skillPath.path, child.name);\n\t\t\tif (child.isDirectory() || child.isSymbolicLink()) {\n\t\t\t\tif (shouldSkipDirectory(child.name)) continue;\n\t\t\t\tlet childStat: fs.Stats;\n\t\t\t\ttry {\n\t\t\t\t\tchildStat = fs.statSync(childPath);\n\t\t\t\t} catch {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (childStat.isDirectory()) walkSkillDirectories(childPath, skillPath.source);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (child.isFile() && child.name.toLowerCase().endsWith(\".md\")) {\n\t\t\t\tpushEntry(path.basename(child.name, path.extname(child.name)), childPath, skillPath.source);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn entries;\n}\n\nfunction getCachedSkills(cwd: string): CachedSkillEntry[] {\n\tconst now = Date.now();\n\tconst agentDir = getAgentDir();\n\tif (loadSkillsCache && loadSkillsCache.cwd === cwd && loadSkillsCache.agentDir === agentDir && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {\n\t\treturn loadSkillsCache.skills;\n\t}\n\n\tconst skillPaths = buildSkillPaths(cwd, agentDir);\n\tconst loaded = collectFilesystemSkills(cwd, agentDir, skillPaths);\n\tconst dedupedByName = new Map<string, CachedSkillEntry>();\n\n\tfor (const entry of loaded) {\n\t\tconst current = dedupedByName.get(entry.name);\n\t\tdedupedByName.set(entry.name, chooseHigherPrioritySkill(current, entry));\n\t}\n\n\tconst skills = [...dedupedByName.values()].sort((a, b) => a.order - b.order);\n\tloadSkillsCache = { cwd, agentDir, skills, timestamp: now };\n\treturn skills;\n}\n\nexport function resolveSkillPath(\n\tskillName: string,\n\tcwd: string,\n): { path: string; source: SkillSource } | undefined {\n\tconst skills = getCachedSkills(cwd);\n\tconst skill = skills.find((s) => s.name === skillName);\n\tif (!skill) return undefined;\n\treturn { path: skill.filePath, source: skill.source };\n}\n\nfunction readSkill(\n\tskillName: string,\n\tskillPath: string,\n\tsource: SkillSource,\n): ResolvedSkill | undefined {\n\ttry {\n\t\tconst stat = fs.statSync(skillPath);\n\t\tconst cached = skillCache.get(skillPath);\n\t\tif (cached && cached.mtime === stat.mtimeMs) {\n\t\t\treturn cached.skill;\n\t\t}\n\n\t\tconst raw = fs.readFileSync(skillPath, \"utf-8\");\n\t\tconst content = stripSkillFrontmatter(raw);\n\t\tconst description = maybeReadSkillDescription(skillPath);\n\t\tconst skill: ResolvedSkill = {\n\t\t\tname: skillName,\n\t\t\tpath: skillPath,\n\t\t\tcontent,\n\t\t\tdescription,\n\t\t\tsource,\n\t\t};\n\n\t\tskillCache.set(skillPath, { mtime: stat.mtimeMs, skill });\n\t\tif (skillCache.size > MAX_CACHE_SIZE) {\n\t\t\tconst firstKey = skillCache.keys().next().value;\n\t\t\tif (firstKey) skillCache.delete(firstKey);\n\t\t}\n\n\t\treturn skill;\n\t} catch {\n\t\t// Treat unreadable skill files as unresolved so callers can surface as missing.\n\t\treturn undefined;\n\t}\n}\n\nexport function resolveSkills(\n\tskillNames: string[],\n\tcwd: string,\n\tlocalSkillPaths?: string[],\n\tlocalBaseDir?: string,\n): { resolved: ResolvedSkill[]; missing: string[] } {\n\tconst resolved: ResolvedSkill[] = [];\n\tconst missing: string[] = [];\n\tconst localByName = new Map<string, CachedSkillEntry>();\n\tif (localSkillPaths?.length) {\n\t\tconst agentDir = getAgentDir();\n\t\tconst localEntries = collectFilesystemSkills(cwd, agentDir, localSkillPaths.map((entry) => ({\n\t\t\tpath: path.resolve(localBaseDir ?? cwd, entry),\n\t\t\tsource: \"unknown\" as const,\n\t\t})));\n\t\tfor (const entry of localEntries) {\n\t\t\tif (!localByName.has(entry.name)) localByName.set(entry.name, entry);\n\t\t}\n\t}\n\n\tfor (const name of skillNames) {\n\t\tconst trimmed = name.trim();\n\t\tif (!trimmed) continue;\n\t\tif (trimmed === SUBAGENT_ORCHESTRATION_SKILL) {\n\t\t\tmissing.push(trimmed);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst local = localByName.get(trimmed);\n\t\tlet skill = local ? readSkill(trimmed, local.filePath, local.source) : undefined;\n\t\tif (!skill) {\n\t\t\tconst location = resolveSkillPath(trimmed, cwd);\n\t\t\tif (location) skill = readSkill(trimmed, location.path, location.source);\n\t\t}\n\t\tif (skill) resolved.push(skill);\n\t\telse missing.push(trimmed);\n\t}\n\n\treturn { resolved, missing };\n}\n\nexport function resolveSkillsWithFallback(\n\tskillNames: string[],\n\tprimaryCwd: string,\n\tfallbackCwd?: string,\n\tlocalSkillPaths?: string[],\n\tlocalBaseDir?: string,\n): { resolved: ResolvedSkill[]; missing: string[] } {\n\tconst primary = resolveSkills(skillNames, primaryCwd, localSkillPaths, localBaseDir);\n\tif (!fallbackCwd || primary.missing.length === 0) return primary;\n\tif (path.resolve(primaryCwd) === path.resolve(fallbackCwd)) return primary;\n\n\tconst fallback = resolveSkills(primary.missing, fallbackCwd);\n\treturn {\n\t\tresolved: [...primary.resolved, ...fallback.resolved],\n\t\tmissing: fallback.missing,\n\t};\n}\n\nexport function buildSkillInjection(skills: ResolvedSkill[]): string {\n\tif (skills.length === 0) return \"\";\n\n\tconst lines = [\n\t\t\"The following configured skills are available to this subagent.\",\n\t\t\"Use the read tool to load a skill's file when the task matches its description.\",\n\t\t\"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.\",\n\t\t\"\",\n\t\t\"<available_skills>\",\n\t];\n\tfor (const skill of skills) {\n\t\tlines.push(\"  <skill>\");\n\t\tlines.push(`    <name>${escapeXmlText(skill.name)}</name>`);\n\t\tlines.push(`    <description>${escapeXmlText(skill.description ?? \"\")}</description>`);\n\t\tlines.push(`    <location>${escapeXmlText(skill.path)}</location>`);\n\t\tlines.push(\"  </skill>\");\n\t}\n\tlines.push(\"</available_skills>\");\n\treturn lines.join(\"\\n\");\n}\n\nfunction escapeXmlText(value: string): string {\n\treturn value\n\t\t.replace(/&/g, \"&amp;\")\n\t\t.replace(/</g, \"&lt;\")\n\t\t.replace(/>/g, \"&gt;\");\n}\n\nexport function normalizeSkillInput(\n\tinput: string | string[] | boolean | undefined,\n): string[] | false | undefined {\n\tif (input === false) return false;\n\tif (input === true || input === undefined) return undefined;\n\tif (Array.isArray(input)) {\n\t\treturn [...new Set(input.map((s) => s.trim()).filter((s) => s.length > 0))];\n\t}\n\t// Guard against JSON-encoded arrays arriving as strings (e.g. '[\"a\",\"b\"]').\n\t// Models sometimes serialise the skill parameter as a JSON string instead of\n\t// a native array, and naively splitting on \",\" would embed brackets/quotes\n\t// into the skill names, causing resolution to silently fail.\n\tconst trimmed = input.trim();\n\tif (trimmed.startsWith(\"[\")) {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(trimmed);\n\t\t\tif (Array.isArray(parsed)) {\n\t\t\t\treturn normalizeSkillInput(parsed);\n\t\t\t}\n\t\t} catch {\n\t\t\t// Not valid JSON – fall through to comma-split\n\t\t}\n\t}\n\treturn [...new Set(input.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0))];\n}\n\nexport function discoverAvailableSkills(cwd: string): Array<{\n\tname: string;\n\tsource: SkillSource;\n\tdescription?: string;\n}> {\n\tconst skills = getCachedSkills(cwd);\n\treturn skills\n\t\t.filter((s) => s.name !== SUBAGENT_ORCHESTRATION_SKILL)\n\t\t.map((s) => ({\n\t\t\tname: s.name,\n\t\t\tsource: s.source,\n\t\t\tdescription: s.description,\n\t\t}))\n\t\t.sort((a, b) => a.name.localeCompare(b.name));\n}\n\nexport function clearSkillCache(): void {\n\tskillCache.clear();\n\tloadSkillsCache = null;\n}\n"]}