zidane 6.4.3 → 6.5.0

package/dist/{resolve-CZJxds85.js → skills-Cp9vnBwd.js}

@@ -1,6 +1,6 @@
 import { o as AgentToolNotAllowedError, u as errorMessage } from "./errors-BwBxu3zD.js";
 import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
@@ -326,90 +326,105 @@ function isToolAllowedByUnion(displayName, input, union) {
 	return union.some((pattern) => matchesAllowedTool(displayName, input, pattern));
 }
 //#endregion
-//#region src/skills/interpolate.ts
-/** Regex to match !`command` patterns in skill instructions */
-const SHELL_INTERPOLATION_RE = /!`([^`]+)`/g;
-/**
-* Replace every !\`command\` pattern with a static placeholder, without
-* executing anything. Used when shell interpolation is disabled
-* (`SkillsConfig.allowShellInterpolation: false`): skill content can be
-* third-party input, and running its embedded commands on activation
-* bypasses the allowed-tools gate.
-*/
-function stripShellInterpolations(instructions) {
-	return instructions.replace(SHELL_INTERPOLATION_RE, "[shell interpolation disabled]");
+//#region src/skills/activation.ts
+function createSkillActivationState(options = {}) {
+	const byName = /* @__PURE__ */ new Map();
+	const maxActive = typeof options.maxActive === "number" && options.maxActive > 0 ? options.maxActive : void 0;
+	return {
+		active() {
+			return [...byName.values()];
+		},
+		isActive(name) {
+			return byName.has(name);
+		},
+		get(name) {
+			return byName.get(name);
+		},
+		activate(skill, via) {
+			if (byName.has(skill.name)) return "already-active";
+			if (maxActive !== void 0 && byName.size >= maxActive) return "cap-reached";
+			byName.set(skill.name, {
+				skill,
+				activatedAt: Date.now(),
+				activatedVia: via
+			});
+			return "ok";
+		},
+		deactivate(name) {
+			const existing = byName.get(name);
+			if (!existing) return void 0;
+			byName.delete(name);
+			return existing;
+		},
+		clear() {
+			const snapshot = [...byName.values()];
+			byName.clear();
+			return snapshot;
+		}
+	};
 }
+//#endregion
+//#region src/skills/allowed-tools.ts
+/** Tools that are always allowed regardless of the active skills' allow-list. */
+const IMPLICITLY_ALLOWED_SKILL_TOOLS = [
+	"skills_use",
+	"skills_read",
+	"skills_run_script"
+];
 /**
-* Interpolate shell commands in skill instructions.
+* Register `tool:gate` / `mcp:tool:gate` handlers that enforce the union of
+* `allowedTools` across active skills.
 *
-* Runs each !\`command\` through the execution context and replaces
-* the placeholder with the command's stdout. If a command fails,
-* the placeholder is replaced with an error message (and
-* `options.onFailure` is notified when provided).
+* No-op when no active skill declares an allow-list (permissive default —
+* matches the spec's "experimental" note for `allowed-tools`).
 *
-* @param instructions - Raw skill instructions with potential !\`command\` patterns
-* @param execution - The execution context to run commands in
-* @param handle - The active execution handle
-* @returns Instructions with all !\`command\` patterns replaced by output
+* Returns an `uninstall` fn. The agent calls this at run end to detach the
+* handlers and prevent cross-run hook leaks.
 */
-async function interpolateShellCommands(instructions, execution, handle, options = {}) {
-	const matches = [...instructions.matchAll(SHELL_INTERPOLATION_RE)];
-	if (matches.length === 0) return instructions;
-	const replacements = [];
-	for (const match of matches) {
-		const command = match[1];
-		const index = match.index;
-		const length = match[0].length;
-		if (options.approve) {
-			let approved = false;
-			try {
-				approved = await options.approve(command);
-			} catch {
-				approved = false;
-			}
-			if (!approved) {
-				const placeholder = "[shell interpolation not approved]";
-				options.onFailure?.(command, placeholder);
-				replacements.push({
-					index,
-					length,
-					output: placeholder
-				});
-				continue;
-			}
-		}
-		try {
-			const result = await execution.exec(handle, command, { timeout: 30 });
-			if (result.exitCode === 0) replacements.push({
-				index,
-				length,
-				output: result.stdout.trim()
-			});
-			else {
-				const placeholder = `[command failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}]`;
-				options.onFailure?.(command, placeholder);
-				replacements.push({
-					index,
-					length,
-					output: placeholder
-				});
-			}
-		} catch (err) {
-			const placeholder = `[command error: ${errorMessage(err)}]`;
-			options.onFailure?.(command, placeholder);
-			replacements.push({
-				index,
-				length,
-				output: placeholder
-			});
-		}
+function installAllowedToolsGate(hooks, state) {
+	function effectiveUnion() {
+		const active = state.active();
+		const declared = [];
+		for (const record of active) if (record.skill.allowedTools?.length) declared.push(...record.skill.allowedTools);
+		return {
+			union: declared.length > 0 ? [...declared, ...IMPLICITLY_ALLOWED_SKILL_TOOLS] : [],
+			active: active.map((a) => a.skill.name)
+		};
 	}
-	let result = instructions;
-	for (let i = replacements.length - 1; i >= 0; i--) {
-		const { index, length, output } = replacements[i];
-		result = result.slice(0, index) + output + result.slice(index + length);
+	function gateHandler(ctx) {
+		if (ctx.block) return;
+		const { union, active } = effectiveUnion();
+		if (union.length === 0) return;
+		if (isToolAllowedByUnion(ctx.displayName, ctx.input, union)) return;
+		const err = new AgentToolNotAllowedError({
+			toolName: ctx.name,
+			displayName: ctx.displayName,
+			allowedUnion: union,
+			activeSkills: active
+		});
+		ctx.block = true;
+		ctx.reason = err.message;
 	}
-	return result;
+	function mcpGateHandler(ctx) {
+		if (ctx.block) return;
+		const { union, active } = effectiveUnion();
+		if (union.length === 0) return;
+		if (isToolAllowedByUnion(ctx.displayName, ctx.input, union)) return;
+		const err = new AgentToolNotAllowedError({
+			toolName: `mcp_${ctx.server}_${ctx.tool}`,
+			displayName: ctx.displayName,
+			allowedUnion: union,
+			activeSkills: active
+		});
+		ctx.block = true;
+		ctx.reason = err.message;
+	}
+	const unregisterTool = hooks.hook("tool:gate", gateHandler);
+	const unregisterMcp = hooks.hook("mcp:tool:gate", mcpGateHandler);
+	return function uninstall() {
+		unregisterTool();
+		unregisterMcp();
+	};
 }
 //#endregion
 //#region src/xml.ts
@@ -431,1028 +446,1405 @@ function escapeXml(str) {
 	return str.replace(RE_AMP, "&").replace(RE_LT, "<").replace(RE_GT, ">").replace(RE_QUOT, """);
 }
 //#endregion
-//#region src/install/source.ts
+//#region src/skills/catalog.ts
 /**
-* Shared install-source layer — the source-agnostic half of "install a
-* thing from github/npm". Extracted from the extensions installer so
-* SKILL installs (and any future installable artifact) reuse the exact
-* same spec grammar, fetch pipeline, and hardening instead of forking
-* them:
-*
-*   - Spec grammar: `owner/repo[#ref][:subdir]`, `github:owner/repo`,
-*     pasted GitHub URLs (including `/tree/<ref>/<path>`),
-*     `pkg[@version]`, `@scope/pkg[@version]`.
-*   - Fetch: `git clone --depth 1` (records the exact commit) with a
-*     codeload-tarball fallback, npm registry resolve (exact versions +
-*     dist-tags) + tarball download. Downloads are double-capped at
-*     {@link MAX_DOWNLOAD_BYTES} (content-length header AND post-hoc for
-*     chunked responses). Extraction requires `tar` on PATH.
-*   - All side effects go through the injectable {@link InstallIo} seams
-*     so tests stay offline and hosts can instrument.
-*
-* Flavor-specific concerns stay OUT of this module: candidate
-* enumeration, validation, target roots, provenance files, dependency
-* installs. Flavors subclass {@link InstallSourceError} to widen the
-* error-code union while keeping `.code`-based handling uniform.
+* Build the skill catalog XML and behavioral instructions for the system prompt.
 */
+function buildCatalog(skills, options = {}) {
+	if (skills.length === 0) return "";
+	const skillsToolRegistered = options.skillsToolRegistered ?? true;
+	const readToolName = options.readToolName ?? "read_file";
+	const entries = skills.map((skill) => {
+		const locationLine = skill.location ? `\n    <location>${escapeXml(skill.location)}</location>` : "";
+		return `  <skill>
+    <name>${escapeXml(skill.name)}</name>
+    <description>${escapeXml(skill.description)}</description>${locationLine}
+  </skill>`;
+	}).join("\n");
+	const hasFsSkills = skills.some((s) => s.location);
+	const hasInlineSkills = skills.some((s) => !s.location);
+	const behavioralParts = [];
+	behavioralParts.push("The following skills provide specialized instructions for specific tasks.", "When a task matches a skill's description, activate the skill to load its full instructions before proceeding.");
+	if (skillsToolRegistered) behavioralParts.push("To activate a skill, call the `skills_use` tool with the skill's name. The response contains the full instructions and any bundled resources you can then load via `skills_read` (reference files) or execute via `skills_run_script` (scripts/ directory).", "Relative paths referenced in a skill's instructions resolve against the skill directory noted in the `skills_use` response.");
+	else if (hasFsSkills) behavioralParts.push(`For skills with a <location>, use the ${readToolName} tool to read the SKILL.md file at that path.`, "When a skill references relative paths, resolve them against the skill's directory (the parent of SKILL.md) and use absolute paths in tool calls.");
+	if (hasInlineSkills && !skillsToolRegistered) behavioralParts.push("Skills without a <location> have their instructions included directly in <instructions> tags below.");
+	const parts = [
+		behavioralParts.join("\n"),
+		"",
+		"<available_skills>",
+		entries,
+		"</available_skills>"
+	];
+	if (hasInlineSkills && !skillsToolRegistered) {
+		parts.push("");
+		for (const skill of skills) if (!skill.location && skill.instructions) {
+			parts.push(`<skill_instructions name="${escapeXml(skill.name)}">`);
+			parts.push(skill.instructions);
+			if (skill.resources && skill.resources.length > 0) {
+				parts.push("");
+				parts.push("<skill_resources>");
+				for (const res of skill.resources) parts.push(`  <file type="${res.type}">${escapeXml(res.path)}</file>`);
+				parts.push("</skill_resources>");
+			}
+			parts.push("</skill_instructions>");
+		}
+	}
+	return parts.join("\n");
+}
+//#endregion
+//#region src/skills/discovery.ts
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const INDENT_RE = /^[ \t]{2,}/;
+const KV_RE = /^([^:]+):(.*)$/;
+const DOUBLE_QUOTED_RE = /^"((?:\\.|[^"\\])*)"$/;
+const SINGLE_QUOTED_RE = /^'((?:''|[^'])*)'$/;
+const DQ_ESCAPE_RE = /\\(["\\/bfnrt])/g;
+const WHITESPACE_SPLIT_RE = /\s+/;
+const PARAGRAPH_SPLIT_RE = /\n\n/;
+const COMMA_OR_SPACE_RE = /[,\s]+/;
 /**
-* Base error for install pipelines. `code` is a plain string here so
-* flavors (extensions, skills) can widen it with their own codes while
-* callers keep a single `err.code` switch. The base layer itself only
-* throws `'invalid-source'` and `'fetch-failed'`.
+* Block-list bullet (`- value`) under an indented frontmatter key. A
+* single dash followed by either a space or end-of-line; bare `-` is a
+* list item with an empty value (preserved by callers as `""` because
+* the spec doesn't disallow it).
 */
-var InstallSourceError = class extends Error {
-	code;
-	/** Set for candidate-selection errors — the names the caller can pick from. */
-	candidates;
-	constructor(code, message, candidates) {
-		super(message);
-		this.name = "InstallSourceError";
-		this.code = code;
-		if (candidates) this.candidates = candidates;
-	}
-};
-const GITHUB_TREE_URL_RE = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#@:]+?)(?:\.git)?\/tree\/([^/\s:]+)(?:\/([^\s:]+?))?\/?$/;
-const GITHUB_URL_RE = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#@:]+?)(?:\.git)?\/?$/;
-const OWNER_REPO_RE = /^([\w.-]+)\/([\w.-]+)$/;
-const GITHUB_REF_RE = /^[\w./-]+$/;
-const NPM_NAME_RE = /^(@[\w.-]+\/[\w.-]+|[\w.-]+)(?:@([\w.^~><=*-]+))?$/;
-/** Structural validation for a `:subdir` suffix — repo-relative, no escapes. */
-function parseSubdir(rawSubdir, raw) {
-	const subdir = rawSubdir.replace(/^\.\//, "").replace(/\/+$/, "");
-	const segments = subdir.split("/");
-	if (subdir.length === 0 || subdir.startsWith("/") || subdir.includes("\\") || segments.some((s) => s.length === 0 || s === "." || s === "..")) throw new InstallSourceError("invalid-source", `"${raw}" has an invalid subdirectory — expected a repo-relative path (no leading /, no ..).`);
-	return subdir;
-}
+const LIST_ITEM_RE = /^-(?:\s+|$)/;
 /**
-* Classify a raw source string:
+* Flow-style list scalar (`[a, b, c]`). Anchored, non-nested, single
+* pass — we trim the outer brackets and let the caller split on
+* commas. Anything more complex (nested brackets, quoted commas)
+* falls through to the whitespace-split branch, where the bracket
+* characters become visible authoring errors instead of silent garbage.
 *
-*   - `github:owner/repo`, `owner/repo`, GitHub URLs (including
-*     `/tree/<ref>/<path>` links) → GitHub. Optional `#ref` (or the
-*     legacy `@ref`) pins a branch/tag; optional `:path/to/dir` roots the
-*     candidate search in a subdirectory: `owner/repo#branch:packages/x`.
-*   - `@scope/pkg[@version]`, `pkg[@version]` → npm (no subdir support —
-*     flavors expose their own selector for multi-candidate packages).
+* Carefully written without overlapping `\s*` runs so it's not
+* ReDoS-prone: the body class `[^[\]]*` already swallows whitespace,
+* so wrapping it in `\s*…\s*` would let the regex engine
+* non-deterministically split a run of spaces between the body and
+* the boundary quantifiers.
+*/
+const FLOW_LIST_RE = /^\[([^[\]]*)\]$/;
+/**
+* Common kebab/camel/snake misspellings of multi-word spec frontmatter
+* keys. The Agent Skills spec mandates kebab-case (`allowed-tools`), but
+* authors raised on JS / Python idioms naturally reach for camelCase
+* (`allowedTools`) or snake_case (`allowed_tools`) — and the consequences
+* of a silent mismatch on `allowed-tools` specifically are nasty: the
+* skill loads fine, looks active in the UI, the model reads the body
+* and tells the user "tools are restricted", but the `tool:gate`
+* middleware finds nothing in the union and runs permissively. So we
+* look for these alts at parse time, migrate the value to the canonical
+* key, and emit a diagnostic so the next person sees the issue clearly.
 *
-* The one ambiguity — `a/b` — is resolved as GitHub: npm's slash names
-* are always scoped (`@scope/…`), so a bare `owner/repo` can only be a
-* repo. Throws `invalid-source` on anything else.
+* Keep the value space tight — accepting too many shapes erodes the
+* "lenient load, strict authoring" principle. Add entries only for keys
+* that are (a) multi-word (single-word keys have no ambiguity), (b) in
+* active use, and (c) cause silent failures when missing (gate keys,
+* security gates, …).
 */
-function parseInstallSource(raw) {
-	const spec = raw.trim();
-	if (spec.length === 0) throw new InstallSourceError("invalid-source", "Empty source. Expected `owner/repo`, `github:owner/repo`, a GitHub URL, or an npm package name.");
-	const explicitGithub = spec.startsWith("github:");
-	const body = explicitGithub ? spec.slice(7) : spec;
-	const tree = GITHUB_TREE_URL_RE.exec(body);
-	if (tree) return {
-		kind: "github",
-		owner: tree[1],
-		repo: tree[2],
-		ref: tree[3],
-		...tree[4] ? { subdir: parseSubdir(tree[4], raw) } : {}
-	};
-	const url = GITHUB_URL_RE.exec(body);
-	if (url) return {
-		kind: "github",
-		owner: url[1],
-		repo: url[2]
-	};
-	if (body.startsWith("@")) {
-		if (explicitGithub) throw new InstallSourceError("invalid-source", `"${raw}" mixes the github: prefix with an npm scoped name.`);
-		if (body.includes(":")) throw new InstallSourceError("invalid-source", `"${raw}": subdirectories (\`:path\`) are only supported for GitHub sources.`);
-		const m = NPM_NAME_RE.exec(body);
-		if (!m) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid npm package spec.`);
-		return {
-			kind: "npm",
-			pkg: m[1],
-			...m[2] ? { version: m[2] } : {}
-		};
-	}
-	if (body.includes("/")) {
-		const colonIdx = body.indexOf(":");
-		const specPart = colonIdx === -1 ? body : body.slice(0, colonIdx);
-		const subdir = colonIdx === -1 ? void 0 : parseSubdir(body.slice(colonIdx + 1), raw);
-		const hashIdx = specPart.indexOf("#");
-		const refIdx = hashIdx >= 0 ? hashIdx : specPart.indexOf("@");
-		const repoPart = refIdx === -1 ? specPart : specPart.slice(0, refIdx);
-		const ref = refIdx === -1 ? void 0 : specPart.slice(refIdx + 1);
-		const m = OWNER_REPO_RE.exec(repoPart);
-		if (!m || ref !== void 0 && !GITHUB_REF_RE.test(ref)) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid GitHub repo spec (expected owner/repo, optionally #ref and :subdir).`);
-		return {
-			kind: "github",
-			owner: m[1],
-			repo: m[2],
-			...ref ? { ref } : {},
-			...subdir ? { subdir } : {}
-		};
-	}
-	if (explicitGithub) throw new InstallSourceError("invalid-source", `"${raw}" is missing the repo part (expected github:owner/repo).`);
-	if (body.includes(":")) throw new InstallSourceError("invalid-source", `"${raw}": subdirectories (\`:path\`) are only supported for GitHub sources.`);
-	const m = NPM_NAME_RE.exec(body);
-	if (!m) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid npm package spec.`);
-	return {
-		kind: "npm",
-		pkg: m[1],
-		...m[2] ? { version: m[2] } : {}
-	};
-}
+const FRONTMATTER_KEY_ALIASES = /* @__PURE__ */ new Map([["allowed-tools", ["allowedTools", "allowed_tools"]]]);
 /**
-* Materialize the source into `destDir` (created by the caller, assumed
-* empty). Returns the provenance string plus, for git clones, the exact
-* commit SHA (the tarball fallback can't know it — codeload doesn't
-* expose the resolved commit).
+* Mutate `frontmatter` so any well-known alt-spelling of a canonical
+* spec key gets folded into the canonical slot. Idempotent — when the
+* canonical key is already set the function is a no-op even if an
+* alt-spelling is also present (canonical wins; alt is ignored).
+*
+* Pushes a `frontmatter-key-alt-spelling` diagnostic per migration so
+* the SkillConfig's `.diagnostics` carries an actionable hint into any
+* host UI surfacing skill load issues.
 */
-async function fetchInstallSource(source, destDir, io = {}, onProgress) {
-	const exec = io.exec ?? defaultExec;
-	const which = io.which ?? defaultWhich;
-	const fetchImpl = io.fetch ?? fetch;
-	if (source.kind === "github") {
-		const label = `${source.owner}/${source.repo}${source.ref ? `@${source.ref}` : ""}${source.subdir ? `:${source.subdir}` : ""}`;
-		if (which("git")) {
-			onProgress?.(`cloning github.com/${label}…`);
-			const cloneArgs = (url) => {
-				const args = [
-					"clone",
-					"--depth",
-					"1",
-					"--single-branch"
-				];
-				if (source.ref) args.push("--branch", source.ref);
-				args.push(url, destDir);
-				return args;
-			};
-			let res = await exec("git", cloneArgs(`https://github.com/${source.owner}/${source.repo}.git`), { env: { GIT_TERMINAL_PROMPT: "0" } });
-			if (!res.ok && /could not read username|terminal prompts disabled|authentication failed|repository not found/i.test(res.stderr)) {
-				rmSync(destDir, {
-					recursive: true,
-					force: true
-				});
-				mkdirSync(destDir, { recursive: true });
-				onProgress?.(`anonymous clone rejected — retrying via SSH (git@github.com:${source.owner}/${source.repo})…`);
-				const ssh = await exec("git", cloneArgs(`git@github.com:${source.owner}/${source.repo}.git`), { env: {
-					GIT_TERMINAL_PROMPT: "0",
-					GIT_SSH_COMMAND: sshCommandWithBatchMode(process.env.GIT_SSH_COMMAND)
-				} });
-				if (ssh.ok) res = ssh;
-				else throw new InstallSourceError("fetch-failed", `git clone failed for ${label}: ${lastLine(res.stderr)}; SSH retry also failed: ${lastLine(ssh.stderr)} (private repo? check your GitHub SSH keys / repo access, or configure git credentials for HTTPS)`);
-			}
-			if (!res.ok) throw new InstallSourceError("fetch-failed", `git clone failed for ${label}: ${lastLine(res.stderr)}`);
-			const head = await exec("git", ["rev-parse", "HEAD"], { cwd: destDir });
-			const commit = head.ok && /^[0-9a-f]{40}$/.test(head.stdout.trim()) ? head.stdout.trim() : void 0;
-			rmSync(join(destDir, ".git"), {
-				recursive: true,
-				force: true
+function normalizeKeyAliases(frontmatter, diagnostics) {
+	for (const [canonical, aliases] of FRONTMATTER_KEY_ALIASES) {
+		if (frontmatter[canonical] !== void 0) continue;
+		for (const alias of aliases) {
+			if (frontmatter[alias] === void 0) continue;
+			frontmatter[canonical] = frontmatter[alias];
+			diagnostics.push({
+				severity: "warning",
+				code: "frontmatter-key-alt-spelling",
+				message: `Frontmatter field "${alias}" is not a spec key — the spec uses "${canonical}" (kebab-case). Reading the value from "${alias}" as a courtesy; rename it to "${canonical}" to silence this warning.`,
+				field: alias
 			});
-			return {
-				provenance: `github:${label}`,
-				...commit ? { commit } : {}
-			};
+			break;
 		}
-		onProgress?.(`downloading github.com/${label} tarball…`);
-		const ref = source.ref ?? "HEAD";
-		await downloadAndExtract(`https://codeload.github.com/${source.owner}/${source.repo}/tar.gz/${ref}`, destDir, {
-			exec,
-			fetchImpl,
-			which,
-			what: label
-		});
-		return { provenance: `github:${label}` };
 	}
-	onProgress?.(`resolving npm:${source.pkg}…`);
-	const { version, tarball } = await resolveNpmVersion(source, fetchImpl);
-	onProgress?.(`downloading npm:${source.pkg}@${version}…`);
-	await downloadAndExtract(tarball, destDir, {
-		exec,
-		fetchImpl,
-		which,
-		what: `${source.pkg}@${version}`
-	});
-	return { provenance: `npm:${source.pkg}@${version}` };
 }
 /**
-* Registry lookup shared by the fetch path and update no-op checks.
-* Exact versions and dist-tags only — range resolution is out of scope.
+* Parse a SKILL.md file into frontmatter + body.
+*
+* Uses a simple regex-based YAML extractor that handles:
+* - Flat key: value pairs
+* - Quoted values
+* - One-level nested maps (for `metadata:`)
+* - One-level nested block lists, `key:` followed by indented `- item`
+*   lines (for `allowed-tools` and any future array fields). Items are
+*   unquoted with the same rules as scalar values.
+* - Flow-style scalars are preserved verbatim — interpretation (e.g.
+*   `[a, b]` as a list) is left to per-field consumers via
+*   {@link takeStringOrArray}.
+* - Lenient recovery from unquoted-colon values (e.g.
+*   `description: Use when: the user asks …`) via a quote-wrap retry.
 */
-async function resolveNpmVersion(source, fetchImpl) {
-	const registryUrl = `https://registry.npmjs.org/${source.pkg.replace("/", "%2F")}`;
-	let meta;
-	try {
-		const res = await fetchImpl(registryUrl);
-		if (!res.ok) throw new Error(`registry returned ${res.status}`);
-		meta = await res.json();
-	} catch (err) {
-		throw new InstallSourceError("fetch-failed", `Could not resolve npm package "${source.pkg}": ${errorText(err)}`);
-	}
-	const version = source.version && meta.versions?.[source.version] ? source.version : meta["dist-tags"]?.[source.version ?? "latest"];
-	const tarball = version ? meta.versions?.[version]?.dist?.tarball : void 0;
-	if (!version || !tarball) throw new InstallSourceError("fetch-failed", `npm package "${source.pkg}" has no ${source.version ? `version/tag "${source.version}"` : "latest version"} (exact versions and dist-tags only — ranges are not resolved).`);
-	return {
-		version,
-		tarball
+function parseFrontmatter(content) {
+	const diagnostics = [];
+	const match = content.match(FRONTMATTER_RE);
+	if (!match) return {
+		frontmatter: {},
+		body: content.trim(),
+		diagnostics
 	};
+	const yamlBlock = match[1];
+	const body = match[2].trim();
+	const frontmatter = {};
+	let currentKey = null;
+	let currentMap = null;
+	let currentList = null;
+	const flushPending = () => {
+		if (currentKey === null) return;
+		if (currentList !== null) frontmatter[currentKey] = currentList;
+		else if (currentMap !== null) frontmatter[currentKey] = currentMap;
+		currentKey = null;
+		currentMap = null;
+		currentList = null;
+	};
+	for (const line of yamlBlock.split("\n")) {
+		if (!line.trim() || line.trim().startsWith("#")) continue;
+		if (currentKey !== null && INDENT_RE.test(line)) {
+			const stripped = line.trim();
+			if (LIST_ITEM_RE.test(stripped)) {
+				if (currentMap !== null && Object.keys(currentMap).length > 0) {
+					diagnostics.push({
+						severity: "warning",
+						code: "mixed-list-and-map",
+						message: `Frontmatter field "${currentKey}" mixes list items and map entries — keeping the map and dropping the list items.`,
+						field: currentKey
+					});
+					continue;
+				}
+				currentList = currentList ?? [];
+				currentList.push(unquoteYaml(stripped.slice(1).trim()));
+				continue;
+			}
+			const nestedMatch = stripped.match(KV_RE);
+			if (nestedMatch) {
+				if (currentList !== null) {
+					diagnostics.push({
+						severity: "warning",
+						code: "mixed-list-and-map",
+						message: `Frontmatter field "${currentKey}" mixes list items and map entries — keeping the list and dropping the map entries.`,
+						field: currentKey
+					});
+					continue;
+				}
+				currentMap = currentMap ?? {};
+				const val = nestedMatch[2].trim();
+				currentMap[nestedMatch[1].trim()] = unquoteYaml(val);
+			}
+			continue;
+		}
+		flushPending();
+		const kvMatch = matchFirstColon(line);
+		if (!kvMatch) continue;
+		const key = kvMatch.key.trim();
+		const rawValue = kvMatch.value.trim();
+		if (!rawValue) currentKey = key;
+		else frontmatter[key] = unquoteYaml(rawValue);
+	}
+	flushPending();
+	return {
+		frontmatter,
+		body,
+		diagnostics
+	};
+}
+function matchFirstColon(line) {
+	const idx = line.indexOf(":");
+	if (idx < 0) return null;
+	const key = line.slice(0, idx);
+	const value = line.slice(idx + 1);
+	if (!KV_RE.test(`${key}:`)) return null;
+	return {
+		key,
+		value
+	};
+}
+/**
+* Strip outer quotes and decode YAML-style escapes.
+*
+* - Double-quoted values honor `\"`, `\\`, `\n`, `\r`, `\t`, `\b`, `\f`, `\/`.
+* - Single-quoted values honor `''` (the YAML single-quote escape for a literal `'`).
+* - Trailing inline comments on unquoted values (` # comment`) are dropped.
+* - Unquoted values are returned as-is (trimmed by caller).
+*
+* Skill frontmatter in the wild uses a narrow YAML subset — this is
+* sufficient for every field in the current spec and the common authoring
+* tools. Block scalars (`|`, `>`) and flow sequences are intentionally left
+* unsupported: they'd only appear in a bespoke workflow, and silently
+* half-supporting them is worse than rejecting them obviously.
+*/
+function unquoteYaml(val) {
+	const dq = val.match(DOUBLE_QUOTED_RE);
+	if (dq) return dq[1].replace(DQ_ESCAPE_RE, (_, ch) => {
+		switch (ch) {
+			case "\"": return "\"";
+			case "\\": return "\\";
+			case "/": return "/";
+			case "b": return "\b";
+			case "f": return "\f";
+			case "n": return "\n";
+			case "r": return "\r";
+			case "t": return "	";
+			default: return ch;
+		}
+	});
+	const sq = val.match(SINGLE_QUOTED_RE);
+	if (sq) return sq[1].replace(/''/g, "'");
+	const hashIdx = val.indexOf(" #");
+	if (hashIdx >= 0) return val.slice(0, hashIdx).trimEnd();
+	return val;
+}
+/**
+* Narrow a frontmatter field to a string. Produces a diagnostic when present
+* but not a string, so malformed YAML (e.g. `name: 123`) surfaces as a
+* warning instead of silently coerced downstream via `as string`.
+*/
+function takeString(frontmatter, key, diagnostics) {
+	const raw = frontmatter[key];
+	if (raw === void 0 || raw === null) return void 0;
+	if (typeof raw === "string") return raw;
+	diagnostics.push({
+		severity: "warning",
+		code: "invalid-field-type",
+		message: `Frontmatter field "${key}" expected string, got ${Array.isArray(raw) ? "array" : typeof raw}. Skipping.`,
+		field: key
+	});
+}
+/**
+* Accept either a YAML scalar (whitespace-separated tokens, the
+* spec-canonical form) OR a YAML block / flow list (`- item` or
+* `[a, b]`). Returns the field as a normalized `string[]`, or
+* `undefined` when the field is absent or empty.
+*
+* Used for list-shaped fields like `allowed-tools` whose authoring
+* surface has always been "either a space-separated string OR a
+* list" in skill files in the wild (Claude Code's docs use both
+* interchangeably). Pre-fix, the parser silently turned the list
+* forms into `[object Object]` / `["[a", "b]"]` and the
+* allowed-tools gate would never match anything — opening it wide.
+*
+* Diagnostics are pushed for unexpected shapes (number, plain
+* object, etc.) and the field is dropped to avoid silent corruption.
+*/
+function takeStringOrArray(frontmatter, key, diagnostics) {
+	const raw = frontmatter[key];
+	if (raw === void 0 || raw === null) return void 0;
+	if (Array.isArray(raw)) {
+		const items = raw.filter((v) => v !== null && v !== void 0).map((v) => typeof v === "string" ? v : String(v)).map((v) => v.trim()).filter((v) => v.length > 0);
+		return items.length > 0 ? items : void 0;
+	}
+	if (typeof raw === "string") {
+		const trimmed = raw.trim();
+		if (trimmed.length === 0) return void 0;
+		const flowMatch = trimmed.match(FLOW_LIST_RE);
+		if (flowMatch) return flowMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
+		return trimmed.split(WHITESPACE_SPLIT_RE).filter(Boolean);
+	}
+	diagnostics.push({
+		severity: "warning",
+		code: "invalid-field-type",
+		message: `Frontmatter field "${key}" expected string or list, got ${typeof raw}. Skipping.`,
+		field: key
+	});
+}
+const RESOURCE_DIRS = {
+	scripts: "script",
+	references: "reference",
+	assets: "asset"
+};
+function enumerateResources(baseDir) {
+	const resources = [];
+	for (const [dir, type] of Object.entries(RESOURCE_DIRS)) {
+		const dirPath = join(baseDir, dir);
+		if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) continue;
+		try {
+			const files = readdirSync(dirPath, { recursive: true });
+			for (const file of files) {
+				const rel = typeof file === "string" ? file : file.toString("utf-8");
+				if (statSync(join(dirPath, rel)).isFile()) resources.push({
+					path: join(dir, rel),
+					type
+				});
+			}
+		} catch {}
+	}
+	try {
+		for (const entry of readdirSync(baseDir)) {
+			if (entry === "SKILL.md") continue;
+			if (statSync(join(baseDir, entry)).isFile()) resources.push({
+				path: entry,
+				type: "other"
+			});
+		}
+	} catch {}
+	return resources;
+}
+/**
+* Parse a SKILL.md file into a SkillConfig (lenient).
+*
+* Returns `null` only when the skill is fundamentally unusable:
+* - The file is missing
+* - The description is absent (required by spec for disclosure)
+*
+* All other issues are surfaced as `SkillConfig.diagnostics` with severity
+* `warning`. Deprecated top-level fields (`paths`, `model`, `thinking`) are
+* auto-migrated into `metadata['zidane.*']`.
+*/
+async function parseSkillFile(filePath, options = {}) {
+	const absPath = resolve(filePath);
+	if (!existsSync(absPath)) return null;
+	const { frontmatter, body, diagnostics } = parseFrontmatter(readFileSync(absPath, "utf-8"));
+	normalizeKeyAliases(frontmatter, diagnostics);
+	let description = takeString(frontmatter, "description", diagnostics);
+	if (!description && body) {
+		const firstParagraph = body.split(PARAGRAPH_SPLIT_RE)[0]?.trim();
+		if (firstParagraph) description = firstParagraph;
+	}
+	if (!description) return null;
+	if (description.length > 1024) diagnostics.push({
+		severity: "warning",
+		code: "description-too-long",
+		message: `Description exceeds spec limit of 1024 characters (got ${description.length}). Loading anyway.`,
+		field: "description"
+	});
+	const baseDir = dirname(absPath);
+	const dirName = basename(baseDir);
+	const frontmatterName = takeString(frontmatter, "name", diagnostics);
+	const name = frontmatterName || dirName;
+	if (frontmatterName && frontmatterName !== dirName) diagnostics.push({
+		severity: "warning",
+		code: "name-mismatch-directory",
+		message: `Skill name "${frontmatterName}" does not match parent directory "${dirName}". Loading anyway.`,
+		field: "name"
+	});
+	if (name.length > 64) diagnostics.push({
+		severity: "warning",
+		code: "name-too-long",
+		message: `Skill name "${name}" exceeds spec limit of 64 characters. Loading anyway.`,
+		field: "name"
+	});
+	if (!validateSkillName(name)) diagnostics.push({
+		severity: "warning",
+		code: "invalid-name-format",
+		message: `Skill name "${name}" does not match spec format (lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens). Loading anyway.`,
+		field: "name"
+	});
+	const config = {
+		name,
+		description,
+		instructions: body,
+		source: options.source ?? "project",
+		location: absPath,
+		baseDir,
+		resources: enumerateResources(baseDir)
+	};
+	const license = takeString(frontmatter, "license", diagnostics);
+	if (license) config.license = license;
+	const compatibility = takeString(frontmatter, "compatibility", diagnostics);
+	if (compatibility) {
+		if (compatibility.length > 500) diagnostics.push({
+			severity: "warning",
+			code: "compatibility-too-long",
+			message: `Compatibility exceeds spec limit of 500 characters (got ${compatibility.length}). Loading anyway.`,
+			field: "compatibility"
+		});
+		config.compatibility = compatibility;
+	}
+	const metadata = {};
+	const rawMetadata = frontmatter.metadata;
+	if (rawMetadata && typeof rawMetadata === "object" && !Array.isArray(rawMetadata)) for (const [k, v] of Object.entries(rawMetadata)) {
+		if (typeof v !== "string") {
+			diagnostics.push({
+				severity: "warning",
+				code: "invalid-metadata-value",
+				message: `Metadata value for "${k}" is not a string; coerced. (Spec requires string values.)`,
+				field: "metadata"
+			});
+			metadata[k] = String(v);
+			continue;
+		}
+		metadata[k] = v;
+	}
+	else if (rawMetadata !== void 0) diagnostics.push({
+		severity: "warning",
+		code: "invalid-metadata-shape",
+		message: `Frontmatter "metadata" expected a map, got ${Array.isArray(rawMetadata) ? "array" : typeof rawMetadata}. Ignored.`,
+		field: "metadata"
+	});
+	const pathsField = takeString(frontmatter, "paths", diagnostics);
+	if (pathsField) {
+		metadata["zidane.paths"] = pathsField.split(COMMA_OR_SPACE_RE).filter(Boolean).join(",");
+		diagnostics.push({
+			severity: "warning",
+			code: "deprecated-top-level-field",
+			message: "`paths` is not a spec field and is deprecated — moved to `metadata[\"zidane.paths\"]`.",
+			field: "paths"
+		});
+	}
+	const modelField = takeString(frontmatter, "model", diagnostics);
+	if (modelField) {
+		metadata["zidane.model"] = modelField;
+		diagnostics.push({
+			severity: "warning",
+			code: "deprecated-top-level-field",
+			message: "`model` is not a spec field and is deprecated — moved to `metadata[\"zidane.model\"]`.",
+			field: "model"
+		});
+	}
+	const thinkingField = takeString(frontmatter, "thinking", diagnostics);
+	const effortField = thinkingField ? void 0 : takeString(frontmatter, "effort", diagnostics);
+	const legacyThinking = thinkingField ?? effortField;
+	if (legacyThinking) {
+		metadata["zidane.thinking"] = legacyThinking;
+		diagnostics.push({
+			severity: "warning",
+			code: "deprecated-top-level-field",
+			message: `\`${thinkingField ? "thinking" : "effort"}\` is not a spec field and is deprecated — moved to \`metadata["zidane.thinking"]\`.`,
+			field: thinkingField ? "thinking" : "effort"
+		});
+	}
+	if (Object.keys(metadata).length > 0) config.metadata = metadata;
+	const allowedTools = takeStringOrArray(frontmatter, "allowed-tools", diagnostics);
+	if (allowedTools && allowedTools.length > 0) config.allowedTools = allowedTools;
+	if (diagnostics.length > 0) config.diagnostics = diagnostics;
+	return config;
+}
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	".git",
+	"node_modules",
+	".DS_Store",
+	"dist",
+	"build"
+]);
+function findSkillDirs(root, maxDepth = 4, _depth = 0) {
+	if (_depth > maxDepth) return [];
+	if (!existsSync(root) || !statSync(root).isDirectory()) return [];
+	const results = [];
+	try {
+		for (const entry of readdirSync(root)) {
+			if (SKIP_DIRS.has(entry)) continue;
+			const entryPath = join(root, entry);
+			if (!statSync(entryPath).isDirectory()) continue;
+			const skillFile = join(entryPath, "SKILL.md");
+			if (existsSync(skillFile) && statSync(skillFile).isFile()) results.push(skillFile);
+			else results.push(...findSkillDirs(entryPath, maxDepth, _depth + 1));
+		}
+	} catch {}
+	return results;
 }
 /**
-* OOM guard: tarballs are buffered in memory before extraction, so an
-* unexpectedly huge (or hostile) URL must fail fast instead of ballooning
-* RSS. Install sources are source trees — 64MB is already generous.
+* Return the default scan paths tagged by source. Project-scope paths come
+* first; their skills therefore win on name collisions against user-scope
+* skills (first-found wins in discovery).
 */
-const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
-async function downloadAndExtract(url, destDir, opts) {
-	let bytes;
-	try {
-		const res = await opts.fetchImpl(url);
-		if (!res.ok) throw new Error(`download returned ${res.status}`);
-		const declared = Number(res.headers.get("content-length") ?? "0");
-		if (declared > 67108864) throw new Error(`archive is ${Math.round(declared / 1024 / 1024)}MB — larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB limit`);
-		bytes = await res.arrayBuffer();
-		if (bytes.byteLength > 67108864) throw new Error(`archive is ${Math.round(bytes.byteLength / 1024 / 1024)}MB — larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB limit`);
-	} catch (err) {
-		throw new InstallSourceError("fetch-failed", `Download failed for ${opts.what}: ${errorText(err)}`);
-	}
-	if (!opts.which("tar")) throw new InstallSourceError("fetch-failed", `Extracting ${opts.what} requires \`tar\` on PATH (or install git for the clone path).`);
-	const tarPath = join(destDir, ".zidane-install.tgz");
-	mkdirSync(destDir, { recursive: true });
-	writeFileSync(tarPath, new Uint8Array(bytes));
-	const res = await opts.exec("tar", [
-		"-xzf",
-		tarPath,
-		"-C",
-		destDir,
-		"--strip-components=1"
-	], {});
-	rmSync(tarPath, { force: true });
-	if (!res.ok) throw new InstallSourceError("fetch-failed", `Extracting ${opts.what} failed: ${lastLine(res.stderr)}`);
+function getDefaultScanPaths() {
+	const home = homedir();
+	const cwd = process.cwd();
+	return [
+		{
+			path: join(cwd, ".agents", "skills"),
+			source: "project"
+		},
+		{
+			path: join(cwd, ".zidane", "skills"),
+			source: "project"
+		},
+		{
+			path: join(home, ".agents", "skills"),
+			source: "user"
+		},
+		{
+			path: join(home, ".zidane", "skills"),
+			source: "user"
+		}
+	];
 }
 /**
-* Resolve a `:subdir` inside a fetched tree with PHYSICAL containment:
-* string-level prefix check first, then realpath both sides and re-check
-* so a malicious repo shipping a symlink (`evil -> /`) can't walk the
-* candidate search (and any follow-up validation) onto the local
-* filesystem. Returns the physical directory, or a typed refusal the
-* flavor maps onto its own error vocabulary.
+* Infer a source tag for a user-provided scan path.
+* Paths under `$HOME` are treated as 'user'; everything else as 'project'.
 */
-function resolveSubdirRoot(fetchedInto, subdir) {
-	const resolved = resolve(fetchedInto, subdir);
-	if (!resolved.startsWith(fetchedInto + sep)) return {
-		ok: false,
-		reason: "escape"
-	};
-	let physical = null;
-	try {
-		physical = realpathSync(resolved);
-	} catch {}
-	if (physical === null || !isDirectory(physical)) return {
-		ok: false,
-		reason: "missing"
-	};
-	const physicalRoot = realpathSync(fetchedInto);
-	if (physical !== physicalRoot && !physical.startsWith(physicalRoot + sep)) return {
-		ok: false,
-		reason: "escape-symlink"
-	};
-	return {
-		ok: true,
-		dir: physical
-	};
-}
-function isDirectory(path) {
-	try {
-		return lstatSync(path).isDirectory();
-	} catch {
-		return false;
-	}
-}
-function defaultExec(cmd, args, opts) {
-	return new Promise((resolvePromise) => {
-		const env = opts.env ? {
-			...process.env,
-			...opts.env
-		} : void 0;
-		execFile(cmd, [...args], {
-			cwd: opts.cwd,
-			env,
-			maxBuffer: 16 * 1024 * 1024
-		}, (err, stdout, stderr) => {
-			resolvePromise({
-				ok: !err,
-				stdout: String(stdout),
-				stderr: String(stderr)
-			});
-		});
-	});
+function inferSource(path) {
+	return path.startsWith(homedir()) ? "user" : "project";
 }
-function defaultWhich(cmd) {
-	const exts = process.platform === "win32" ? [
-		".exe",
-		".cmd",
-		".bat",
-		""
-	] : [""];
-	for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-		if (!dir) continue;
-		for (const ext of exts) {
-			const full = resolve(dir, cmd + ext);
-			try {
-				if (lstatSync(full).isFile()) return full;
-			} catch {
+/**
+* Discover skills from sourced filesystem paths.
+* Each path is scanned for subdirectories containing SKILL.md.
+* Earlier paths have higher priority (first-found wins on name collision).
+*
+* `signal` is checked between each `parseSkillFile` so a rapid `cwd` switch
+* in the host (TUI / GUI) can stop a long scan without leaking I/O. Aborts
+* reject with the signal's `reason` (or a default `AbortError`) — same shape
+* `AbortSignal.throwIfAborted()` produces in modern runtimes.
+*/
+async function discoverSkills(paths, signal) {
+	const skillsByName = /* @__PURE__ */ new Map();
+	for (const { path: scanPath, source } of paths) {
+		signal?.throwIfAborted?.();
+		const skillFiles = findSkillDirs(resolve(scanPath));
+		for (const file of skillFiles) {
+			signal?.throwIfAborted?.();
+			const skill = await parseSkillFile(file, { source });
+			if (!skill) continue;
+			if (skillsByName.has(skill.name)) {
+				const existing = skillsByName.get(skill.name);
+				const diag = {
+					severity: "warning",
+					code: "name-collision-shadowed",
+					message: `A skill with name "${skill.name}" was also found at ${file} (source: ${source}); shadowed by ${existing.location} (source: ${existing.source}).`
+				};
+				existing.diagnostics = [...existing.diagnostics ?? [], diag];
 				continue;
 			}
+			skillsByName.set(skill.name, skill);
 		}
 	}
-	return null;
+	return [...skillsByName.values()];
 }
-/** Last non-empty line of a command's output — the useful bit of tool noise. */
+//#endregion
+//#region src/install/source.ts
 /**
-* Insert `-oBatchMode=yes` into a `GIT_SSH_COMMAND` right after the command
-* token. OpenSSH resolves every option to the FIRST obtained value
-* (repeated `-o` included), so insertion-first beats a user-set
-* `-oBatchMode=no` — deliberate: the install flow cannot answer a prompt,
-* and a hang is strictly worse than a fast auth failure. A leading quote
-* (single or double) marks a command path containing spaces
-* (`"/my tools/ssh" -i key`) — insert after the CLOSING quote so the path
-* isn't split mid-token; an unterminated quote falls back to appending at
-* the end (mangled input, best-effort semantics).
+* Shared install-source layer — the source-agnostic half of "install a
+* thing from github/npm". Extracted from the extensions installer so
+* SKILL installs (and any future installable artifact) reuse the exact
+* same spec grammar, fetch pipeline, and hardening instead of forking
+* them:
+*
+*   - Spec grammar: `owner/repo[#ref][:subdir]`, `github:owner/repo`,
+*     pasted GitHub URLs (including `/tree/<ref>/<path>`),
+*     `pkg[@version]`, `@scope/pkg[@version]`.
+*   - Fetch: `git clone --depth 1` (records the exact commit) with a
+*     codeload-tarball fallback, npm registry resolve (exact versions +
+*     dist-tags) + tarball download. Downloads are double-capped at
+*     {@link MAX_DOWNLOAD_BYTES} (content-length header AND post-hoc for
+*     chunked responses). Extraction requires `tar` on PATH.
+*   - All side effects go through the injectable {@link InstallIo} seams
+*     so tests stay offline and hosts can instrument.
+*
+* Flavor-specific concerns stay OUT of this module: candidate
+* enumeration, validation, target roots, provenance files, dependency
+* installs. Flavors subclass {@link InstallSourceError} to widen the
+* error-code union while keeping `.code`-based handling uniform.
 */
-function sshCommandWithBatchMode(configured) {
-	const base = configured?.trim() || "ssh";
-	const quoteChar = base[0] === "\"" || base[0] === "'" ? base[0] : null;
-	if (quoteChar) {
-		const closing = base.indexOf(quoteChar, 1);
-		if (closing === -1) return `${base} -oBatchMode=yes`;
-		return `${base.slice(0, closing + 1)} -oBatchMode=yes${base.slice(closing + 1)}`;
-	}
-	return base.replace(/^(\S+)/, "$1 -oBatchMode=yes");
-}
-function lastLine(text) {
-	const lines = text.trim().split("\n").filter((l) => l.trim().length > 0);
-	return lines[lines.length - 1]?.trim() ?? "";
-}
-function errorText(err) {
-	return err instanceof Error ? err.message : String(err);
-}
-//#endregion
-//#region src/skills/activation.ts
-function createSkillActivationState(options = {}) {
-	const byName = /* @__PURE__ */ new Map();
-	const maxActive = typeof options.maxActive === "number" && options.maxActive > 0 ? options.maxActive : void 0;
-	return {
-		active() {
-			return [...byName.values()];
-		},
-		isActive(name) {
-			return byName.has(name);
-		},
-		get(name) {
-			return byName.get(name);
-		},
-		activate(skill, via) {
-			if (byName.has(skill.name)) return "already-active";
-			if (maxActive !== void 0 && byName.size >= maxActive) return "cap-reached";
-			byName.set(skill.name, {
-				skill,
-				activatedAt: Date.now(),
-				activatedVia: via
-			});
-			return "ok";
-		},
-		deactivate(name) {
-			const existing = byName.get(name);
-			if (!existing) return void 0;
-			byName.delete(name);
-			return existing;
-		},
-		clear() {
-			const snapshot = [...byName.values()];
-			byName.clear();
-			return snapshot;
-		}
-	};
+/**
+* Base error for install pipelines. `code` is a plain string here so
+* flavors (extensions, skills) can widen it with their own codes while
+* callers keep a single `err.code` switch. The base layer itself only
+* throws `'invalid-source'` and `'fetch-failed'`.
+*/
+var InstallSourceError = class extends Error {
+	code;
+	/** Set for candidate-selection errors — the names the caller can pick from. */
+	candidates;
+	constructor(code, message, candidates) {
+		super(message);
+		this.name = "InstallSourceError";
+		this.code = code;
+		if (candidates) this.candidates = candidates;
+	}
+};
+const GITHUB_TREE_URL_RE = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#@:]+?)(?:\.git)?\/tree\/([^/\s:]+)(?:\/([^\s:]+?))?\/?$/;
+const GITHUB_URL_RE = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#@:]+?)(?:\.git)?\/?$/;
+const OWNER_REPO_RE = /^([\w.-]+)\/([\w.-]+)$/;
+const GITHUB_REF_RE = /^[\w./-]+$/;
+const NPM_NAME_RE = /^(@[\w.-]+\/[\w.-]+|[\w.-]+)(?:@([\w.^~><=*-]+))?$/;
+/** Structural validation for a `:subdir` suffix — repo-relative, no escapes. */
+function parseSubdir(rawSubdir, raw) {
+	const subdir = rawSubdir.replace(/^\.\//, "").replace(/\/+$/, "");
+	const segments = subdir.split("/");
+	if (subdir.length === 0 || subdir.startsWith("/") || subdir.includes("\\") || segments.some((s) => s.length === 0 || s === "." || s === "..")) throw new InstallSourceError("invalid-source", `"${raw}" has an invalid subdirectory — expected a repo-relative path (no leading /, no ..).`);
+	return subdir;
 }
-//#endregion
-//#region src/skills/allowed-tools.ts
-/** Tools that are always allowed regardless of the active skills' allow-list. */
-const IMPLICITLY_ALLOWED_SKILL_TOOLS = [
-	"skills_use",
-	"skills_read",
-	"skills_run_script"
-];
 /**
-* Register `tool:gate` / `mcp:tool:gate` handlers that enforce the union of
-* `allowedTools` across active skills.
+* Classify a raw source string:
 *
-* No-op when no active skill declares an allow-list (permissive default —
-* matches the spec's "experimental" note for `allowed-tools`).
+*   - `github:owner/repo`, `owner/repo`, GitHub URLs (including
+*     `/tree/<ref>/<path>` links) → GitHub. Optional `#ref` (or the
+*     legacy `@ref`) pins a branch/tag; optional `:path/to/dir` roots the
+*     candidate search in a subdirectory: `owner/repo#branch:packages/x`.
+*   - `@scope/pkg[@version]`, `pkg[@version]` → npm (no subdir support —
+*     flavors expose their own selector for multi-candidate packages).
 *
-* Returns an `uninstall` fn. The agent calls this at run end to detach the
-* handlers and prevent cross-run hook leaks.
+* The one ambiguity — `a/b` — is resolved as GitHub: npm's slash names
+* are always scoped (`@scope/…`), so a bare `owner/repo` can only be a
+* repo. Throws `invalid-source` on anything else.
 */
-function installAllowedToolsGate(hooks, state) {
-	function effectiveUnion() {
-		const active = state.active();
-		const declared = [];
-		for (const record of active) if (record.skill.allowedTools?.length) declared.push(...record.skill.allowedTools);
+function parseInstallSource(raw) {
+	const spec = raw.trim();
+	if (spec.length === 0) throw new InstallSourceError("invalid-source", "Empty source. Expected `owner/repo`, `github:owner/repo`, a GitHub URL, or an npm package name.");
+	const explicitGithub = spec.startsWith("github:");
+	const body = explicitGithub ? spec.slice(7) : spec;
+	const tree = GITHUB_TREE_URL_RE.exec(body);
+	if (tree) return {
+		kind: "github",
+		owner: tree[1],
+		repo: tree[2],
+		ref: tree[3],
+		...tree[4] ? { subdir: parseSubdir(tree[4], raw) } : {}
+	};
+	const url = GITHUB_URL_RE.exec(body);
+	if (url) return {
+		kind: "github",
+		owner: url[1],
+		repo: url[2]
+	};
+	if (body.startsWith("@")) {
+		if (explicitGithub) throw new InstallSourceError("invalid-source", `"${raw}" mixes the github: prefix with an npm scoped name.`);
+		if (body.includes(":")) throw new InstallSourceError("invalid-source", `"${raw}": subdirectories (\`:path\`) are only supported for GitHub sources.`);
+		const m = NPM_NAME_RE.exec(body);
+		if (!m) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid npm package spec.`);
 		return {
-			union: declared.length > 0 ? [...declared, ...IMPLICITLY_ALLOWED_SKILL_TOOLS] : [],
-			active: active.map((a) => a.skill.name)
+			kind: "npm",
+			pkg: m[1],
+			...m[2] ? { version: m[2] } : {}
 		};
 	}
-	function gateHandler(ctx) {
-		if (ctx.block) return;
-		const { union, active } = effectiveUnion();
-		if (union.length === 0) return;
-		if (isToolAllowedByUnion(ctx.displayName, ctx.input, union)) return;
-		const err = new AgentToolNotAllowedError({
-			toolName: ctx.name,
-			displayName: ctx.displayName,
-			allowedUnion: union,
-			activeSkills: active
-		});
-		ctx.block = true;
-		ctx.reason = err.message;
-	}
-	function mcpGateHandler(ctx) {
-		if (ctx.block) return;
-		const { union, active } = effectiveUnion();
-		if (union.length === 0) return;
-		if (isToolAllowedByUnion(ctx.displayName, ctx.input, union)) return;
-		const err = new AgentToolNotAllowedError({
-			toolName: `mcp_${ctx.server}_${ctx.tool}`,
-			displayName: ctx.displayName,
-			allowedUnion: union,
-			activeSkills: active
-		});
-		ctx.block = true;
-		ctx.reason = err.message;
+	if (body.includes("/")) {
+		const colonIdx = body.indexOf(":");
+		const specPart = colonIdx === -1 ? body : body.slice(0, colonIdx);
+		const subdir = colonIdx === -1 ? void 0 : parseSubdir(body.slice(colonIdx + 1), raw);
+		const hashIdx = specPart.indexOf("#");
+		const refIdx = hashIdx >= 0 ? hashIdx : specPart.indexOf("@");
+		const repoPart = refIdx === -1 ? specPart : specPart.slice(0, refIdx);
+		const ref = refIdx === -1 ? void 0 : specPart.slice(refIdx + 1);
+		const m = OWNER_REPO_RE.exec(repoPart);
+		if (!m || ref !== void 0 && !GITHUB_REF_RE.test(ref)) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid GitHub repo spec (expected owner/repo, optionally #ref and :subdir).`);
+		return {
+			kind: "github",
+			owner: m[1],
+			repo: m[2],
+			...ref ? { ref } : {},
+			...subdir ? { subdir } : {}
+		};
 	}
-	const unregisterTool = hooks.hook("tool:gate", gateHandler);
-	const unregisterMcp = hooks.hook("mcp:tool:gate", mcpGateHandler);
-	return function uninstall() {
-		unregisterTool();
-		unregisterMcp();
+	if (explicitGithub) throw new InstallSourceError("invalid-source", `"${raw}" is missing the repo part (expected github:owner/repo).`);
+	if (body.includes(":")) throw new InstallSourceError("invalid-source", `"${raw}": subdirectories (\`:path\`) are only supported for GitHub sources.`);
+	const m = NPM_NAME_RE.exec(body);
+	if (!m) throw new InstallSourceError("invalid-source", `"${raw}" is not a valid npm package spec.`);
+	return {
+		kind: "npm",
+		pkg: m[1],
+		...m[2] ? { version: m[2] } : {}
 	};
 }
-//#endregion
-//#region src/skills/catalog.ts
 /**
-* Build the skill catalog XML and behavioral instructions for the system prompt.
+* Materialize the source into `destDir` (created by the caller, assumed
+* empty). Returns the provenance string plus, for git clones, the exact
+* commit SHA (the tarball fallback can't know it — codeload doesn't
+* expose the resolved commit).
 */
-function buildCatalog(skills, options = {}) {
-	if (skills.length === 0) return "";
-	const skillsToolRegistered = options.skillsToolRegistered ?? true;
-	const readToolName = options.readToolName ?? "read_file";
-	const entries = skills.map((skill) => {
-		const locationLine = skill.location ? `\n    <location>${escapeXml(skill.location)}</location>` : "";
-		return `  <skill>
-    <name>${escapeXml(skill.name)}</name>
-    <description>${escapeXml(skill.description)}</description>${locationLine}
-  </skill>`;
-	}).join("\n");
-	const hasFsSkills = skills.some((s) => s.location);
-	const hasInlineSkills = skills.some((s) => !s.location);
-	const behavioralParts = [];
-	behavioralParts.push("The following skills provide specialized instructions for specific tasks.", "When a task matches a skill's description, activate the skill to load its full instructions before proceeding.");
-	if (skillsToolRegistered) behavioralParts.push("To activate a skill, call the `skills_use` tool with the skill's name. The response contains the full instructions and any bundled resources you can then load via `skills_read` (reference files) or execute via `skills_run_script` (scripts/ directory).", "Relative paths referenced in a skill's instructions resolve against the skill directory noted in the `skills_use` response.");
-	else if (hasFsSkills) behavioralParts.push(`For skills with a <location>, use the ${readToolName} tool to read the SKILL.md file at that path.`, "When a skill references relative paths, resolve them against the skill's directory (the parent of SKILL.md) and use absolute paths in tool calls.");
-	if (hasInlineSkills && !skillsToolRegistered) behavioralParts.push("Skills without a <location> have their instructions included directly in <instructions> tags below.");
-	const parts = [
-		behavioralParts.join("\n"),
-		"",
-		"<available_skills>",
-		entries,
-		"</available_skills>"
-	];
-	if (hasInlineSkills && !skillsToolRegistered) {
-		parts.push("");
-		for (const skill of skills) if (!skill.location && skill.instructions) {
-			parts.push(`<skill_instructions name="${escapeXml(skill.name)}">`);
-			parts.push(skill.instructions);
-			if (skill.resources && skill.resources.length > 0) {
-				parts.push("");
-				parts.push("<skill_resources>");
-				for (const res of skill.resources) parts.push(`  <file type="${res.type}">${escapeXml(res.path)}</file>`);
-				parts.push("</skill_resources>");
+async function fetchInstallSource(source, destDir, io = {}, onProgress) {
+	const exec = io.exec ?? defaultExec;
+	const which = io.which ?? defaultWhich;
+	const fetchImpl = io.fetch ?? fetch;
+	if (source.kind === "github") {
+		const label = `${source.owner}/${source.repo}${source.ref ? `@${source.ref}` : ""}${source.subdir ? `:${source.subdir}` : ""}`;
+		if (which("git")) {
+			onProgress?.(`cloning github.com/${label}…`);
+			const cloneArgs = (url) => {
+				const args = [
+					"clone",
+					"--depth",
+					"1",
+					"--single-branch"
+				];
+				if (source.ref) args.push("--branch", source.ref);
+				args.push(url, destDir);
+				return args;
+			};
+			let res = await exec("git", cloneArgs(`https://github.com/${source.owner}/${source.repo}.git`), { env: { GIT_TERMINAL_PROMPT: "0" } });
+			if (!res.ok && /could not read username|terminal prompts disabled|authentication failed|repository not found/i.test(res.stderr)) {
+				rmSync(destDir, {
+					recursive: true,
+					force: true
+				});
+				mkdirSync(destDir, { recursive: true });
+				onProgress?.(`anonymous clone rejected — retrying via SSH (git@github.com:${source.owner}/${source.repo})…`);
+				const ssh = await exec("git", cloneArgs(`git@github.com:${source.owner}/${source.repo}.git`), { env: {
+					GIT_TERMINAL_PROMPT: "0",
+					GIT_SSH_COMMAND: sshCommandWithBatchMode(process.env.GIT_SSH_COMMAND)
+				} });
+				if (ssh.ok) res = ssh;
+				else throw new InstallSourceError("fetch-failed", `git clone failed for ${label}: ${lastLine(res.stderr)}; SSH retry also failed: ${lastLine(ssh.stderr)} (private repo? check your GitHub SSH keys / repo access, or configure git credentials for HTTPS)`);
 			}
-			parts.push("</skill_instructions>");
-		}
-	}
-	return parts.join("\n");
-}
-//#endregion
-//#region src/skills/discovery.ts
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-const INDENT_RE = /^[ \t]{2,}/;
-const KV_RE = /^([^:]+):(.*)$/;
-const DOUBLE_QUOTED_RE = /^"((?:\\.|[^"\\])*)"$/;
-const SINGLE_QUOTED_RE = /^'((?:''|[^'])*)'$/;
-const DQ_ESCAPE_RE = /\\(["\\/bfnrt])/g;
-const WHITESPACE_SPLIT_RE = /\s+/;
-const PARAGRAPH_SPLIT_RE = /\n\n/;
-const COMMA_OR_SPACE_RE = /[,\s]+/;
-/**
-* Block-list bullet (`- value`) under an indented frontmatter key. A
-* single dash followed by either a space or end-of-line; bare `-` is a
-* list item with an empty value (preserved by callers as `""` because
-* the spec doesn't disallow it).
-*/
-const LIST_ITEM_RE = /^-(?:\s+|$)/;
-/**
-* Flow-style list scalar (`[a, b, c]`). Anchored, non-nested, single
-* pass — we trim the outer brackets and let the caller split on
-* commas. Anything more complex (nested brackets, quoted commas)
-* falls through to the whitespace-split branch, where the bracket
-* characters become visible authoring errors instead of silent garbage.
-*
-* Carefully written without overlapping `\s*` runs so it's not
-* ReDoS-prone: the body class `[^[\]]*` already swallows whitespace,
-* so wrapping it in `\s*…\s*` would let the regex engine
-* non-deterministically split a run of spaces between the body and
-* the boundary quantifiers.
-*/
-const FLOW_LIST_RE = /^\[([^[\]]*)\]$/;
+			if (!res.ok) throw new InstallSourceError("fetch-failed", `git clone failed for ${label}: ${lastLine(res.stderr)}`);
+			const head = await exec("git", ["rev-parse", "HEAD"], { cwd: destDir });
+			const commit = head.ok && /^[0-9a-f]{40}$/.test(head.stdout.trim()) ? head.stdout.trim() : void 0;
+			rmSync(join(destDir, ".git"), {
+				recursive: true,
+				force: true
+			});
+			return {
+				provenance: `github:${label}`,
+				...commit ? { commit } : {}
+			};
+		}
+		onProgress?.(`downloading github.com/${label} tarball…`);
+		const ref = source.ref ?? "HEAD";
+		await downloadAndExtract(`https://codeload.github.com/${source.owner}/${source.repo}/tar.gz/${ref}`, destDir, {
+			exec,
+			fetchImpl,
+			which,
+			what: label
+		});
+		return { provenance: `github:${label}` };
+	}
+	onProgress?.(`resolving npm:${source.pkg}…`);
+	const { version, tarball } = await resolveNpmVersion(source, fetchImpl);
+	onProgress?.(`downloading npm:${source.pkg}@${version}…`);
+	await downloadAndExtract(tarball, destDir, {
+		exec,
+		fetchImpl,
+		which,
+		what: `${source.pkg}@${version}`
+	});
+	return { provenance: `npm:${source.pkg}@${version}` };
+}
 /**
-* Common kebab/camel/snake misspellings of multi-word spec frontmatter
-* keys. The Agent Skills spec mandates kebab-case (`allowed-tools`), but
-* authors raised on JS / Python idioms naturally reach for camelCase
-* (`allowedTools`) or snake_case (`allowed_tools`) — and the consequences
-* of a silent mismatch on `allowed-tools` specifically are nasty: the
-* skill loads fine, looks active in the UI, the model reads the body
-* and tells the user "tools are restricted", but the `tool:gate`
-* middleware finds nothing in the union and runs permissively. So we
-* look for these alts at parse time, migrate the value to the canonical
-* key, and emit a diagnostic so the next person sees the issue clearly.
-*
-* Keep the value space tight — accepting too many shapes erodes the
-* "lenient load, strict authoring" principle. Add entries only for keys
-* that are (a) multi-word (single-word keys have no ambiguity), (b) in
-* active use, and (c) cause silent failures when missing (gate keys,
-* security gates, …).
+* Registry lookup shared by the fetch path and update no-op checks.
+* Exact versions and dist-tags only — range resolution is out of scope.
 */
-const FRONTMATTER_KEY_ALIASES = /* @__PURE__ */ new Map([["allowed-tools", ["allowedTools", "allowed_tools"]]]);
+async function resolveNpmVersion(source, fetchImpl) {
+	const registryUrl = `https://registry.npmjs.org/${source.pkg.replace("/", "%2F")}`;
+	let meta;
+	try {
+		const res = await fetchImpl(registryUrl);
+		if (!res.ok) throw new Error(`registry returned ${res.status}`);
+		meta = await res.json();
+	} catch (err) {
+		throw new InstallSourceError("fetch-failed", `Could not resolve npm package "${source.pkg}": ${errorText(err)}`);
+	}
+	const version = source.version && meta.versions?.[source.version] ? source.version : meta["dist-tags"]?.[source.version ?? "latest"];
+	const tarball = version ? meta.versions?.[version]?.dist?.tarball : void 0;
+	if (!version || !tarball) throw new InstallSourceError("fetch-failed", `npm package "${source.pkg}" has no ${source.version ? `version/tag "${source.version}"` : "latest version"} (exact versions and dist-tags only — ranges are not resolved).`);
+	return {
+		version,
+		tarball
+	};
+}
 /**
-* Mutate `frontmatter` so any well-known alt-spelling of a canonical
-* spec key gets folded into the canonical slot. Idempotent — when the
-* canonical key is already set the function is a no-op even if an
-* alt-spelling is also present (canonical wins; alt is ignored).
-*
-* Pushes a `frontmatter-key-alt-spelling` diagnostic per migration so
-* the SkillConfig's `.diagnostics` carries an actionable hint into any
-* host UI surfacing skill load issues.
+* OOM guard: tarballs are buffered in memory before extraction, so an
+* unexpectedly huge (or hostile) URL must fail fast instead of ballooning
+* RSS. Install sources are source trees — 64MB is already generous.
 */
-function normalizeKeyAliases(frontmatter, diagnostics) {
-	for (const [canonical, aliases] of FRONTMATTER_KEY_ALIASES) {
-		if (frontmatter[canonical] !== void 0) continue;
-		for (const alias of aliases) {
-			if (frontmatter[alias] === void 0) continue;
-			frontmatter[canonical] = frontmatter[alias];
-			diagnostics.push({
-				severity: "warning",
-				code: "frontmatter-key-alt-spelling",
-				message: `Frontmatter field "${alias}" is not a spec key — the spec uses "${canonical}" (kebab-case). Reading the value from "${alias}" as a courtesy; rename it to "${canonical}" to silence this warning.`,
-				field: alias
-			});
-			break;
-		}
+const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+async function downloadAndExtract(url, destDir, opts) {
+	let bytes;
+	try {
+		const res = await opts.fetchImpl(url);
+		if (!res.ok) throw new Error(`download returned ${res.status}`);
+		const declared = Number(res.headers.get("content-length") ?? "0");
+		if (declared > 67108864) throw new Error(`archive is ${Math.round(declared / 1024 / 1024)}MB — larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB limit`);
+		bytes = await res.arrayBuffer();
+		if (bytes.byteLength > 67108864) throw new Error(`archive is ${Math.round(bytes.byteLength / 1024 / 1024)}MB — larger than the ${MAX_DOWNLOAD_BYTES / 1024 / 1024}MB limit`);
+	} catch (err) {
+		throw new InstallSourceError("fetch-failed", `Download failed for ${opts.what}: ${errorText(err)}`);
 	}
+	if (!opts.which("tar")) throw new InstallSourceError("fetch-failed", `Extracting ${opts.what} requires \`tar\` on PATH (or install git for the clone path).`);
+	const tarPath = join(destDir, ".zidane-install.tgz");
+	mkdirSync(destDir, { recursive: true });
+	writeFileSync(tarPath, new Uint8Array(bytes));
+	const res = await opts.exec("tar", [
+		"-xzf",
+		tarPath,
+		"-C",
+		destDir,
+		"--strip-components=1"
+	], {});
+	rmSync(tarPath, { force: true });
+	if (!res.ok) throw new InstallSourceError("fetch-failed", `Extracting ${opts.what} failed: ${lastLine(res.stderr)}`);
 }
 /**
-* Parse a SKILL.md file into frontmatter + body.
-*
-* Uses a simple regex-based YAML extractor that handles:
-* - Flat key: value pairs
-* - Quoted values
-* - One-level nested maps (for `metadata:`)
-* - One-level nested block lists, `key:` followed by indented `- item`
-*   lines (for `allowed-tools` and any future array fields). Items are
-*   unquoted with the same rules as scalar values.
-* - Flow-style scalars are preserved verbatim — interpretation (e.g.
-*   `[a, b]` as a list) is left to per-field consumers via
-*   {@link takeStringOrArray}.
-* - Lenient recovery from unquoted-colon values (e.g.
-*   `description: Use when: the user asks …`) via a quote-wrap retry.
+* Resolve a `:subdir` inside a fetched tree with PHYSICAL containment:
+* string-level prefix check first, then realpath both sides and re-check
+* so a malicious repo shipping a symlink (`evil -> /`) can't walk the
+* candidate search (and any follow-up validation) onto the local
+* filesystem. Returns the physical directory, or a typed refusal the
+* flavor maps onto its own error vocabulary.
 */
-function parseFrontmatter(content) {
-	const diagnostics = [];
-	const match = content.match(FRONTMATTER_RE);
-	if (!match) return {
-		frontmatter: {},
-		body: content.trim(),
-		diagnostics
+function resolveSubdirRoot(fetchedInto, subdir) {
+	const resolved = resolve(fetchedInto, subdir);
+	if (!resolved.startsWith(fetchedInto + sep)) return {
+		ok: false,
+		reason: "escape"
 	};
-	const yamlBlock = match[1];
-	const body = match[2].trim();
-	const frontmatter = {};
-	let currentKey = null;
-	let currentMap = null;
-	let currentList = null;
-	const flushPending = () => {
-		if (currentKey === null) return;
-		if (currentList !== null) frontmatter[currentKey] = currentList;
-		else if (currentMap !== null) frontmatter[currentKey] = currentMap;
-		currentKey = null;
-		currentMap = null;
-		currentList = null;
+	let physical = null;
+	try {
+		physical = realpathSync(resolved);
+	} catch {}
+	if (physical === null || !isDirectory(physical)) return {
+		ok: false,
+		reason: "missing"
 	};
-	for (const line of yamlBlock.split("\n")) {
-		if (!line.trim() || line.trim().startsWith("#")) continue;
-		if (currentKey !== null && INDENT_RE.test(line)) {
-			const stripped = line.trim();
-			if (LIST_ITEM_RE.test(stripped)) {
-				if (currentMap !== null && Object.keys(currentMap).length > 0) {
-					diagnostics.push({
-						severity: "warning",
-						code: "mixed-list-and-map",
-						message: `Frontmatter field "${currentKey}" mixes list items and map entries — keeping the map and dropping the list items.`,
-						field: currentKey
-					});
-					continue;
-				}
-				currentList = currentList ?? [];
-				currentList.push(unquoteYaml(stripped.slice(1).trim()));
+	const physicalRoot = realpathSync(fetchedInto);
+	if (physical !== physicalRoot && !physical.startsWith(physicalRoot + sep)) return {
+		ok: false,
+		reason: "escape-symlink"
+	};
+	return {
+		ok: true,
+		dir: physical
+	};
+}
+function isDirectory(path) {
+	try {
+		return lstatSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function defaultExec(cmd, args, opts) {
+	return new Promise((resolvePromise) => {
+		const env = opts.env ? {
+			...process.env,
+			...opts.env
+		} : void 0;
+		execFile(cmd, [...args], {
+			cwd: opts.cwd,
+			env,
+			maxBuffer: 16 * 1024 * 1024
+		}, (err, stdout, stderr) => {
+			resolvePromise({
+				ok: !err,
+				stdout: String(stdout),
+				stderr: String(stderr)
+			});
+		});
+	});
+}
+function defaultWhich(cmd) {
+	const exts = process.platform === "win32" ? [
+		".exe",
+		".cmd",
+		".bat",
+		""
+	] : [""];
+	for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+		if (!dir) continue;
+		for (const ext of exts) {
+			const full = resolve(dir, cmd + ext);
+			try {
+				if (lstatSync(full).isFile()) return full;
+			} catch {
 				continue;
 			}
-			const nestedMatch = stripped.match(KV_RE);
-			if (nestedMatch) {
-				if (currentList !== null) {
-					diagnostics.push({
-						severity: "warning",
-						code: "mixed-list-and-map",
-						message: `Frontmatter field "${currentKey}" mixes list items and map entries — keeping the list and dropping the map entries.`,
-						field: currentKey
-					});
-					continue;
-				}
-				currentMap = currentMap ?? {};
-				const val = nestedMatch[2].trim();
-				currentMap[nestedMatch[1].trim()] = unquoteYaml(val);
-			}
-			continue;
 		}
-		flushPending();
-		const kvMatch = matchFirstColon(line);
-		if (!kvMatch) continue;
-		const key = kvMatch.key.trim();
-		const rawValue = kvMatch.value.trim();
-		if (!rawValue) currentKey = key;
-		else frontmatter[key] = unquoteYaml(rawValue);
 	}
-	flushPending();
-	return {
-		frontmatter,
-		body,
-		diagnostics
-	};
+	return null;
+}
+/** Last non-empty line of a command's output — the useful bit of tool noise. */
+/**
+* Insert `-oBatchMode=yes` into a `GIT_SSH_COMMAND` right after the command
+* token. OpenSSH resolves every option to the FIRST obtained value
+* (repeated `-o` included), so insertion-first beats a user-set
+* `-oBatchMode=no` — deliberate: the install flow cannot answer a prompt,
+* and a hang is strictly worse than a fast auth failure. A leading quote
+* (single or double) marks a command path containing spaces
+* (`"/my tools/ssh" -i key`) — insert after the CLOSING quote so the path
+* isn't split mid-token; an unterminated quote falls back to appending at
+* the end (mangled input, best-effort semantics).
+*/
+function sshCommandWithBatchMode(configured) {
+	const base = configured?.trim() || "ssh";
+	const quoteChar = base[0] === "\"" || base[0] === "'" ? base[0] : null;
+	if (quoteChar) {
+		const closing = base.indexOf(quoteChar, 1);
+		if (closing === -1) return `${base} -oBatchMode=yes`;
+		return `${base.slice(0, closing + 1)} -oBatchMode=yes${base.slice(closing + 1)}`;
+	}
+	return base.replace(/^(\S+)/, "$1 -oBatchMode=yes");
 }
-function matchFirstColon(line) {
-	const idx = line.indexOf(":");
-	if (idx < 0) return null;
-	const key = line.slice(0, idx);
-	const value = line.slice(idx + 1);
-	if (!KV_RE.test(`${key}:`)) return null;
-	return {
-		key,
-		value
+function lastLine(text) {
+	const lines = text.trim().split("\n").filter((l) => l.trim().length > 0);
+	return lines[lines.length - 1]?.trim() ?? "";
+}
+function errorText(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/skills/install.ts
+var SkillInstallError = class extends InstallSourceError {
+	/**
+	* Frontmatter metadata per candidate, parallel to `candidates` — set on
+	* the selector-less `multiple-candidates` error so host pickers can show
+	* descriptions without re-fetching the source. Best-effort: candidates
+	* whose SKILL.md fails to parse appear with no description.
+	*/
+	details;
+	constructor(code, message, candidates, details) {
+		super(code, message, candidates);
+		this.name = "SkillInstallError";
+		if (details) this.details = details;
+	}
+};
+function rethrowAsSkillError(err) {
+	if (err instanceof InstallSourceError && !(err instanceof SkillInstallError)) throw new SkillInstallError(err.code, err.message, err.candidates);
+	throw err;
+}
+const SKILLS_SH_URL_RE = /^(?:https?:\/\/)?(?:www\.)?skills\.sh\/([\w.-]+)\/([\w.-]+)(?:\/([\w.-]+))?\/?$/;
+/**
+* Pasted install commands, as printed by skill READMEs and skills.sh
+* pages — `npx skills add owner/repo`, `bunx skills add …`,
+* `pnpm dlx skills add … --skill x`, or a bare `skills add …`. The
+* runner + `add` verb are stripped and the remaining tokens re-enter
+* the normal grammar, so users can copy a whole command into the
+* install input verbatim.
+*/
+const SKILLS_CLI_COMMAND_RE = /^(?:(?:npx|bunx|yarn\s+dlx|pnpm\s+dlx)\s+)?skills(?:@\S+)?\s+add\s+(\S.*)$/i;
+/**
+* Parse a raw skill source. Accepts everything the shared grammar does
+* (`owner/repo[#ref][:subdir]`, GitHub URLs, `pkg@version`, …) plus
+* pasted skills.sh catalog URLs — `skills.sh/vercel-labs/agent-skills/
+* react-best-practices` maps to the backing GitHub repo with the third
+* segment as the skill selector.
+*/
+function parseSkillInstallSpec(raw) {
+	const spec = raw.trim();
+	const cliCommand = SKILLS_CLI_COMMAND_RE.exec(spec);
+	if (cliCommand) return parseCliAddCommand(cliCommand[1]);
+	const skillsSh = SKILLS_SH_URL_RE.exec(spec);
+	if (skillsSh) return {
+		source: {
+			kind: "github",
+			owner: skillsSh[1],
+			repo: skillsSh[2]
+		},
+		...skillsSh[3] ? { skill: skillsSh[3] } : {},
+		cliSpec: `${skillsSh[1]}/${skillsSh[2]}`
 	};
+	try {
+		return {
+			source: parseInstallSource(spec),
+			cliSpec: spec
+		};
+	} catch (err) {
+		rethrowAsSkillError(err);
+	}
 }
 /**
-* Strip outer quotes and decode YAML-style escapes.
-*
-* - Double-quoted values honor `\"`, `\\`, `\n`, `\r`, `\t`, `\b`, `\f`, `\/`.
-* - Single-quoted values honor `''` (the YAML single-quote escape for a literal `'`).
-* - Trailing inline comments on unquoted values (` # comment`) are dropped.
-* - Unquoted values are returned as-is (trimmed by caller).
-*
-* Skill frontmatter in the wild uses a narrow YAML subset — this is
-* sufficient for every field in the current spec and the common authoring
-* tools. Block scalars (`|`, `>`) and flow sequences are intentionally left
-* unsupported: they'd only appear in a bespoke workflow, and silently
-* half-supporting them is worse than rejecting them obviously.
+* Parse the argument tail of a pasted `skills add …` command. Honors
+* `--skill <name>` / `--skill=<name>` (their per-skill selector — an
+* explicit selector in the URL/shorthand form wins over it), ignores
+* flags that are the dialog's job here (`-y`, `-g`, `--global`, …),
+* and routes the first non-flag token back through
+* {@link parseSkillInstallSpec} so URLs and shorthands inside the
+* command parse identically to a bare paste.
 */
-function unquoteYaml(val) {
-	const dq = val.match(DOUBLE_QUOTED_RE);
-	if (dq) return dq[1].replace(DQ_ESCAPE_RE, (_, ch) => {
-		switch (ch) {
-			case "\"": return "\"";
-			case "\\": return "\\";
-			case "/": return "/";
-			case "b": return "\b";
-			case "f": return "\f";
-			case "n": return "\n";
-			case "r": return "\r";
-			case "t": return "	";
-			default: return ch;
+function parseCliAddCommand(rest) {
+	const tokens = rest.split(/\s+/).filter((t) => t.length > 0);
+	let sourceToken;
+	let skill;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--skill" || token === "-s") {
+			skill = tokens[i + 1];
+			i += 1;
+			continue;
 		}
-	});
-	const sq = val.match(SINGLE_QUOTED_RE);
-	if (sq) return sq[1].replace(/''/g, "'");
-	const hashIdx = val.indexOf(" #");
-	if (hashIdx >= 0) return val.slice(0, hashIdx).trimEnd();
-	return val;
+		const inline = /^--skill=(.+)$/.exec(token);
+		if (inline) {
+			skill = inline[1];
+			continue;
+		}
+		if (token.startsWith("-")) continue;
+		if (sourceToken === void 0) sourceToken = token;
+	}
+	if (sourceToken === void 0) throw new SkillInstallError("invalid-source", "Pasted skills command has no source — expected “skills add <owner/repo>”.");
+	const parsed = parseSkillInstallSpec(sourceToken);
+	return {
+		...parsed,
+		...skill !== void 0 && parsed.skill === void 0 ? { skill } : {}
+	};
 }
 /**
-* Narrow a frontmatter field to a string. Produces a diagnostic when present
-* but not a string, so malformed YAML (e.g. `name: 123`) surfaces as a
-* warning instead of silently coerced downstream via `as string`.
+* How deep the candidate walk descends. Real-world collections nest
+* skills under category directories (`skills/engineering/tdd/SKILL.md`
+* in mattpocock/skills; `.github/skills/…` elsewhere) — one-level
+* enumeration missed all of them. Four levels covers every observed
+* layout while keeping the walk trivially bounded on the staged tree.
 */
-function takeString(frontmatter, key, diagnostics) {
-	const raw = frontmatter[key];
-	if (raw === void 0 || raw === null) return void 0;
-	if (typeof raw === "string") return raw;
-	diagnostics.push({
-		severity: "warning",
-		code: "invalid-field-type",
-		message: `Frontmatter field "${key}" expected string, got ${Array.isArray(raw) ? "array" : typeof raw}. Skipping.`,
-		field: key
-	});
-}
+const CANDIDATE_WALK_MAX_DEPTH = 4;
 /**
-* Accept either a YAML scalar (whitespace-separated tokens, the
-* spec-canonical form) OR a YAML block / flow list (`- item` or
-* `[a, b]`). Returns the field as a normalized `string[]`, or
-* `undefined` when the field is absent or empty.
+* List installable skills inside a fetched tree.
 *
-* Used for list-shaped fields like `allowed-tools` whose authoring
-* surface has always been "either a space-separated string OR a
-* list" in skill files in the wild (Claude Code's docs use both
-* interchangeably). Pre-fix, the parser silently turned the list
-* forms into `[object Object]` / `["[a", "b]"]` and the
-* allowed-tools gate would never match anything — opening it wide.
+* A skill is ANY directory containing a `SKILL.md` — found by a
+* bounded recursive walk (depth {@link CANDIDATE_WALK_MAX_DEPTH}),
+* skipping dot-dirs and `node_modules`, and never descending INTO a
+* skill (its `references/` / `scripts/` subtree ships with it, it
+* doesn't nest further candidates). A root-level `SKILL.md` means
+* "repo IS the skill" and short-circuits, named from the fallback.
 *
-* Diagnostics are pushed for unexpected shapes (number, plain
-* object, etc.) and the field is dropped to avoid silent corruption.
+* Candidates carry their root-relative path (`rel`) so same-named
+* skills in different categories stay individually addressable.
+* Sorted by `rel`.
 */
-function takeStringOrArray(frontmatter, key, diagnostics) {
-	const raw = frontmatter[key];
-	if (raw === void 0 || raw === null) return void 0;
-	if (Array.isArray(raw)) {
-		const items = raw.filter((v) => v !== null && v !== void 0).map((v) => typeof v === "string" ? v : String(v)).map((v) => v.trim()).filter((v) => v.length > 0);
-		return items.length > 0 ? items : void 0;
-	}
-	if (typeof raw === "string") {
-		const trimmed = raw.trim();
-		if (trimmed.length === 0) return void 0;
-		const flowMatch = trimmed.match(FLOW_LIST_RE);
-		if (flowMatch) return flowMatch[1].split(",").map((s) => s.trim()).filter(Boolean);
-		return trimmed.split(WHITESPACE_SPLIT_RE).filter(Boolean);
-	}
-	diagnostics.push({
-		severity: "warning",
-		code: "invalid-field-type",
-		message: `Frontmatter field "${key}" expected string or list, got ${typeof raw}. Skipping.`,
-		field: key
-	});
-}
-const RESOURCE_DIRS = {
-	scripts: "script",
-	references: "reference",
-	assets: "asset"
-};
-function enumerateResources(baseDir) {
-	const resources = [];
-	for (const [dir, type] of Object.entries(RESOURCE_DIRS)) {
-		const dirPath = join(baseDir, dir);
-		if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) continue;
-		try {
-			const files = readdirSync(dirPath, { recursive: true });
-			for (const file of files) {
-				const rel = typeof file === "string" ? file : file.toString("utf-8");
-				if (statSync(join(dirPath, rel)).isFile()) resources.push({
-					path: join(dir, rel),
-					type
-				});
-			}
-		} catch {}
-	}
-	try {
-		for (const entry of readdirSync(baseDir)) {
-			if (entry === "SKILL.md") continue;
-			if (statSync(join(baseDir, entry)).isFile()) resources.push({
-				path: entry,
-				type: "other"
+function listSkillCandidates(dir, fallbackName) {
+	if (existsSync(join(dir, "SKILL.md"))) return [{
+		name: sanitizeName(fallbackName),
+		dir,
+		rel: "."
+	}];
+	const out = [];
+	const walk = (current, rel, depth) => {
+		if (depth > CANDIDATE_WALK_MAX_DEPTH) return;
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") continue;
+			const childDir = join(current, entry.name);
+			const childRel = rel.length === 0 ? entry.name : `${rel}/${entry.name}`;
+			if (existsSync(join(childDir, "SKILL.md"))) out.push({
+				name: entry.name,
+				dir: childDir,
+				rel: childRel
 			});
+			else walk(childDir, childRel, depth + 1);
 		}
-	} catch {}
-	return resources;
+	};
+	walk(dir, "", 1);
+	return out.sort((a, b) => a.rel.localeCompare(b.rel));
 }
 /**
-* Parse a SKILL.md file into a SkillConfig (lenient).
-*
-* Returns `null` only when the skill is fundamentally unusable:
-* - The file is missing
-* - The description is absent (required by spec for disclosure)
-*
-* All other issues are surfaced as `SkillConfig.diagnostics` with severity
-* `warning`. Deprecated top-level fields (`paths`, `model`, `thinking`) are
-* auto-migrated into `metadata['zidane.*']`.
+* Frontmatter details for a host picker, parallel to the candidate list.
+* Parsing is best-effort per candidate — a malformed SKILL.md yields a
+* detail row without a description rather than failing the enumeration.
 */
-async function parseSkillFile(filePath, options = {}) {
-	const absPath = resolve(filePath);
-	if (!existsSync(absPath)) return null;
-	const { frontmatter, body, diagnostics } = parseFrontmatter(readFileSync(absPath, "utf-8"));
-	normalizeKeyAliases(frontmatter, diagnostics);
-	let description = takeString(frontmatter, "description", diagnostics);
-	if (!description && body) {
-		const firstParagraph = body.split(PARAGRAPH_SPLIT_RE)[0]?.trim();
-		if (firstParagraph) description = firstParagraph;
-	}
-	if (!description) return null;
-	if (description.length > 1024) diagnostics.push({
-		severity: "warning",
-		code: "description-too-long",
-		message: `Description exceeds spec limit of 1024 characters (got ${description.length}). Loading anyway.`,
-		field: "description"
-	});
-	const baseDir = dirname(absPath);
-	const dirName = basename(baseDir);
-	const frontmatterName = takeString(frontmatter, "name", diagnostics);
-	const name = frontmatterName || dirName;
-	if (frontmatterName && frontmatterName !== dirName) diagnostics.push({
-		severity: "warning",
-		code: "name-mismatch-directory",
-		message: `Skill name "${frontmatterName}" does not match parent directory "${dirName}". Loading anyway.`,
-		field: "name"
-	});
-	if (name.length > 64) diagnostics.push({
-		severity: "warning",
-		code: "name-too-long",
-		message: `Skill name "${name}" exceeds spec limit of 64 characters. Loading anyway.`,
-		field: "name"
-	});
-	if (!validateSkillName(name)) diagnostics.push({
-		severity: "warning",
-		code: "invalid-name-format",
-		message: `Skill name "${name}" does not match spec format (lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens). Loading anyway.`,
-		field: "name"
-	});
-	const config = {
-		name,
-		description,
-		instructions: body,
-		source: options.source ?? "project",
-		location: absPath,
-		baseDir,
-		resources: enumerateResources(baseDir)
-	};
-	const license = takeString(frontmatter, "license", diagnostics);
-	if (license) config.license = license;
-	const compatibility = takeString(frontmatter, "compatibility", diagnostics);
-	if (compatibility) {
-		if (compatibility.length > 500) diagnostics.push({
-			severity: "warning",
-			code: "compatibility-too-long",
-			message: `Compatibility exceeds spec limit of 500 characters (got ${compatibility.length}). Loading anyway.`,
-			field: "compatibility"
-		});
-		config.compatibility = compatibility;
-	}
-	const metadata = {};
-	const rawMetadata = frontmatter.metadata;
-	if (rawMetadata && typeof rawMetadata === "object" && !Array.isArray(rawMetadata)) for (const [k, v] of Object.entries(rawMetadata)) {
-		if (typeof v !== "string") {
-			diagnostics.push({
-				severity: "warning",
-				code: "invalid-metadata-value",
-				message: `Metadata value for "${k}" is not a string; coerced. (Spec requires string values.)`,
-				field: "metadata"
+async function candidateDetails(candidates) {
+	return Promise.all(candidates.map(async (c) => {
+		const description = (await parseSkillFile(join(c.dir, "SKILL.md")).catch(() => null))?.description.trim();
+		return {
+			rel: c.rel,
+			...description ? { description } : {}
+		};
+	}));
+}
+/** Human-readable candidate list for error messages — capped, rel-qualified when ambiguous. */
+function describeCandidates(candidates) {
+	const nameCounts = /* @__PURE__ */ new Map();
+	for (const c of candidates) nameCounts.set(c.name, (nameCounts.get(c.name) ?? 0) + 1);
+	const labels = candidates.map((c) => (nameCounts.get(c.name) ?? 0) > 1 ? c.rel : c.name);
+	const shown = labels.slice(0, 20);
+	const more = labels.length - shown.length;
+	return shown.join(", ") + (more > 0 ? `, … and ${more} more` : "");
+}
+/**
+* Validate a staged candidate by PARSING its SKILL.md — the same lenient
+* parser discovery runs, so "installs cleanly" and "discovers cleanly"
+* are the same predicate. Returns the frontmatter name (which wins over
+* the directory-derived candidate name for the target folder).
+*/
+async function validateSkillCandidate(candidate) {
+	const parsed = await parseSkillFile(join(candidate.dir, "SKILL.md"));
+	if (!parsed) throw new SkillInstallError("validate-failed", `${candidate.dir}/SKILL.md is not a valid skill (missing name or description in frontmatter).`);
+	const name = parsed.name;
+	if (!validateSkillName(name)) throw new SkillInstallError("validate-failed", `Skill name "${name}" is invalid (lowercase alphanumerics + single hyphens, max 64 chars).`);
+	return { name };
+}
+/**
+* Install a skill (or one skill out of a multi-skill source).
+*
+* Engine selection: targeted installs (an explicit skill selector) go
+* through the skills.sh CLI when present on PATH (unless
+* `preferSkillsCli: false`) — keeping their cross-agent layout and
+* lockfile — else the native fetch pipeline. Selector-less installs are
+* ALWAYS native: only native enumeration can tell single- from
+* multi-skill sources, and the host's "import all?" prompt rides on the
+* `multiple-candidates` error — delegating them to `skills add … -y`
+* would let the CLI's own multi-skill behavior silently decide instead.
+* `all: true` batches are native for the same reason (skip-existing +
+* per-skill provenance are our semantics).
+*/
+async function installSkillFromSpec(opts) {
+	const which = (opts.io ?? {}).which ?? defaultWhich;
+	const spec = parseSkillInstallSpec(opts.source);
+	const batchMode = opts.all === true || (opts.skills?.length ?? 0) > 0;
+	const skillSelector = opts.skill ?? (batchMode ? void 0 : spec.skill);
+	if (!batchMode && skillSelector !== void 0 && (opts.preferSkillsCli ?? true) && which("skills")) return await installViaSkillsCli(spec, skillSelector, opts);
+	return await installNatively(spec, skillSelector, opts);
+}
+/**
+* Delegate to the skills.sh CLI. Non-interactive by construction: `-y`
+* skips confirmation prompts, `-g` maps our `user` scope to their
+* global scope (project scope is their default, keyed off cwd). The CLI
+* decides the on-disk layout (`.agents/skills/`), which zidane's
+* discovery already scans.
+*/
+async function installViaSkillsCli(spec, skillSelector, opts) {
+	const exec = opts.io?.exec ?? defaultExec;
+	const args = [
+		"add",
+		spec.cliSpec,
+		"-y"
+	];
+	if (skillSelector) args.push("--skill", skillSelector);
+	if (opts.scope === "user") args.push("-g");
+	opts.onProgress?.(`skills add ${spec.cliSpec}${skillSelector ? ` --skill ${skillSelector}` : ""}…`);
+	const res = await exec("skills", args, { cwd: opts.cwd ?? process.cwd() });
+	if (!res.ok) throw new SkillInstallError("cli-failed", `skills.sh CLI failed: ${lastLine(res.stderr) || lastLine(res.stdout) || "unknown error"}`);
+	return {
+		installed: [skillSelector ?? spec.cliSpec],
+		engine: "skills-cli"
+	};
+}
+async function installNatively(spec, skillSelector, opts) {
+	const io = opts.io ?? {};
+	const source = spec.source;
+	const stage = mkdtempSync(join(tmpdir(), "zidane-skill-install-"));
+	try {
+		const fetchedInto = join(stage, "fetched");
+		mkdirSync(fetchedInto, { recursive: true });
+		let provenance;
+		try {
+			provenance = (await fetchInstallSource(source, fetchedInto, io, opts.onProgress)).provenance;
+		} catch (err) {
+			rethrowAsSkillError(err);
+		}
+		let candidateRoot = fetchedInto;
+		let fallbackName = source.kind === "github" ? source.repo : source.pkg;
+		if (source.kind === "github" && source.subdir) {
+			const rooted = resolveSubdirRoot(fetchedInto, source.subdir);
+			if (!rooted.ok) {
+				if (rooted.reason === "missing") throw new SkillInstallError("no-skill", `"${source.subdir}" is not a directory in ${source.owner}/${source.repo}.`);
+				throw new SkillInstallError("invalid-source", `Subdirectory "${source.subdir}" escapes the repository root${rooted.reason === "escape-symlink" ? " through a symlink" : ""}.`);
+			}
+			candidateRoot = rooted.dir;
+			fallbackName = basename(resolve(fetchedInto, source.subdir));
+		}
+		const candidates = listSkillCandidates(candidateRoot, fallbackName);
+		if (candidates.length === 0) throw new SkillInstallError("no-skill", `No skill found in ${opts.source} — no SKILL.md anywhere in the tree (searched ${CANDIDATE_WALK_MAX_DEPTH} levels deep).`);
+		let picked;
+		if (!skillSelector && opts.skills && opts.skills.length > 0) {
+			const byRel = /* @__PURE__ */ new Map();
+			for (const sel of opts.skills) {
+				const matches = candidates.filter((c) => c.name === sel || c.rel === sel);
+				if (matches.length === 0) throw new SkillInstallError("no-skill", `No skill named "${sel}" in ${opts.source}. Available: ${describeCandidates(candidates)}`, candidates.map((c) => c.rel));
+				if (matches.length > 1) throw new SkillInstallError("multiple-candidates", `"${sel}" is ambiguous in ${opts.source} — pick a path: ${matches.map((c) => c.rel).join(", ")}`, matches.map((c) => c.rel));
+				const match = matches[0];
+				byRel.set(match.rel, match);
+			}
+			picked = [...byRel.values()];
+		} else if (skillSelector) {
+			const matches = candidates.filter((c) => c.name === skillSelector || c.rel === skillSelector);
+			if (matches.length === 0) throw new SkillInstallError("no-skill", `No skill named "${skillSelector}" in ${opts.source}. Available: ${describeCandidates(candidates)}`, candidates.map((c) => c.rel));
+			if (matches.length > 1) throw new SkillInstallError("multiple-candidates", `"${skillSelector}" is ambiguous in ${opts.source} — pick a path: ${matches.map((c) => c.rel).join(", ")}`, matches.map((c) => c.rel));
+			picked = [matches[0]];
+		} else if (candidates.length > 1 && !opts.all) throw new SkillInstallError("multiple-candidates", `${opts.source} contains ${candidates.length} skills — pick one: ${describeCandidates(candidates)}`, candidates.map((c) => c.rel), await candidateDetails(candidates));
+		else picked = [...candidates];
+		const root = scopeRoot(opts);
+		const installed = [];
+		const skipped = [];
+		const failed = [];
+		let lastDir;
+		const batch = picked.length > 1;
+		const resolved = [];
+		const nameToRel = /* @__PURE__ */ new Map();
+		for (const candidate of picked) try {
+			const { name } = await validateSkillCandidate(candidate);
+			const conflict = nameToRel.get(name);
+			if (conflict !== void 0) {
+				failed.push(candidate.rel);
+				opts.onProgress?.(`skipping "${candidate.rel}" — name "${name}" conflicts with "${conflict}"`);
+				continue;
+			}
+			nameToRel.set(name, candidate.rel);
+			resolved.push({
+				candidate,
+				name
 			});
-			metadata[k] = String(v);
-			continue;
+		} catch (err) {
+			if (!batch) throw err;
+			failed.push(candidate.rel);
+			opts.onProgress?.(`skipping "${candidate.rel}" — ${errorMessage(err)}`);
 		}
-		metadata[k] = v;
-	}
-	else if (rawMetadata !== void 0) diagnostics.push({
-		severity: "warning",
-		code: "invalid-metadata-shape",
-		message: `Frontmatter "metadata" expected a map, got ${Array.isArray(rawMetadata) ? "array" : typeof rawMetadata}. Ignored.`,
-		field: "metadata"
-	});
-	const pathsField = takeString(frontmatter, "paths", diagnostics);
-	if (pathsField) {
-		metadata["zidane.paths"] = pathsField.split(COMMA_OR_SPACE_RE).filter(Boolean).join(",");
-		diagnostics.push({
-			severity: "warning",
-			code: "deprecated-top-level-field",
-			message: "`paths` is not a spec field and is deprecated — moved to `metadata[\"zidane.paths\"]`.",
-			field: "paths"
-		});
-	}
-	const modelField = takeString(frontmatter, "model", diagnostics);
-	if (modelField) {
-		metadata["zidane.model"] = modelField;
-		diagnostics.push({
-			severity: "warning",
-			code: "deprecated-top-level-field",
-			message: "`model` is not a spec field and is deprecated — moved to `metadata[\"zidane.model\"]`.",
-			field: "model"
-		});
-	}
-	const thinkingField = takeString(frontmatter, "thinking", diagnostics);
-	const effortField = thinkingField ? void 0 : takeString(frontmatter, "effort", diagnostics);
-	const legacyThinking = thinkingField ?? effortField;
-	if (legacyThinking) {
-		metadata["zidane.thinking"] = legacyThinking;
-		diagnostics.push({
-			severity: "warning",
-			code: "deprecated-top-level-field",
-			message: `\`${thinkingField ? "thinking" : "effort"}\` is not a spec field and is deprecated — moved to \`metadata["zidane.thinking"]\`.`,
-			field: thinkingField ? "thinking" : "effort"
+		for (const { candidate, name } of resolved) {
+			const targetDir = join(root, name);
+			const backupDir = `${targetDir}.zidane-backup`;
+			if (existsSync(targetDir) && !opts.overwrite) {
+				if (batch) {
+					skipped.push(name);
+					opts.onProgress?.(`skipping "${name}" — already installed`);
+					continue;
+				}
+				throw new SkillInstallError("exists", `Skill "${name}" is already installed at ${targetDir}. Overwrite to replace it.`);
+			}
+			mkdirSync(root, { recursive: true });
+			const hadPrevious = existsSync(targetDir);
+			if (hadPrevious) {
+				rmSync(backupDir, {
+					recursive: true,
+					force: true
+				});
+				renameSync(targetDir, backupDir);
+			}
+			try {
+				cpSync(candidate.dir, targetDir, {
+					recursive: true,
+					dereference: true
+				});
+				writeProvenance(targetDir, {
+					spec: opts.source,
+					...skillSelector ? { skill: skillSelector } : {},
+					scope: opts.scope,
+					provenance,
+					installedAt: Date.now()
+				});
+			} catch (err) {
+				rmSync(targetDir, {
+					recursive: true,
+					force: true
+				});
+				if (hadPrevious) renameSync(backupDir, targetDir);
+				throw new SkillInstallError("io-failed", `Writing ${targetDir} failed: ${errorMessage(err)}`);
+			}
+			rmSync(backupDir, {
+				recursive: true,
+				force: true
+			});
+			installed.push(name);
+			lastDir = targetDir;
+			if (batch) opts.onProgress?.(`installed "${name}" (${installed.length}/${resolved.length})`);
+		}
+		if (installed.length === 0 && skipped.length > 0) throw new SkillInstallError("exists", `All ${skipped.length} installable skills from ${opts.source} are already installed: ${skipped.join(", ")}. Overwrite to replace them.`);
+		if (installed.length === 0 && failed.length > 0) throw new SkillInstallError("validate-failed", `No skill from ${opts.source} was installable — invalid: ${failed.join(", ")}.`);
+		return {
+			installed,
+			...skipped.length > 0 ? { skipped } : {},
+			...failed.length > 0 ? { failed } : {},
+			...lastDir !== void 0 ? { dir: lastDir } : {},
+			engine: "native",
+			provenance
+		};
+	} finally {
+		rmSync(stage, {
+			recursive: true,
+			force: true
 		});
 	}
-	if (Object.keys(metadata).length > 0) config.metadata = metadata;
-	const allowedTools = takeStringOrArray(frontmatter, "allowed-tools", diagnostics);
-	if (allowedTools && allowedTools.length > 0) config.allowedTools = allowedTools;
-	if (diagnostics.length > 0) config.diagnostics = diagnostics;
-	return config;
 }
-const SKIP_DIRS = /* @__PURE__ */ new Set([
-	".git",
-	"node_modules",
-	".DS_Store",
-	"dist",
-	"build"
-]);
-function findSkillDirs(root, maxDepth = 4, _depth = 0) {
-	if (_depth > maxDepth) return [];
-	if (!existsSync(root) || !statSync(root).isDirectory()) return [];
-	const results = [];
+/** Provenance sidecar — lets a future update flow replay the recorded spec. */
+const SKILL_PROVENANCE_FILE = ".zidane-install.json";
+function writeProvenance(dir, data) {
+	writeFileSync(join(dir, SKILL_PROVENANCE_FILE), `${JSON.stringify(data, null, 2)}\n`);
+}
+/** Read a skill directory's install provenance, `null` for hand-authored skills. */
+function readSkillProvenance(dir) {
 	try {
-		for (const entry of readdirSync(root)) {
-			if (SKIP_DIRS.has(entry)) continue;
-			const entryPath = join(root, entry);
-			if (!statSync(entryPath).isDirectory()) continue;
-			const skillFile = join(entryPath, "SKILL.md");
-			if (existsSync(skillFile) && statSync(skillFile).isFile()) results.push(skillFile);
-			else results.push(...findSkillDirs(entryPath, maxDepth, _depth + 1));
-		}
-	} catch {}
-	return results;
+		const raw = JSON.parse(readFileSync(join(dir, SKILL_PROVENANCE_FILE), "utf8"));
+		return typeof raw.spec === "string" && raw.spec.length > 0 ? raw : null;
+	} catch {
+		return null;
+	}
 }
 /**
-* Return the default scan paths tagged by source. Project-scope paths come
-* first; their skills therefore win on name collisions against user-scope
-* skills (first-found wins in discovery).
+* Native-install target root: the `<prefix>/skills` flavor of the
+* project/user convention (`~/.zidane/skills`, `<gitRoot>/.zidane/skills`).
+* The `.agents/skills` siblings stay read-only for us — they belong to
+* the cross-agent ecosystem (and the skills.sh CLI writes there).
 */
-function getDefaultScanPaths() {
-	const home = homedir();
-	const cwd = process.cwd();
-	return [
-		{
-			path: join(cwd, ".agents", "skills"),
-			source: "project"
-		},
-		{
-			path: join(cwd, ".zidane", "skills"),
-			source: "project"
-		},
-		{
-			path: join(home, ".agents", "skills"),
-			source: "user"
-		},
-		{
-			path: join(home, ".zidane", "skills"),
-			source: "user"
-		}
-	];
+function scopeRoot(opts) {
+	const root = projectUserPaths({
+		subPath: "skills",
+		...opts.cwd ? { cwd: opts.cwd } : {},
+		...opts.home ? { home: opts.home } : {},
+		...opts.prefix ? { prefix: opts.prefix } : {}
+	}).find((r) => r.source === opts.scope && r.path.includes(`.${(opts.prefix ?? ".zidane").replace(/^\./, "")}`));
+	if (!root) throw new SkillInstallError("io-failed", `No ${opts.scope} skills root resolved.`);
+	return root.path;
+}
+function sanitizeName(raw) {
+	const cleaned = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+	return cleaned.length > 0 ? cleaned : "skill";
 }
+//#endregion
+//#region src/skills/interpolate.ts
+/** Regex to match !`command` patterns in skill instructions */
+const SHELL_INTERPOLATION_RE = /!`([^`]+)`/g;
 /**
-* Infer a source tag for a user-provided scan path.
-* Paths under `$HOME` are treated as 'user'; everything else as 'project'.
+* Replace every !\`command\` pattern with a static placeholder, without
+* executing anything. Used when shell interpolation is disabled
+* (`SkillsConfig.allowShellInterpolation: false`): skill content can be
+* third-party input, and running its embedded commands on activation
+* bypasses the allowed-tools gate.
 */
-function inferSource(path) {
-	return path.startsWith(homedir()) ? "user" : "project";
+function stripShellInterpolations(instructions) {
+	return instructions.replace(SHELL_INTERPOLATION_RE, "[shell interpolation disabled]");
 }
 /**
-* Discover skills from sourced filesystem paths.
-* Each path is scanned for subdirectories containing SKILL.md.
-* Earlier paths have higher priority (first-found wins on name collision).
+* Interpolate shell commands in skill instructions.
 *
-* `signal` is checked between each `parseSkillFile` so a rapid `cwd` switch
-* in the host (TUI / GUI) can stop a long scan without leaking I/O. Aborts
-* reject with the signal's `reason` (or a default `AbortError`) — same shape
-* `AbortSignal.throwIfAborted()` produces in modern runtimes.
+* Runs each !\`command\` through the execution context and replaces
+* the placeholder with the command's stdout. If a command fails,
+* the placeholder is replaced with an error message (and
+* `options.onFailure` is notified when provided).
+*
+* @param instructions - Raw skill instructions with potential !\`command\` patterns
+* @param execution - The execution context to run commands in
+* @param handle - The active execution handle
+* @returns Instructions with all !\`command\` patterns replaced by output
 */
-async function discoverSkills(paths, signal) {
-	const skillsByName = /* @__PURE__ */ new Map();
-	for (const { path: scanPath, source } of paths) {
-		signal?.throwIfAborted?.();
-		const skillFiles = findSkillDirs(resolve(scanPath));
-		for (const file of skillFiles) {
-			signal?.throwIfAborted?.();
-			const skill = await parseSkillFile(file, { source });
-			if (!skill) continue;
-			if (skillsByName.has(skill.name)) {
-				const existing = skillsByName.get(skill.name);
-				const diag = {
-					severity: "warning",
-					code: "name-collision-shadowed",
-					message: `A skill with name "${skill.name}" was also found at ${file} (source: ${source}); shadowed by ${existing.location} (source: ${existing.source}).`
-				};
-				existing.diagnostics = [...existing.diagnostics ?? [], diag];
+async function interpolateShellCommands(instructions, execution, handle, options = {}) {
+	const matches = [...instructions.matchAll(SHELL_INTERPOLATION_RE)];
+	if (matches.length === 0) return instructions;
+	const replacements = [];
+	for (const match of matches) {
+		const command = match[1];
+		const index = match.index;
+		const length = match[0].length;
+		if (options.approve) {
+			let approved = false;
+			try {
+				approved = await options.approve(command);
+			} catch {
+				approved = false;
+			}
+			if (!approved) {
+				const placeholder = "[shell interpolation not approved]";
+				options.onFailure?.(command, placeholder);
+				replacements.push({
+					index,
+					length,
+					output: placeholder
+				});
 				continue;
 			}
-			skillsByName.set(skill.name, skill);
+		}
+		try {
+			const result = await execution.exec(handle, command, { timeout: 30 });
+			if (result.exitCode === 0) replacements.push({
+				index,
+				length,
+				output: result.stdout.trim()
+			});
+			else {
+				const placeholder = `[command failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}]`;
+				options.onFailure?.(command, placeholder);
+				replacements.push({
+					index,
+					length,
+					output: placeholder
+				});
+			}
+		} catch (err) {
+			const placeholder = `[command error: ${errorMessage(err)}]`;
+			options.onFailure?.(command, placeholder);
+			replacements.push({
+				index,
+				length,
+				output: placeholder
+			});
 		}
 	}
-	return [...skillsByName.values()];
+	let result = instructions;
+	for (let i = replacements.length - 1; i >= 0; i--) {
+		const { index, length, output } = replacements[i];
+		result = result.slice(0, index) + output + result.slice(index + length);
+	}
+	return result;
 }
 //#endregion
 //#region src/skills/writer.ts
@@ -1549,7 +1941,19 @@ async function resolveSkills(config) {
 	}
 	const diskSkills = await discoverSkills(sourcedPaths);
 	const skillsByName = /* @__PURE__ */ new Map();
-	for (const entry of config.catalog ?? []) skillsByName.set(entry.name, { ...entry });
+	for (const entry of config.catalog ?? []) {
+		const winner = { ...entry };
+		const shadowed = skillsByName.get(entry.name);
+		if (shadowed) {
+			const diag = {
+				severity: "warning",
+				code: "name-collision-shadowed",
+				message: `A skill with name "${entry.name}" was also supplied in the catalog by ${shadowed.location ?? "(catalog)"} (source: ${shadowed.source ?? "inline"}); shadowed by ${winner.location ?? "(catalog)"} (source: ${winner.source ?? "inline"}).`
+			};
+			winner.diagnostics = [...winner.diagnostics ?? [], diag];
+		}
+		skillsByName.set(entry.name, winner);
+	}
 	for (const skill of diskSkills) {
 		const existing = skillsByName.get(skill.name);
 		if (existing) {
@@ -1586,6 +1990,26 @@ async function resolveSkills(config) {
 	};
 }
 //#endregion
-export { validateSkillName as A, stripShellInterpolations as C, validateResourcePath as D, parseAllowedToolPattern as E, findGitRoot as M, validateResourcePathReal as O, interpolateShellCommands as S, matchesAllowedTool as T, lastLine as _, getDefaultScanPaths as a, resolveSubdirRoot as b, parseSkillFile as c, installAllowedToolsGate as d, createSkillActivationState as f, fetchInstallSource as g, defaultWhich as h, discoverSkills as i, projectUserPaths as j, validateSkillForWrite as k, buildCatalog as l, defaultExec as m, writeSkillToDisk as n, inferSource as o, InstallSourceError as p, writeSkillsToDisk as r, parseFrontmatter as s, resolveSkills as t, IMPLICITLY_ALLOWED_SKILL_TOOLS as u, parseInstallSource as v, isToolAllowedByUnion as w, escapeXml as x, resolveNpmVersion as y };
+//#region src/skills/index.ts
+/**
+* Define an inline skill configuration.
+*
+* Strict-validates at author-time — throws if the config would be rejected by
+* `writeSkillToDisk` or the spec. Source defaults to `'inline'`.
+*/
+function defineSkill(config) {
+	const normalized = {
+		...config,
+		source: config.source ?? "inline"
+	};
+	const result = validateSkillForWrite(normalized);
+	if (!result.valid) {
+		const summary = result.errors.map((e) => `  - [${e.code}] ${e.message}`).join("\n");
+		throw new Error(`Invalid skill "${normalized.name}":\n${summary}`);
+	}
+	return normalized;
+}
+//#endregion
+export { createSkillActivationState as A, inferSource as C, escapeXml as D, buildCatalog as E, validateResourcePathReal as F, validateSkillForWrite as I, validateSkillName as L, matchesAllowedTool as M, parseAllowedToolPattern as N, IMPLICITLY_ALLOWED_SKILL_TOOLS as O, validateResourcePath as P, projectUserPaths as R, getDefaultScanPaths as S, parseSkillFile as T, lastLine as _, interpolateShellCommands as a, resolveSubdirRoot as b, SkillInstallError as c, parseSkillInstallSpec as d, readSkillProvenance as f, fetchInstallSource as g, defaultWhich as h, writeSkillsToDisk as i, isToolAllowedByUnion as j, installAllowedToolsGate as k, installSkillFromSpec as l, defaultExec as m, resolveSkills as n, stripShellInterpolations as o, InstallSourceError as p, writeSkillToDisk as r, SKILL_PROVENANCE_FILE as s, defineSkill as t, listSkillCandidates as u, parseInstallSource as v, parseFrontmatter as w, discoverSkills as x, resolveNpmVersion as y, findGitRoot as z };
 
-//# sourceMappingURL=resolve-CZJxds85.js.map
+//# sourceMappingURL=skills-Cp9vnBwd.js.map