@sayknow-cli/coding-agent 0.3.8 → 0.3.10

package/src/config/model-profile-activation.ts

@@ -1,4 +1,4 @@
-import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import { ThinkingLevel } from "@sayknow-cli/agent-core";
 import type { Api, Model } from "@sayknow-cli/ai";
 import type { AgentSession } from "../session/agent-session";
 import { formatClampedModelSelector } from "../thinking";
@@ -43,7 +43,10 @@ export interface PrepareModelProfileActivationOptions {
 	settings: Pick<Settings, "get">;
 	profileName: string;
 }
-
+export interface ApplyModelProfileActivationOptions {
+	persistDefault?: boolean;
+	thinkingLevelOverride?: ThinkingLevel;
+}
 export interface PreparedModelProfileActivation {
 	profileName: string;
 	session: ModelProfileActivationSession & { setModelTemporary: AgentSession["setModelTemporary"] };
@@ -351,25 +354,31 @@ export async function prepareModelProfileActivation(
 
 export async function applyPreparedModelProfileActivation(
 	prepared: PreparedModelProfileActivation,
-	options: { persistDefault?: boolean } = {},
+	options: ApplyModelProfileActivationOptions = {},
 ): Promise<void> {
 	const previousModel = prepared.previousModel;
 	const previousThinkingLevel = prepared.previousThinkingLevel;
 	const previousAgentModelOverrides = prepared.previousAgentModelOverrides;
 	const previousModelRoles = prepared.previousModelRoles;
 	const previousPersistedDefault = prepared.settings.get("modelProfile.default");
+	const previousDefaultThinkingLevel = prepared.settings.get("defaultThinkingLevel");
 	const previousActiveModelProfile = prepared.previousActiveModelProfile;
 	const previousSessionDefaultModel = prepared.previousSessionDefaultModel;
 	let modelChanged = false;
 	let overridesChanged = false;
 	let defaultChanged = false;
 	let modelRolesChanged = false;
+	let defaultThinkingChanged = false;
 
 	try {
 		if (prepared.defaultModel) {
-			await prepared.session.setModelTemporary(prepared.defaultModel, prepared.defaultThinkingLevel, {
-				persistAsSessionDefault: true,
-			});
+			await prepared.session.setModelTemporary(
+				prepared.defaultModel,
+				options.thinkingLevelOverride ?? prepared.defaultThinkingLevel,
+				{
+					persistAsSessionDefault: true,
+				},
+			);
 			modelChanged = true;
 		}
 		if (Object.keys(prepared.modelRoles).length > 0) {
@@ -386,6 +395,10 @@ export async function applyPreparedModelProfileActivation(
 		if (options.persistDefault) {
 			prepared.settings.set("modelRoles", {});
 			prepared.settings.set("task.agentModelOverrides", {});
+			if (prepared.defaultThinkingLevel !== undefined && prepared.defaultThinkingLevel !== ThinkingLevel.Inherit) {
+				prepared.settings.set("defaultThinkingLevel", prepared.defaultThinkingLevel);
+				defaultThinkingChanged = true;
+			}
 			prepared.settings.set("modelProfile.default", prepared.profileName);
 			defaultChanged = true;
 			await prepared.settings.flush();
@@ -396,6 +409,9 @@ export async function applyPreparedModelProfileActivation(
 			prepared.settings.set("modelProfile.default", previousPersistedDefault);
 			prepared.settings.set("modelRoles", previousModelRoles);
 			prepared.settings.set("task.agentModelOverrides", previousAgentModelOverrides);
+			if (defaultThinkingChanged) {
+				prepared.settings.set("defaultThinkingLevel", previousDefaultThinkingLevel);
+			}
 		}
 		if (modelRolesChanged) {
 			prepared.settings.override("modelRoles", previousModelRoles);
@@ -430,7 +446,7 @@ export async function applyPreparedModelProfileActivation(
 
 export async function activateModelProfile(
 	options: PrepareModelProfileActivationOptions,
-	applyOptions: { persistDefault?: boolean } = {},
+	applyOptions: ApplyModelProfileActivationOptions = {},
 ): Promise<void> {
 	const prepared = await prepareModelProfileActivation(options);
 	await applyPreparedModelProfileActivation(prepared, applyOptions);

package/src/config/model-registry.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import {
 	type Api,
 	type AssistantMessageEventStream,
+	type AuthCredentialSelector,
 	type CacheRetention,
 	type Context,
 	createModelManager,
@@ -83,7 +84,8 @@ export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
 };
 
 export const MODEL_ROLE_IDS: ModelRole[] = ["default"];
-
+export const MODEL_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+export const MODEL_PROFILE_NAME_PATTERN_DESCRIPTION = "lowercase letters, numbers, dots, underscores, or hyphens";
 export type SkcModelAssignmentTargetId = "default" | "executor" | "architect" | "planner" | "critic";
 
 export interface SkcModelAssignmentTargetInfo extends ModelRoleInfo {
@@ -922,10 +924,13 @@ function resolveCustomModelReference(modelId: string): Model<Api> | undefined {
 }
 
 function applyStandaloneCustomModelPolicies(model: CustomModelOverlay): CustomModelOverlay {
-	if (model.id !== "gpt-5.4" || model.provider === "github-copilot" || model.contextWindow !== undefined) {
+	if (model.contextWindow !== undefined) {
 		return model;
 	}
-	return { ...model, contextWindow: 1_000_000 };
+	if (model.id === "gpt-5.4" && model.provider !== "github-copilot") {
+		return { ...model, contextWindow: 1_000_000 };
+	}
+	return model;
 }
 
 function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuildOptions): Model<Api> {
@@ -1590,10 +1595,7 @@ export class ModelRegistry {
 			const where = first?.path.length ? `/${first.path.map(String).join("/")}` : "root";
 			throw new Error(`Generated models config is invalid at ${where}: ${first?.message ?? "unknown schema error"}`);
 		}
-		await fs.mkdir(path.dirname(this.#modelsConfigFile.path()), { recursive: true });
-		await Bun.write(this.#modelsConfigFile.path(), Bun.YAML.stringify(checkedConfig.data, null, 2));
-		this.#modelsConfigFile.invalidate();
-		this.#reloadStaticModels();
+		await this.#writeCheckedModelsConfig(checkedConfig.data);
 		const modelMapping = { ...definition.model_mapping };
 		const profile: ModelProfileDefinition = {
 			name: normalizedName,
@@ -1604,6 +1606,84 @@ export class ModelRegistry {
 		};
 		return profile;
 	}
+
+	async renameCustomModelProfile(name: string, displayName: string): Promise<ModelProfileDefinition> {
+		const normalizedName = name.trim();
+		const nextDisplayName = displayName.trim();
+		if (!normalizedName) throw new Error("Profile name is required.");
+		if (!nextDisplayName) throw new Error("Profile display name is required.");
+		const { current, profile } = this.#loadCustomProfileForMutation(normalizedName, "rename");
+		const nextProfiles = {
+			...(current.profiles ?? {}),
+			[normalizedName]: {
+				...profile,
+				display_name: nextDisplayName,
+			},
+		};
+		const checkedConfig = ModelsConfigSchema.safeParse({ ...current, profiles: nextProfiles });
+		if (!checkedConfig.success) {
+			const first = checkedConfig.error.issues[0];
+			const where = first?.path.length ? `/${first.path.map(String).join("/")}` : "root";
+			throw new Error(`Generated models config is invalid at ${where}: ${first?.message ?? "unknown schema error"}`);
+		}
+		await this.#writeCheckedModelsConfig(checkedConfig.data);
+		const modelMapping = { ...profile.model_mapping };
+		return {
+			name: normalizedName,
+			displayName: nextDisplayName,
+			requiredProviders: aggregateModelProfileRequiredProviders(profile.required_providers, { modelMapping }),
+			modelMapping,
+			source: "user",
+		};
+	}
+
+	async deleteCustomModelProfile(name: string): Promise<ModelProfileConfig> {
+		const normalizedName = name.trim();
+		if (!normalizedName) throw new Error("Profile name is required.");
+		const { current, profile } = this.#loadCustomProfileForMutation(normalizedName, "delete");
+		const nextProfiles = { ...(current.profiles ?? {}) };
+		delete nextProfiles[normalizedName];
+		const checkedConfig = ModelsConfigSchema.safeParse({
+			...current,
+			profiles: Object.keys(nextProfiles).length > 0 ? nextProfiles : undefined,
+		});
+		if (!checkedConfig.success) {
+			const first = checkedConfig.error.issues[0];
+			const where = first?.path.length ? `/${first.path.map(String).join("/")}` : "root";
+			throw new Error(`Generated models config is invalid at ${where}: ${first?.message ?? "unknown schema error"}`);
+		}
+		await this.#writeCheckedModelsConfig(checkedConfig.data);
+		return profile;
+	}
+
+	#loadCustomProfileForMutation(
+		normalizedName: string,
+		action: "rename" | "delete",
+	): { current: ModelsConfig; profile: ModelProfileConfig } {
+		const loaded = this.#modelsConfigFile.tryLoad();
+		if (loaded.status === "error") {
+			throw new Error(
+				`Cannot ${action} custom model profile because ${this.#modelsConfigFile.path()} is invalid. Fix the existing config before modifying presets.`,
+			);
+		}
+		const current = loaded.value ?? this.#modelsConfigFile.createDefault();
+		const profile = current.profiles?.[normalizedName];
+		if (!profile) {
+			const existing = this.#modelProfiles.get(normalizedName);
+			if (existing && existing.source !== "user") {
+				throw new Error(`Cannot ${action} bundled model profile: ${normalizedName}.`);
+			}
+			throw new Error(`Custom model profile does not exist: ${normalizedName}.`);
+		}
+		return { current, profile };
+	}
+
+	async #writeCheckedModelsConfig(config: ModelsConfig): Promise<void> {
+		await fs.mkdir(path.dirname(this.#modelsConfigFile.path()), { recursive: true });
+		await Bun.write(this.#modelsConfigFile.path(), Bun.YAML.stringify(config, null, 2));
+		this.#modelsConfigFile.invalidate();
+		this.#reloadStaticModels();
+	}
 	applyConfiguredModelBindings(targetSettings: Settings): void {
 		this.#modelBindingsTargetSettings = targetSettings;
 		this.#applyConfiguredModelBindingsToTarget();
@@ -2579,21 +2659,37 @@ export class ModelRegistry {
 	/**
 	 * Get API key for a model.
 	 */
-	async getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined> {
+	async getApiKey(
+		model: Model<Api>,
+		sessionId?: string,
+		options: { credentialSelector?: AuthCredentialSelector } = {},
+	): Promise<string | undefined> {
 		if (this.#keylessProviders.has(model.provider) && !this.authStorage.hasAuth(model.provider)) {
 			return kNoAuth;
 		}
-		return this.authStorage.getApiKey(model.provider, sessionId, { baseUrl: model.baseUrl, modelId: model.id });
+		return this.authStorage.getApiKey(model.provider, sessionId, {
+			baseUrl: model.baseUrl,
+			modelId: model.id,
+			credentialSelector: options.credentialSelector,
+		});
 	}
 
 	/**
 	 * Get API key for a provider (e.g., "openai").
 	 */
-	async getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined> {
+	async getApiKeyForProvider(
+		provider: string,
+		sessionId?: string,
+		baseUrl?: string,
+		options: { credentialSelector?: AuthCredentialSelector } = {},
+	): Promise<string | undefined> {
 		if (this.#keylessProviders.has(provider) && !this.authStorage.hasAuth(provider)) {
 			return kNoAuth;
 		}
-		return this.authStorage.getApiKey(provider, sessionId, { baseUrl });
+		return this.authStorage.getApiKey(provider, sessionId, {
+			baseUrl,
+			credentialSelector: options.credentialSelector,
+		});
 	}
 
 	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {

package/src/config/model-resolver.ts

@@ -3,15 +3,7 @@
  */
 
 import { ThinkingLevel } from "@sayknow-cli/agent-core";
-import {
-	type Api,
-	clampThinkingLevelForModel,
-	DEFAULT_MODEL_PER_PROVIDER,
-	type Effort,
-	type KnownProvider,
-	type Model,
-	modelsAreEqual,
-} from "@sayknow-cli/ai";
+import { type Api, DEFAULT_MODEL_PER_PROVIDER, type KnownProvider, type Model, modelsAreEqual } from "@sayknow-cli/ai";
 import { fuzzyMatch } from "@sayknow-cli/tui";
 import { logger } from "@sayknow-cli/utils";
 import chalk from "chalk";
@@ -1197,7 +1189,7 @@ export async function findInitialModel(options: {
 	isContinuing: boolean;
 	defaultProvider?: string;
 	defaultModelId?: string;
-	defaultThinkingSelector?: Effort;
+	defaultThinkingSelector?: ThinkingLevel;
 	modelRegistry: InitialModelRegistry;
 }): Promise<InitialModelResult> {
 	const {
@@ -1212,7 +1204,7 @@ export async function findInitialModel(options: {
 	} = options;
 
 	let model: Model<Api> | undefined;
-	let thinkingLevel: Effort | undefined;
+	let thinkingLevel: ThinkingLevel | undefined;
 
 	// 1. CLI args take priority
 	if (cliProvider && cliModel) {
@@ -1233,10 +1225,7 @@ export async function findInitialModel(options: {
 				: (scoped.thinkingLevel ?? defaultThinkingSelector);
 		return {
 			model: scoped.model,
-			thinkingLevel:
-				scopedThinkingSelector === ThinkingLevel.Off
-					? ThinkingLevel.Off
-					: clampThinkingLevelForModel(scoped.model, scopedThinkingSelector),
+			thinkingLevel: resolveThinkingLevelForModel(scoped.model, scopedThinkingSelector),
 			fallbackMessage: undefined,
 		};
 	}
@@ -1246,7 +1235,7 @@ export async function findInitialModel(options: {
 		const found = modelRegistry.find(defaultProvider, defaultModelId);
 		if (found) {
 			model = found;
-			thinkingLevel = clampThinkingLevelForModel(found, defaultThinkingSelector);
+			thinkingLevel = resolveThinkingLevelForModel(found, defaultThinkingSelector);
 			return { model, thinkingLevel, fallbackMessage: undefined };
 		}
 	}

package/src/config/settings-schema.ts

@@ -5,6 +5,7 @@ import { EDIT_MODES } from "../utils/edit-mode";
 import { CONFIGURABLE_SEARCH_PROVIDER_IDS } from "../web/search/types";
 
 const THINKING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as readonly Effort[];
+const DEFAULT_THINKING_LEVELS = ["off", ...THINKING_EFFORTS] as const;
 
 import {
 	DEFAULT_DISABLED_EXTENSIONS,
@@ -262,6 +263,8 @@ export const SETTINGS_SCHEMA = {
 	"notifications.enabled": { type: "boolean", default: false },
 	"notifications.telegram.botToken": { type: "string", default: undefined },
 	"notifications.telegram.chatId": { type: "string", default: undefined },
+	"notifications.telegram.rich.enabled": { type: "boolean", default: true },
+	"notifications.telegram.richDraft.enabled": { type: "boolean", default: false },
 	"notifications.discord.botToken": { type: "string", default: undefined },
 	"notifications.discord.channelId": { type: "string", default: undefined },
 	"notifications.slack.botToken": { type: "string", default: undefined },
@@ -827,13 +830,13 @@ export const SETTINGS_SCHEMA = {
 	// Reasoning and prompts
 	defaultThinkingLevel: {
 		type: "enum",
-		values: THINKING_EFFORTS,
+		values: DEFAULT_THINKING_LEVELS,
 		default: THINKING_EFFORTS[3],
 		ui: {
 			tab: "model",
 			label: "Thinking Level",
 			description: "Reasoning depth for thinking-capable models",
-			options: [...THINKING_EFFORTS.map(getThinkingLevelMetadata)],
+			options: [...DEFAULT_THINKING_LEVELS.map(getThinkingLevelMetadata)],
 		},
 	},
 
@@ -3610,6 +3613,12 @@ export interface NotificationsSettings {
 	telegram: {
 		botToken: string | undefined;
 		chatId: string | undefined;
+		rich: {
+			enabled: boolean;
+		};
+		richDraft: {
+			enabled: boolean;
+		};
 	};
 	discord: {
 		botToken: string | undefined;

package/src/config/settings.ts

@@ -375,6 +375,25 @@ export class Settings {
 		}
 	}
 
+	/**
+	 * Like {@link flush}, but rejects if the durable save fails instead of
+	 * swallowing the error. Use where the caller must confirm persistence before
+	 * reporting success (e.g. the Telegram `/rich` toggle). In-memory instances
+	 * ({@link isolated}) short-circuit in {@link #saveNow} and never throw.
+	 */
+	async flushOrThrow(): Promise<void> {
+		if (this.#saveTimer) {
+			clearTimeout(this.#saveTimer);
+			this.#saveTimer = undefined;
+		}
+		if (this.#savePromise) {
+			await this.#savePromise;
+		}
+		if (this.#modified.size > 0) {
+			await this.#saveNow({ throwOnError: true });
+		}
+	}
+
 	async cloneForCwd(cwd: string): Promise<Settings> {
 		const cloned = new Settings({
 			cwd,
@@ -818,7 +837,7 @@ export class Settings {
 		}, 100);
 	}
 
-	async #saveNow(): Promise<void> {
+	async #saveNow(options: { throwOnError?: boolean } = {}): Promise<void> {
 		if (!this.#persist || !this.#configPath || this.#modified.size === 0) return;
 
 		const configPath = this.#configPath;
@@ -847,6 +866,10 @@ export class Settings {
 			for (const p of modifiedPaths) {
 				this.#modified.add(p);
 			}
+			if (options.throwOnError) {
+				this.#rebuildMerged();
+				throw error;
+			}
 		}
 
 		this.#rebuildMerged();

package/src/extensibility/runtime-skill-discovery.ts

@@ -0,0 +1,229 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { findRepoRoot } from "../capability/fs";
+import type { Skill as CapabilitySkill } from "../capability/skill";
+import type { SkillsSettings } from "../config/settings-schema";
+import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
+import type { Skill } from "./skills";
+
+export type RuntimeSkillDiscoverySource = "project" | "user";
+
+export interface RuntimeSkillDiscoveryCandidate {
+	name: string;
+	description: string;
+	source: RuntimeSkillDiscoverySource;
+	path: string;
+	useWhen?: string[];
+}
+
+export interface DiscoverRuntimeSkillsOptions {
+	cwd: string;
+	home?: string;
+	query?: string;
+	limit?: number;
+	source?: RuntimeSkillDiscoverySource | "all";
+	policy?: SkillsSettings;
+}
+
+function getRuntimeHome(): string {
+	return process.env.HOME || os.homedir();
+}
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+
+function normalizeLimit(limit: number | undefined): number {
+	if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_LIMIT;
+	return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(limit)));
+}
+
+async function getProjectSkillDirs(cwd: string, home: string): Promise<{ dirs: string[]; repoRoot: string | null }> {
+	const dirs: string[] = [];
+	let current = path.resolve(cwd);
+	const resolvedHome = path.resolve(home);
+	const repoRoot = await findRepoRoot(current);
+	const stop = path.resolve(repoRoot ?? current);
+	while (true) {
+		if (current !== resolvedHome) {
+			dirs.push(path.join(current, ".skc", "skills"));
+		}
+		if (current === stop) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return { dirs, repoRoot };
+}
+
+function getUseWhen(skill: CapabilitySkill): string[] | undefined {
+	const frontmatter = skill.frontmatter as Record<string, unknown> | undefined;
+	const values: string[] = [];
+	const globs = frontmatter?.globs;
+	if (Array.isArray(globs)) {
+		values.push(...globs.filter((value): value is string => typeof value === "string"));
+	} else if (typeof globs === "string") {
+		values.push(globs);
+	}
+	for (const key of ["use_when", "useWhen", "conditions"]) {
+		const raw = frontmatter?.[key];
+		if (typeof raw === "string") values.push(raw);
+		if (Array.isArray(raw)) values.push(...raw.filter((value): value is string => typeof value === "string"));
+	}
+	return values.length > 0 ? values : undefined;
+}
+
+function toRuntimeSkill(skill: CapabilitySkill, source: RuntimeSkillDiscoverySource): Skill {
+	return {
+		name: skill.name,
+		description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
+		filePath: skill.path,
+		baseDir: skill.path.replace(/[\\/]SKILL\.md$/, ""),
+		source: `runtime:${source}`,
+		hide: skill.frontmatter?.hide === true,
+		_source: { ...skill._source, providerName: "Runtime skill discovery" },
+	};
+}
+function sourceEnabled(source: RuntimeSkillDiscoverySource, policy: SkillsSettings | undefined): boolean {
+	if (policy?.enabled !== true) return false;
+	if (source === "project") return policy.enablePiProject === true;
+	if (source === "user") return policy.enablePiUser === true;
+	return false;
+}
+
+function matchesIncludePatterns(name: string, includeSkills: string[] | undefined): boolean {
+	if (!includeSkills || includeSkills.length === 0) return true;
+	return includeSkills.some(pattern => new Bun.Glob(pattern).match(name));
+}
+
+function matchesIgnorePatterns(name: string, ignoredSkills: string[] | undefined): boolean {
+	if (!ignoredSkills || ignoredSkills.length === 0) return false;
+	return ignoredSkills.some(pattern => new Bun.Glob(pattern).match(name));
+}
+
+function isDisabledSkill(name: string, disabledExtensions: string[] | undefined): boolean {
+	return (disabledExtensions ?? []).some(id => id === `skill:${name}`);
+}
+
+function isAllowedByPolicy(
+	skill: CapabilitySkill,
+	source: RuntimeSkillDiscoverySource,
+	policy: SkillsSettings | undefined,
+): boolean {
+	if (!sourceEnabled(source, policy)) return false;
+	if (isDisabledSkill(skill.name, policy?.disabledExtensions)) return false;
+	if (matchesIgnorePatterns(skill.name, policy?.ignoredSkills)) return false;
+	if (!matchesIncludePatterns(skill.name, policy?.includeSkills)) return false;
+	return true;
+}
+function matchesQuery(candidate: RuntimeSkillDiscoveryCandidate, query: string): boolean {
+	const normalized = query.trim().toLowerCase();
+	if (!normalized) return true;
+	const haystack = [candidate.name, candidate.description, candidate.source, ...(candidate.useWhen ?? [])]
+		.join("\n")
+		.toLowerCase();
+	return normalized
+		.split(/\s+/)
+		.filter(Boolean)
+		.every(term => haystack.includes(term));
+}
+
+async function realPathOrSelf(filePath: string): Promise<string> {
+	try {
+		return await fs.realpath(filePath);
+	} catch {
+		return filePath;
+	}
+}
+
+export async function discoverRuntimeSkills(
+	options: DiscoverRuntimeSkillsOptions,
+): Promise<RuntimeSkillDiscoveryCandidate[]> {
+	const home = options.home ?? getRuntimeHome();
+	const source = options.source ?? "all";
+	const policy = options.policy;
+	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
+	const projectSkills = await getProjectSkillDirs(options.cwd, home);
+	const projectContext = { cwd: options.cwd, home, repoRoot: projectSkills.repoRoot };
+	if ((source === "all" || source === "project") && sourceEnabled("project", policy)) {
+		for (const dir of projectSkills.dirs) {
+			scanJobs.push(
+				scanSkillsFromDir(projectContext, {
+					dir,
+					providerId: "runtime",
+					level: "project",
+					requireDescription: true,
+				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
+			);
+		}
+	}
+	if ((source === "all" || source === "user") && sourceEnabled("user", policy)) {
+		scanJobs.push(
+			scanSkillsFromDir(
+				{ cwd: options.cwd, home, repoRoot: home },
+				{ dir: path.join(home, ".skc", "skills"), providerId: "runtime", level: "user", requireDescription: true },
+			).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
+		);
+	}
+
+	const seenNames = new Set<string>();
+	const seenPaths = new Set<string>();
+	const candidates: RuntimeSkillDiscoveryCandidate[] = [];
+	for (const entry of (await Promise.all(scanJobs)).flat()) {
+		if (!isAllowedByPolicy(entry.skill, entry.source, policy)) continue;
+		const realPath = await realPathOrSelf(entry.skill.path);
+		if (seenPaths.has(realPath) || seenNames.has(entry.skill.name)) continue;
+		seenPaths.add(realPath);
+		seenNames.add(entry.skill.name);
+		const candidate: RuntimeSkillDiscoveryCandidate = {
+			name: entry.skill.name,
+			description:
+				typeof entry.skill.frontmatter?.description === "string" ? entry.skill.frontmatter.description : "",
+			source: entry.source,
+			path: entry.skill.path,
+			useWhen: getUseWhen(entry.skill),
+		};
+		if (matchesQuery(candidate, options.query ?? "")) candidates.push(candidate);
+	}
+	candidates.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
+	return candidates.slice(0, normalizeLimit(options.limit));
+}
+
+export async function findRuntimeSkillByName(
+	cwd: string,
+	name: string,
+	policy?: SkillsSettings,
+	home = getRuntimeHome(),
+): Promise<Skill | undefined> {
+	const normalized = name.trim();
+	if (!normalized) return undefined;
+	const scanJobs: Array<Promise<{ skill: CapabilitySkill; source: RuntimeSkillDiscoverySource }[]>> = [];
+	const projectSkills = await getProjectSkillDirs(cwd, home);
+	const projectContext = { cwd, home, repoRoot: projectSkills.repoRoot };
+	if (sourceEnabled("project", policy)) {
+		scanJobs.push(
+			...projectSkills.dirs.map(dir =>
+				scanSkillsFromDir(projectContext, {
+					dir,
+					providerId: "runtime",
+					level: "project",
+					requireDescription: true,
+				}).then(result => result.items.map(skill => ({ skill, source: "project" as const }))),
+			),
+		);
+	}
+	if (sourceEnabled("user", policy)) {
+		scanJobs.push(
+			scanSkillsFromDir(
+				{ cwd, home, repoRoot: home },
+				{ dir: path.join(home, ".skc", "skills"), providerId: "runtime", level: "user", requireDescription: true },
+			).then(result => result.items.map(skill => ({ skill, source: "user" as const }))),
+		);
+	}
+	for (const entry of (await Promise.all(scanJobs)).flat()) {
+		if (entry.skill.name === normalized && isAllowedByPolicy(entry.skill, entry.source, policy)) {
+			return toRuntimeSkill(entry.skill, entry.source);
+		}
+	}
+	return undefined;
+}