skills 1.7.1 → 1.7.3

package/dist/cli.mjs

@@ -7,7 +7,7 @@ import { esm_default } from "./_chunks/libs/simple-git.mjs";
 import { xdgConfig } from "./_chunks/libs/xdg-basedir.mjs";
 import { require_dist } from "./_chunks/libs/@vercel/detect-agent.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
-import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
+import { basename, dirname, extname, isAbsolute, join, normalize, posix, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { stripVTControlCharacters } from "node:util";
 import { createWriteStream } from "node:fs";
@@ -17,7 +17,7 @@ import * as readline from "readline";
 import { Writable } from "stream";
 import { promisify } from "util";
 import { execFile, spawn, spawnSync } from "child_process";
-import { access, chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, symlink, writeFile } from "fs/promises";
+import { access, chmod, cp, glob, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, symlink, writeFile } from "fs/promises";
 import { parse, stringify } from "yaml";
 import { createHash } from "crypto";
 import { cp as cp$1, mkdir as mkdir$1, mkdtemp as mkdtemp$1, readFile as readFile$1, rm as rm$1, stat as stat$1, writeFile as writeFile$1 } from "node:fs/promises";
@@ -1015,7 +1015,7 @@ async function cleanupTempDir(dir) {
 	});
 }
 function parseFrontmatter(raw) {
-	const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	const match = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
 	if (!match) return {
 		data: {},
 		content: raw
@@ -1112,14 +1112,13 @@ async function readLocalLock(cwd) {
 async function writeLocalLock(lock, cwd) {
 	const lockDir = cwd || process.cwd();
 	const lockPath = getLocalLockPath(lockDir);
-	const sortedSkills = {};
-	for (const key of Object.keys(lock.skills).sort()) {
+	const sortedSkills = Object.fromEntries(Object.keys(lock.skills).sort().map((key) => {
 		const entry = lock.skills[key];
-		sortedSkills[key] = entry.sourceType === "local" ? {
+		return [key, entry.sourceType === "local" ? {
 			...entry,
 			source: getPortableLocalSource(entry.source, lockDir)
-		} : entry;
-	}
+		} : entry];
+	}));
 	const sorted = {
 		version: lock.version,
 		skills: sortedSkills
@@ -1165,12 +1164,15 @@ async function collectFiles(baseDir, currentDir, results) {
 }
 async function addSkillToLocalLock(skillName, entry, cwd) {
 	const lock = await readLocalLock(cwd);
-	lock.skills[skillName] = entry;
+	lock.skills = {
+		...lock.skills,
+		[skillName]: entry
+	};
 	await writeLocalLock(lock, cwd);
 }
 async function removeSkillFromLocalLock(skillName, cwd) {
 	const lock = await readLocalLock(cwd);
-	if (!(skillName in lock.skills)) return false;
+	if (!Object.hasOwn(lock.skills, skillName)) return false;
 	delete lock.skills[skillName];
 	await writeLocalLock(lock, cwd);
 	return true;
@@ -1572,7 +1574,7 @@ const agents = {
 		name: "codex",
 		displayName: "Codex",
 		skillsDir: ".agents/skills",
-		globalSkillsDir: join(codexHome, "skills"),
+		globalSkillsDir: join(home, ".agents", "skills"),
 		detectInstalled: async () => {
 			return existsSync(codexHome) || existsSync("/etc/codex");
 		}
@@ -1692,8 +1694,8 @@ const agents = {
 	fx: {
 		name: "fx",
 		displayName: "fx",
-		skillsDir: ".fx/skills",
-		globalSkillsDir: join(home, ".fx/skills"),
+		skillsDir: ".agents/skills",
+		globalSkillsDir: join(home, ".agents/skills"),
 		detectInstalled: async () => {
 			return existsSync(join(home, ".fx"));
 		}
@@ -2316,26 +2318,34 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 				mode: "copy"
 			};
 		}
-		if (pathsOverlap(skill.path, canonicalDir)) return {
+		const sourceIsCanonical = resolve(skill.path) === resolve(canonicalDir);
+		if (!sourceIsCanonical && pathsOverlap(skill.path, canonicalDir)) return {
 			success: true,
 			path: canonicalDir,
 			canonicalPath: canonicalDir,
-			mode: "symlink",
+			mode: installMode,
 			skipped: true
 		};
-		await cleanAndCreateDirectory(canonicalDir);
-		await copyDirectory(skill.path, canonicalDir, agentType);
+		if (!sourceIsCanonical) if (installMode === "link") {
+			if (!await createSymlink(skill.path, canonicalDir)) {
+				await cleanAndCreateDirectory(canonicalDir);
+				await copyDirectory(skill.path, canonicalDir, agentType);
+			}
+		} else {
+			await cleanAndCreateDirectory(canonicalDir);
+			await copyDirectory(skill.path, canonicalDir, agentType);
+		}
 		if (isGlobal && isUniversalAgent(agentType)) return {
 			success: true,
 			path: canonicalDir,
 			canonicalPath: canonicalDir,
-			mode: "symlink"
+			mode: installMode
 		};
 		if (shouldSkipProjectAgentSymlink(agentType, isGlobal, cwd, options.createMissingAgentRoot ?? false)) return {
 			success: true,
 			path: canonicalDir,
 			canonicalPath: canonicalDir,
-			mode: "symlink",
+			mode: installMode,
 			skipped: true,
 			skipReason: "missing-agent-project-directory"
 		};
@@ -2346,7 +2356,7 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 				success: true,
 				path: agentDir,
 				canonicalPath: canonicalDir,
-				mode: "symlink",
+				mode: installMode,
 				symlinkFailed: true
 			};
 		}
@@ -2354,7 +2364,7 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 			success: true,
 			path: agentDir,
 			canonicalPath: canonicalDir,
-			mode: "symlink"
+			mode: installMode
 		};
 	} catch (error) {
 		return {
@@ -4172,7 +4182,7 @@ async function tryBlobInstall(ownerRepo, options = {}) {
 		tree
 	};
 }
-var version$1 = "1.7.1";
+var version$1 = "1.7.3";
 const NOTION_API_VERSION = "2026-03-11";
 const NTN_TIMEOUT_MS = 3e4;
 const NTN_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
@@ -4376,18 +4386,18 @@ async function fetchNotionSkillDirectory(pageId, options = {}) {
 }
 async function prepareNotionSkillSource(pageId, options = {}) {
 	const download = options.download ?? downloadNotionDirectory;
-	const spinner$4 = spinner();
-	spinner$4.start("Fetching Notion skill with ntn…");
+	const spinner$5 = spinner();
+	spinner$5.start("Fetching Notion skill with ntn…");
 	try {
 		const [directory, workspace] = await Promise.all([fetchNotionSkillDirectory(pageId, { runNtn: options.runNtn }), fetchNotionWorkspaceName({ runNtn: options.runNtn })]);
 		const downloaded = await download(directory.url);
-		spinner$4.stop(`Downloaded skill from Notion${inWorkspace(workspace)}`);
+		spinner$5.stop(`Downloaded skill from Notion${inWorkspace(workspace)}`);
 		return {
 			rootDir: downloaded.rootDir,
 			tempDir: downloaded.tempDir
 		};
 	} catch (error) {
-		spinner$4.stop(import_picocolors.default.red("Failed to prepare Notion skill"));
+		spinner$5.stop(import_picocolors.default.red("Failed to prepare Notion skill"));
 		throw error;
 	}
 }
@@ -4411,17 +4421,17 @@ function printAvailablePacks(packs) {
 	}
 }
 async function prepareNotionPackSource(options = {}) {
-	const spinner$5 = spinner();
-	spinner$5.start("Fetching Notion packs with ntn…");
+	const spinner$6 = spinner();
+	spinner$6.start("Fetching Notion packs with ntn…");
 	let packs;
 	let workspace = null;
 	try {
 		[packs, workspace] = await Promise.all([fetchNotionPacks({ runNtn: options.runNtn }), fetchNotionWorkspaceName({ runNtn: options.runNtn })]);
 	} catch (error) {
-		spinner$5.stop(import_picocolors.default.red("Failed to load Notion packs"));
+		spinner$6.stop(import_picocolors.default.red("Failed to load Notion packs"));
 		throw error;
 	}
-	spinner$5.stop(`Found ${import_picocolors.default.green(packs.length)} Notion pack${packs.length === 1 ? "" : "s"}${inWorkspace(workspace)}`);
+	spinner$6.stop(`Found ${import_picocolors.default.green(packs.length)} Notion pack${packs.length === 1 ? "" : "s"}${inWorkspace(workspace)}`);
 	if (packs.length === 0) throw new Error("Notion returned no packs for the authenticated workspace");
 	if (options.list) {
 		printAvailablePacks(packs);
@@ -4460,7 +4470,7 @@ async function prepareNotionPackSource(options = {}) {
 	const download = options.download ?? downloadNotionDirectory;
 	const discover = options.discover ?? discoverSkills;
 	let skillCount = 0;
-	spinner$5.start("Preparing selected Notion packs…");
+	spinner$6.start("Preparing selected Notion packs…");
 	try {
 		await mkdir$1(packsDir, { recursive: true });
 		for (const [index, pack] of selectedPacks.entries()) {
@@ -4501,7 +4511,7 @@ async function prepareNotionPackSource(options = {}) {
 			metadata: { pluginRoot: "./packs" },
 			plugins: manifestPlugins
 		}, null, 2)}\n`, "utf8");
-		spinner$5.stop(`Prepared ${import_picocolors.default.green(selectedPacks.length)} Notion pack${selectedPacks.length === 1 ? "" : "s"} with ${import_picocolors.default.green(skillCount)} skill${skillCount === 1 ? "" : "s"}`);
+		spinner$6.stop(`Prepared ${import_picocolors.default.green(selectedPacks.length)} Notion pack${selectedPacks.length === 1 ? "" : "s"} with ${import_picocolors.default.green(skillCount)} skill${skillCount === 1 ? "" : "s"}`);
 		return {
 			rootDir: stagingDir,
 			tempDir: stagingDir,
@@ -4509,7 +4519,7 @@ async function prepareNotionPackSource(options = {}) {
 			skillCount
 		};
 	} catch (error) {
-		spinner$5.stop(import_picocolors.default.red("Failed to prepare Notion packs"));
+		spinner$6.stop(import_picocolors.default.red("Failed to prepare Notion packs"));
 		await cleanupTempDir(stagingDir).catch(() => {});
 		throw error;
 	}
@@ -4685,7 +4695,8 @@ async function promptForAgents(message, choices) {
 	const defaultValues = [
 		"claude-code",
 		"opencode",
-		"codex"
+		"codex",
+		"grok"
 	].filter((a) => validAgents.includes(a));
 	let initialValues = [];
 	if (lastSelected && lastSelected.length > 0) initialValues = lastSelected.filter((a) => validAgents.includes(a));
@@ -5048,6 +5059,182 @@ async function handleWellKnownSkills(source, url, options, spinner) {
 	await promptForFindSkills(options, targetAgents);
 	return true;
 }
+async function resolveSkills(parsed, options, spinner) {
+	const { includeInternal } = options;
+	let skills;
+	let blobResult = null;
+	let tempDir = null;
+	try {
+		if (parsed.type === "local") {
+			spinner.start("Discovering skills…");
+			skills = await discoverSkills(parsed.localPath, parsed.subpath, {
+				includeInternal,
+				fullDepth: options.fullDepth
+			});
+		} else if (parsed.type === "well-known" || parsed.type === "download") {
+			spinner.start("Downloading source...");
+			const downloaded = await downloadSource(parsed.url);
+			tempDir = downloaded.tempDir;
+			spinner.stop(`Downloaded ${downloaded.kind === "skill-md" ? "SKILL.md file" : "archive"}`);
+			spinner.start("Discovering skills...");
+			skills = await discoverSkills(downloaded.rootDir, parsed.subpath, {
+				includeInternal,
+				fullDepth: options.fullDepth
+			});
+		} else if (parsed.type === "github" && !options.fullDepth) {
+			let attemptedBlobInstall = false;
+			const BLOB_ALLOWED_OWNERS = [
+				"vercel",
+				"vercel-labs",
+				"heygen-com",
+				"remotion-dev"
+			];
+			const ownerRepo = getOwnerRepo(parsed);
+			const owner = ownerRepo?.split("/")[0]?.toLowerCase();
+			const isSelfHostedRepo = !!ownerRepo && Object.hasOwn(BLOB_ALLOWED_REPOS, ownerRepo.toLowerCase());
+			if (ownerRepo && owner && (isSelfHostedRepo || BLOB_ALLOWED_OWNERS.includes(owner))) {
+				attemptedBlobInstall = true;
+				spinner.start("Fetching skills…");
+				blobResult = await tryBlobInstall(ownerRepo, {
+					subpath: parsed.subpath,
+					skillFilter: parsed.skillFilter,
+					ref: parsed.ref,
+					getToken: getGitHubToken,
+					includeInternal
+				});
+			}
+			if (blobResult) {
+				skills = blobResult.skills;
+				spinner.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
+			} else {
+				if (attemptedBlobInstall) spinner.message("Cloning repository…");
+				else spinner.start("Cloning repository…");
+				tempDir = await cloneRepo(parsed.url, parsed.ref);
+				spinner.stop("Repository cloned");
+				spinner.start("Discovering skills…");
+				skills = await discoverSkills(tempDir, parsed.subpath, {
+					includeInternal,
+					fullDepth: options.fullDepth
+				});
+			}
+		} else {
+			spinner.start("Cloning repository…");
+			tempDir = await cloneRepo(parsed.url, parsed.ref);
+			spinner.stop("Repository cloned");
+			spinner.start("Discovering skills…");
+			skills = await discoverSkills(tempDir, parsed.subpath, {
+				includeInternal,
+				fullDepth: options.fullDepth
+			});
+		}
+	} catch (error) {
+		await cleanup(tempDir);
+		throw error;
+	}
+	return {
+		skills,
+		tempDir,
+		blobResult
+	};
+}
+async function installToTargets(resolved, skills, targets, options) {
+	const results = [];
+	for (const skill of skills) for (const target of targets) {
+		const { agent, subagent } = target;
+		const installOptions = {
+			global: options.global,
+			mode: options.mode,
+			eveSubagent: subagent,
+			createMissingAgentRoot: options.createMissingAgentRoot(agent)
+		};
+		let result;
+		if (resolved.blobResult && "files" in skill) {
+			const blobSkill = skill;
+			result = await installBlobSkillForAgent({
+				installName: blobSkill.name,
+				files: blobSkill.files
+			}, agent, installOptions);
+		} else result = await installSkillForAgent(skill, agent, installOptions);
+		results.push({
+			skill: getSkillDisplayName(skill),
+			agent: targetDisplayName(target),
+			pluginName: skill.pluginName,
+			...result
+		});
+	}
+	return results;
+}
+function getSkillRepoPaths(resolved, skills) {
+	const { tempDir, blobResult } = resolved;
+	const skillFiles = {};
+	for (const skill of skills) if (blobResult && "repoPath" in skill) skillFiles[skill.name] = skill.repoPath;
+	else if (tempDir && skill.path === tempDir) skillFiles[skill.name] = "SKILL.md";
+	else if (tempDir && skill.path.startsWith(tempDir + sep)) skillFiles[skill.name] = skill.path.slice(tempDir.length + 1).split(sep).join("/") + "/SKILL.md";
+	return skillFiles;
+}
+function getProjectLockSource(parsed) {
+	return getLockSource(parsed.url, getOwnerRepo(parsed)) || parsed.url;
+}
+function projectLockEntry(parsed, skillPath, computedHash) {
+	const sourceUrl = getProjectLockSourceUrl(parsed.type, parsed.url);
+	return {
+		source: getProjectLockSource(parsed),
+		...sourceUrl && { sourceUrl },
+		ref: parsed.ref,
+		sourceType: parsed.type,
+		...skillPath && { skillPath },
+		computedHash
+	};
+}
+async function installFromSource(parsed, options) {
+	const spinner$4 = spinner();
+	let resolved = null;
+	try {
+		resolved = await resolveSkills(parsed, { includeInternal: options.skills.length > 0 }, spinner$4);
+		let selected = options.skills.length > 0 ? filterSkills(resolved.skills, options.skills) : resolved.skills;
+		if (selected.length === 0) {
+			spinner$4.stop(import_picocolors.default.red("No matching skills found"));
+			return {
+				installed: [],
+				failed: [],
+				error: "No matching skills found"
+			};
+		}
+		spinner$4.stop(`Found ${import_picocolors.default.green(selected.length)} skill${selected.length > 1 ? "s" : ""}`);
+		if (options.select) selected = await options.select(selected);
+		const results = await installToTargets(resolved, selected, options.agents.map((agent) => ({ agent })), {
+			global: false,
+			mode: "symlink",
+			createMissingAgentRoot: () => true
+		});
+		const installed = new Set(results.filter((r) => r.success).map((r) => r.skill));
+		const repoPaths = getSkillRepoPaths(resolved, selected);
+		for (const skill of selected) {
+			if (!installed.has(getSkillDisplayName(skill))) continue;
+			const entry = projectLockEntry(parsed, repoPaths[skill.name], await sourceSkillHash(skill));
+			await addSkillToLocalLock(skill.name, {
+				...entry,
+				...options.via && { via: options.via }
+			});
+		}
+		return {
+			installed: [...installed],
+			failed: results.filter((r) => !r.success).map((r) => `${r.skill} → ${r.agent}: ${r.error}`)
+		};
+	} catch (error) {
+		spinner$4.stop(import_picocolors.default.red("Installation failed"));
+		return {
+			installed: [],
+			failed: [],
+			error: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		await cleanup(resolved?.tempDir ?? null);
+	}
+}
+function sourceSkillHash(skill) {
+	return "snapshotHash" in skill ? Promise.resolve(skill.snapshotHash) : computeSkillFolderHash(skill.path);
+}
 async function runAdd(args, options = {}) {
 	const source = args[0];
 	let installTipShown = false;
@@ -5162,8 +5349,6 @@ async function runAdd(args, options = {}) {
 			if (!options.skill.includes(parsed.skillFilter)) options.skill.push(parsed.skillFilter);
 		}
 		const includeInternal = !!(options.skill && options.skill.length > 0 && !options.skill.includes("*"));
-		let skills;
-		let blobResult = null;
 		if (parsed.type === "local") {
 			spinner$3.start("Validating local path…");
 			if (!existsSync(parsed.localPath)) {
@@ -5172,67 +5357,13 @@ async function runAdd(args, options = {}) {
 				emitJsonAndExit(1, `Local path does not exist: ${parsed.localPath}`);
 			}
 			spinner$3.stop("Local path validated");
-			spinner$3.start("Discovering skills…");
-			skills = await discoverSkills(parsed.localPath, parsed.subpath, {
-				includeInternal,
-				fullDepth: options.fullDepth
-			});
-		} else if (parsed.type === "well-known" || parsed.type === "download") {
-			spinner$3.start("Downloading source...");
-			const downloaded = await downloadSource(parsed.url);
-			tempDir = downloaded.tempDir;
-			spinner$3.stop(`Downloaded ${downloaded.kind === "skill-md" ? "SKILL.md file" : "archive"}`);
-			spinner$3.start("Discovering skills...");
-			skills = await discoverSkills(downloaded.rootDir, parsed.subpath, {
-				includeInternal,
-				fullDepth: options.fullDepth
-			});
-		} else if (parsed.type === "github" && !options.fullDepth) {
-			let attemptedBlobInstall = false;
-			const BLOB_ALLOWED_OWNERS = [
-				"vercel",
-				"vercel-labs",
-				"heygen-com",
-				"remotion-dev"
-			];
-			const ownerRepo = getOwnerRepo(parsed);
-			const owner = ownerRepo?.split("/")[0]?.toLowerCase();
-			const isSelfHostedRepo = !!ownerRepo && Object.hasOwn(BLOB_ALLOWED_REPOS, ownerRepo.toLowerCase());
-			if (ownerRepo && owner && (isSelfHostedRepo || BLOB_ALLOWED_OWNERS.includes(owner))) {
-				attemptedBlobInstall = true;
-				spinner$3.start("Fetching skills…");
-				blobResult = await tryBlobInstall(ownerRepo, {
-					subpath: parsed.subpath,
-					skillFilter: parsed.skillFilter,
-					ref: parsed.ref,
-					getToken: getGitHubToken,
-					includeInternal
-				});
-			}
-			if (blobResult) {
-				skills = blobResult.skills;
-				spinner$3.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
-			} else {
-				if (attemptedBlobInstall) spinner$3.message("Cloning repository…");
-				else spinner$3.start("Cloning repository…");
-				tempDir = await cloneRepo(parsed.url, parsed.ref);
-				spinner$3.stop("Repository cloned");
-				spinner$3.start("Discovering skills…");
-				skills = await discoverSkills(tempDir, parsed.subpath, {
-					includeInternal,
-					fullDepth: options.fullDepth
-				});
-			}
-		} else {
-			spinner$3.start("Cloning repository…");
-			tempDir = await cloneRepo(parsed.url, parsed.ref);
-			spinner$3.stop("Repository cloned");
-			spinner$3.start("Discovering skills…");
-			skills = await discoverSkills(tempDir, parsed.subpath, {
-				includeInternal,
-				fullDepth: options.fullDepth
-			});
 		}
+		const resolved = await resolveSkills(parsed, {
+			includeInternal,
+			fullDepth: options.fullDepth
+		}, spinner$3);
+		const { skills, blobResult } = resolved;
+		tempDir = resolved.tempDir ?? tempDir;
 		if (skills.length === 0) {
 			spinner$3.stop(import_picocolors.default.red("No skills found"));
 			outro(import_picocolors.default.red("No valid skills found. Skills require a SKILL.md with name and description."));
@@ -5554,47 +5685,19 @@ async function runAdd(args, options = {}) {
 			}
 		}
 		spinner$3.start("Installing skills…");
-		const results = [];
-		for (const skill of selectedSkills) for (const target of installTargets) {
-			const { agent, subagent } = target;
-			let result;
-			if (blobResult && "files" in skill) {
-				const blobSkill = skill;
-				result = await installBlobSkillForAgent({
-					installName: blobSkill.name,
-					files: blobSkill.files
-				}, agent, {
-					global: installGlobally,
-					mode: installMode,
-					eveSubagent: subagent,
-					createMissingAgentRoot: explicitlySelectedAgents.has(agent)
-				});
-			} else result = await installSkillForAgent(skill, agent, {
-				global: installGlobally,
-				mode: installMode,
-				eveSubagent: subagent,
-				createMissingAgentRoot: explicitlySelectedAgents.has(agent)
-			});
-			results.push({
-				skill: getSkillDisplayName(skill),
-				agent: targetDisplayName(target),
-				pluginName: skill.pluginName,
-				...result
-			});
-		}
+		const results = await installToTargets(resolved, selectedSkills, installTargets, {
+			global: installGlobally,
+			mode: installMode,
+			createMissingAgentRoot: (agent) => explicitlySelectedAgents.has(agent)
+		});
 		spinner$3.stop("Installation complete");
 		console.log();
 		const successful = results.filter((r) => r.success);
 		const failed = results.filter((r) => !r.success);
 		const successfulSkillNames = new Set(successful.map((r) => r.skill));
-		const skillFiles = {};
-		for (const skill of selectedSkills) if (blobResult && "repoPath" in skill) skillFiles[skill.name] = skill.repoPath;
-		else if (tempDir && skill.path === tempDir) skillFiles[skill.name] = "SKILL.md";
-		else if (tempDir && skill.path.startsWith(tempDir + sep)) skillFiles[skill.name] = skill.path.slice(tempDir.length + 1).split(sep).join("/") + "/SKILL.md";
-		else continue;
+		const skillFiles = getSkillRepoPaths(resolved, selectedSkills);
 		const normalizedSource = directDownload ? null : getOwnerRepo(parsed);
 		const lockSource = directDownload ? null : getLockSource(parsed.url, normalizedSource);
-		const projectLockSourceUrl = directDownload ? void 0 : getProjectLockSourceUrl(parsed.type, parsed.url);
 		if (normalizedSource) if (parseOwnerRepo(normalizedSource)) {
 			if (await repoPrivacyPromise === false) track({
 				event: "install",
@@ -5619,8 +5722,7 @@ async function runAdd(args, options = {}) {
 			const skillDisplayName = getSkillDisplayName(skill);
 			if (!successfulSkillNames.has(skillDisplayName)) continue;
 			try {
-				const computedHash = blobResult && "snapshotHash" in skill ? skill.snapshotHash : await computeSkillFolderHash(skill.path);
-				installedSkillHashes.set(skillDisplayName, computedHash);
+				installedSkillHashes.set(skillDisplayName, await sourceSkillHash(skill));
 			} catch {}
 		}
 		if (successful.length > 0 && installGlobally && (normalizedSource || parsed.type === "local" && !directDownload)) {
@@ -5666,12 +5768,7 @@ async function runAdd(args, options = {}) {
 					if (computedHash === void 0) continue;
 					const skillPathValue = skillFiles[skill.name];
 					await addSkillToLocalLock(skill.name, {
-						source: lockSource || parsed.url,
-						...projectLockSourceUrl && { sourceUrl: projectLockSourceUrl },
-						ref: parsed.ref,
-						sourceType: parsed.type,
-						...skillPathValue && { skillPath: skillPathValue },
-						computedHash,
+						...projectLockEntry(parsed, skillPathValue, computedHash),
 						...recordSubagents && { subagents: eveSubagents }
 					}, cwd);
 				} catch {}
@@ -6173,76 +6270,402 @@ ${DIM$3}  2) npx skills add <owner/repo@skill>${RESET$3}`;
 	else console.log(`${DIM$3}Discover more skills at${RESET$3} ${TEXT$2}https://skills.sh${RESET$3}`);
 	console.log();
 }
+const NPM_PREFIX = "npm:";
+const REMOTE_SOURCE_TYPES = /* @__PURE__ */ new Set([
+	"github",
+	"gitlab",
+	"git"
+]);
+function isSkillsFieldEntry(value) {
+	if (typeof value === "string") return true;
+	if (!value || typeof value !== "object" || !("source" in value)) return false;
+	if (typeof value.source !== "string") return false;
+	const skills = "skills" in value ? value.skills : void 0;
+	const ref = "ref" in value ? value.ref : void 0;
+	return (skills === void 0 || Array.isArray(skills) && skills.every((s) => typeof s === "string")) && (ref === void 0 || typeof ref === "string");
+}
+function parseSkillsField(entries, declarer) {
+	const parsed = {
+		npm: [],
+		remote: [],
+		errors: []
+	};
+	for (const raw of entries) {
+		if (!isSkillsFieldEntry(raw)) {
+			parsed.errors.push(`${declarer}: invalid "skills" entry ${JSON.stringify(raw)}`);
+			continue;
+		}
+		const { source, skills = [], ref } = typeof raw === "string" ? { source: raw } : raw;
+		if (!source.startsWith(NPM_PREFIX)) {
+			const remote = parseSource(source);
+			if (!REMOTE_SOURCE_TYPES.has(remote.type)) parsed.errors.push(`${declarer}: "${source}" is not a git source`);
+			else if (ref !== void 0 && remote.ref !== void 0) parsed.errors.push(`${declarer}: "${source}" already has a ref; remove "ref"`);
+			else parsed.remote.push({
+				parsed: {
+					...remote,
+					ref: ref ?? remote.ref
+				},
+				skills: remote.skillFilter ? [...skills, remote.skillFilter] : skills
+			});
+		} else if (ref !== void 0) parsed.errors.push(`${declarer}: "ref" cannot be used with "${source}"`);
+		else parsed.npm.push({
+			package: source.slice(4),
+			skills
+		});
+	}
+	return parsed;
+}
 const isCancelled = (value) => typeof value === "symbol";
+function matchesSkill(skill, patterns) {
+	return patterns.some((pattern) => {
+		const hash = pattern.indexOf("#");
+		const packagePattern = hash === -1 ? pattern : pattern.slice(0, hash);
+		const skillPattern = hash === -1 ? "**" : pattern.slice(hash + 1);
+		return posix.matchesGlob(skill.packageName, packagePattern) && posix.matchesGlob(sanitizeName(skill.name), skillPattern);
+	});
+}
+function allowedByFilters(skill, { include, exclude }) {
+	return (!include?.length || matchesSkill(skill, include)) && !(exclude?.length && matchesSkill(skill, exclude));
+}
 function shortenPath$1(fullPath, cwd) {
 	const home = homedir();
 	if (fullPath === home || fullPath.startsWith(home + sep)) return "~" + fullPath.slice(home.length);
 	if (fullPath === cwd || fullPath.startsWith(cwd + sep)) return "." + fullPath.slice(cwd.length);
 	return fullPath;
 }
-async function discoverNodeModuleSkills(cwd) {
-	const nodeModulesDir = join(cwd, "node_modules");
-	const skills = [];
-	let topNames;
+async function readPackageJson(dir) {
 	try {
-		topNames = await readdir(nodeModulesDir);
+		return JSON.parse(await readFile(join(dir, "package.json"), "utf-8"));
 	} catch {
-		return skills;
-	}
-	const processPackageDir = async (pkgDir, packageName) => {
-		const rootSkill = await parseSkillMd(join(pkgDir, "SKILL.md"));
-		if (rootSkill) {
-			skills.push({
-				...rootSkill,
-				packageName
+		return null;
+	}
+}
+async function discoverPackageSkills(pkgDir, packageName, depth) {
+	const pkg = await readPackageJson(pkgDir);
+	if (!pkg) return [];
+	const rootSkill = await hasSkillMd(pkgDir) ? await parseSkillMd(join(pkgDir, "SKILL.md")) : null;
+	if (rootSkill) return [{
+		...rootSkill,
+		packageName,
+		packageVersion: pkg.version,
+		skillPath: "SKILL.md",
+		depth
+	}];
+	const skills = [];
+	for (const dir of ["skills", "dist/skills"]) for (const name of await readdir(join(pkgDir, dir)).catch(() => [])) {
+		const skillDir = join(pkgDir, dir, name);
+		if (!await hasSkillMd(skillDir)) continue;
+		const skill = await parseSkillMd(join(skillDir, "SKILL.md"));
+		if (skill) skills.push({
+			...skill,
+			packageName,
+			packageVersion: pkg.version,
+			skillPath: `${dir}/${name}/SKILL.md`,
+			depth
+		});
+	}
+	return skills;
+}
+function findInstalledPackage(from, name) {
+	for (let dir = from;; dir = dirname(dir)) {
+		const candidate = join(dir, "node_modules", name);
+		if (existsSync(join(candidate, "package.json"))) return candidate;
+		if (dirname(dir) === dir) return void 0;
+	}
+}
+function remoteAllowsSkill(request, name, options) {
+	return request.declarers.some((packageName) => allowedByFilters({
+		name,
+		packageName
+	}, options));
+}
+function filterRemoteRequests(requests, options) {
+	return requests.flatMap((request) => {
+		const declarers = request.declarers.filter((name) => (!options.include?.length || options.include.some((p) => posix.matchesGlob(name, p.split("#")[0]))) && !options.exclude?.some((p) => !p.includes("#") && posix.matchesGlob(name, p)));
+		if (declarers.length === 0) return [];
+		const filtered = {
+			...request,
+			via: declarers[0],
+			declarers
+		};
+		if (request.skills.length === 0) return [filtered];
+		const skills = request.skills.filter((name) => remoteAllowsSkill(filtered, name, options));
+		return skills.length > 0 ? [{
+			...filtered,
+			skills
+		}] : [];
+	});
+}
+function requestsLockedSkill(request, name, entry) {
+	return isFromRequest(entry, request) && (request.skills.length === 0 || request.skills.some((selected) => sanitizeName(selected) === sanitizeName(name) || selected === posix.basename(posix.dirname(entry.skillPath ?? ""))));
+}
+const DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+async function findWorkspacePackages(cwd, pkg) {
+	const patterns = [...Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages ?? []];
+	try {
+		const pnpm = parse(await readFile(join(cwd, "pnpm-workspace.yaml"), "utf-8"));
+		if (pnpm && typeof pnpm === "object" && "packages" in pnpm && Array.isArray(pnpm.packages)) patterns.push(...pnpm.packages.filter((p) => typeof p === "string"));
+	} catch {}
+	const negated = patterns.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
+	const included = patterns.filter((p) => !p.startsWith("!"));
+	const dirs = /* @__PURE__ */ new Set();
+	for await (const file of glob(included.map((p) => posix.join(p, "package.json")), {
+		cwd,
+		exclude: (path) => basename(path) === "node_modules"
+	})) {
+		const dir = dirname(file).split(sep).join("/");
+		if (dir !== "." && !negated.some((n) => posix.matchesGlob(dir, n))) dirs.add(join(cwd, dir));
+	}
+	return [...dirs].sort();
+}
+async function discoverNodeModuleSkills(cwd, recursive) {
+	const warnings = [];
+	const errors = [];
+	const remote = /* @__PURE__ */ new Map();
+	const pkg = await readPackageJson(cwd);
+	if (!pkg) return {
+		skills: [],
+		remote: [],
+		warnings,
+		errors
+	};
+	const skills = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = async (found) => {
+		for (const skill of found) {
+			const key = await realpath(skill.path).catch(() => skill.path);
+			if (seen.has(key)) continue;
+			seen.add(key);
+			skills.push(skill);
+		}
+	};
+	const projects = [{
+		name: ".",
+		dir: cwd,
+		pkg,
+		depth: 0
+	}];
+	for (const dir of recursive ? await findWorkspacePackages(cwd, pkg) : []) {
+		const workspacePkg = await readPackageJson(dir);
+		const name = workspacePkg?.name ?? relative(cwd, dir).split(sep).join("/");
+		if (workspacePkg) projects.push({
+			name,
+			dir,
+			pkg: workspacePkg,
+			depth: 1
+		});
+	}
+	const declarers = [];
+	for (const project of projects) {
+		const installed = [...new Set(DEPENDENCY_FIELDS.flatMap((field) => Object.keys(project.pkg[field] ?? {})))].flatMap((name) => {
+			const dir = findInstalledPackage(project.dir, name);
+			return dir ? [{
+				name,
+				dir
+			}] : [];
+		});
+		await add((await Promise.all(installed.map(({ name, dir }) => discoverPackageSkills(dir, name, project.depth)))).flat());
+		declarers.push({
+			name: project.name,
+			dir: project.dir,
+			depth: project.depth
+		}, ...installed.map(({ name, dir }) => ({
+			name,
+			dir,
+			depth: project.depth + 1
+		})));
+	}
+	const visited = /* @__PURE__ */ new Set();
+	for (const declarer of declarers) {
+		const dir = await realpath(declarer.dir).catch(() => null);
+		if (!dir || visited.has(dir)) continue;
+		visited.add(dir);
+		const problems = declarer.name === "." ? errors : warnings;
+		const field = (await readPackageJson(dir))?.skills;
+		if (field === void 0) continue;
+		if (!Array.isArray(field)) {
+			if (problems === errors) errors.push("package.json: \"skills\" must be an array");
+			continue;
+		}
+		const parsed = parseSkillsField(field, declarer.name);
+		problems.push(...parsed.errors);
+		for (const request of parsed.remote) {
+			const { url, ref, subpath } = request.parsed;
+			const key = JSON.stringify([
+				url,
+				ref,
+				subpath,
+				request.skills
+			]);
+			const existing = remote.get(key);
+			if (existing) {
+				if (!existing.declarers.includes(declarer.name)) existing.declarers.push(declarer.name);
+			} else remote.set(key, {
+				...request,
+				via: declarer.name,
+				declarers: [declarer.name]
 			});
-			return;
 		}
-		const searchDirs = [
-			pkgDir,
-			join(pkgDir, "skills"),
-			join(pkgDir, ".agents", "skills")
-		];
-		for (const searchDir of searchDirs) try {
-			const entries = await readdir(searchDir);
-			for (const name of entries) {
-				const skillDir = join(searchDir, name);
-				try {
-					if (!(await stat(skillDir)).isDirectory()) continue;
-				} catch {
-					continue;
-				}
-				const skill = await parseSkillMd(join(skillDir, "SKILL.md"));
-				if (skill) skills.push({
-					...skill,
-					packageName
-				});
+		for (const request of parsed.npm) {
+			const target = findInstalledPackage(dir, request.package);
+			if (!target) {
+				problems.push(`${declarer.name}: cannot resolve "npm:${request.package}"; is it a dependency?`);
+				continue;
 			}
-		} catch {}
+			await add((await discoverPackageSkills(target, request.package, declarer.depth)).filter((skill) => request.skills.length === 0 || request.skills.includes(basename(skill.path)) || request.skills.includes(sanitizeName(skill.name))).map((skill) => ({
+				...skill,
+				via: declarer.name
+			})));
+			declarers.push({
+				name: request.package,
+				dir: target,
+				depth: declarer.depth + 1
+			});
+		}
+	}
+	return {
+		skills,
+		remote: [...remote.values()],
+		warnings,
+		errors
 	};
-	await Promise.all(topNames.map(async (name) => {
-		if (name.startsWith(".")) return;
-		const fullPath = join(nodeModulesDir, name);
-		try {
-			if (!(await stat(fullPath)).isDirectory()) return;
-		} catch {
-			return;
+}
+function isUnderNodeModules(path) {
+	return path.split(sep).includes("node_modules");
+}
+function installedBySync(entry) {
+	return entry?.sourceType === "node_modules" || entry?.via !== void 0;
+}
+async function foreignDestination(dest, canonicalDir, lockEntry, cwd) {
+	let stats;
+	try {
+		stats = await lstat(dest);
+	} catch {
+		return null;
+	}
+	if (stats.isSymbolicLink()) {
+		const target = resolve(dirname(dest), await readlink(dest));
+		if (isUnderNodeModules(target) || target === canonicalDir) return null;
+		return `${shortenPath$1(dest, cwd)} is a symlink to ${shortenPath$1(target, cwd)}`;
+	}
+	if (installedBySync(lockEntry)) return null;
+	return `${shortenPath$1(dest, cwd)} already exists and was not installed by sync`;
+}
+async function linksIntoNodeModules(path) {
+	try {
+		if (!(await lstat(path)).isSymbolicLink()) return false;
+		return isUnderNodeModules(resolve(dirname(path), await readlink(path)));
+	} catch {
+		return false;
+	}
+}
+async function pruneStaleSkills(cwd, keep, keepRemote, lock, dryRun) {
+	const canonicalBase = getCanonicalSkillsDir(false, cwd);
+	const lockKeys = /* @__PURE__ */ new Map();
+	const explicit = /* @__PURE__ */ new Set();
+	for (const [key, entry] of Object.entries(lock.skills)) {
+		const remote = entry.sourceType !== "node_modules";
+		if (installedBySync(entry) && !(remote && keepRemote(entry, key))) lockKeys.set(sanitizeName(key), key);
+		else explicit.add(sanitizeName(key));
+	}
+	const candidates = new Set(lockKeys.keys());
+	for (const name of await readdir(canonicalBase).catch(() => [])) if (await linksIntoNodeModules(join(canonicalBase, name))) candidates.add(name);
+	const stale = [...candidates].filter((name) => !keep.has(name) && !explicit.has(name)).sort();
+	if (dryRun || stale.length === 0) return stale;
+	const allAgents = Object.keys(agents);
+	for (const name of stale) {
+		const canonicalDir = join(canonicalBase, name);
+		const key = lockKeys.get(name);
+		const lockEntry = key ? lock.skills[key] : void 0;
+		const destinations = /* @__PURE__ */ new Set([canonicalDir, ...allAgents.map((agent) => getInstallPath(name, agent, { cwd }))]);
+		for (const dest of destinations) if (!await foreignDestination(dest, canonicalDir, lockEntry, cwd)) await rm(dest, {
+			recursive: true,
+			force: true
+		});
+		if (key) delete lock.skills[key];
+	}
+	await writeLocalLock(lock, cwd);
+	return stale;
+}
+async function blockedReason(name, targetAgents, lockEntry, cwd) {
+	if (lockEntry && !installedBySync(lockEntry)) return `installed with \`skills add\` from ${lockEntry.source}`;
+	const canonicalDir = getCanonicalPath(name, { cwd });
+	const destinations = /* @__PURE__ */ new Set([canonicalDir, ...targetAgents.map((agent) => getInstallPath(name, agent, { cwd }))]);
+	for (const dest of destinations) {
+		const reason = await foreignDestination(dest, canonicalDir, lockEntry, cwd);
+		if (reason) return reason;
+	}
+	return null;
+}
+async function resolveConflicts(skills, targetAgents, lockSkills, cwd) {
+	const lockBySanitizedName = new Map(Object.entries(lockSkills).map(([name, entry]) => [sanitizeName(name), entry]));
+	const byName = Map.groupBy(skills, (skill) => sanitizeName(skill.name));
+	const install = [];
+	const skipped = [];
+	for (const [name, all] of byName) {
+		const depth = Math.min(...all.map((c) => c.depth));
+		const candidates = all.filter((c) => c.depth === depth);
+		for (const skill of all.filter((c) => c.depth !== depth)) skipped.push({
+			skill,
+			reason: `${candidates[0].packageName} is closer to the project`
+		});
+		if (candidates.length > 1) {
+			const packages = candidates.map((c) => c.packageName).join(", ");
+			for (const skill of candidates) skipped.push({
+				skill,
+				reason: `shipped by ${packages}; drop this one with --exclude ${skill.packageName}#${name}`
+			});
+			continue;
 		}
-		if (name.startsWith("@")) try {
-			const scopeNames = await readdir(fullPath);
-			await Promise.all(scopeNames.map(async (scopedName) => {
-				const scopedPath = join(fullPath, scopedName);
-				try {
-					if (!(await stat(scopedPath)).isDirectory()) return;
-				} catch {
-					return;
-				}
-				await processPackageDir(scopedPath, `${name}/${scopedName}`);
-			}));
-		} catch {}
-		else await processPackageDir(fullPath, name);
-	}));
-	return skills;
+		const skill = candidates[0];
+		const reason = await blockedReason(name, targetAgents, lockBySanitizedName.get(name), cwd);
+		if (reason) skipped.push({
+			skill,
+			reason
+		});
+		else install.push(skill);
+	}
+	return {
+		install,
+		skipped
+	};
+}
+async function promptForAgentChoice(choices, fallback) {
+	const universalAgents = getUniversalAgents();
+	const visibleUniversalAgents = getVisibleUniversalAgents();
+	const last = await getLastSelectedAgents().catch(() => void 0);
+	const remembered = choices.filter((a) => last?.includes(a));
+	const selected = await searchMultiselect({
+		message: "Which agents do you want to install to?",
+		items: choices.map((a) => ({
+			value: a,
+			label: agents[a].displayName,
+			hint: agents[a].skillsDir
+		})),
+		initialSelected: remembered.length > 0 ? remembered : fallback,
+		lockedSection: {
+			title: "Universal (.agents/skills)",
+			items: visibleUniversalAgents.map((a) => ({
+				value: a,
+				label: agents[a].displayName
+			})),
+			hiddenCount: universalAgents.length - visibleUniversalAgents.length
+		}
+	});
+	if (!isCancelled(selected)) await saveSelectedAgents(selected).catch(() => {});
+	return selected;
+}
+function isFromRequest(entry, request) {
+	return entry.via !== void 0 && entry.source === getProjectLockSource(request.parsed) && entry.ref === request.parsed.ref;
+}
+function isRemoteInstalled(request, lock, cwd) {
+	const installed = Object.entries(lock.skills).filter(([name, entry]) => isFromRequest(entry, request) && existsSync(getCanonicalPath(name, { cwd }))).map(([name]) => sanitizeName(name));
+	return request.skills.length === 0 ? installed.length > 0 : request.skills.every((name) => installed.includes(sanitizeName(name)));
 }
 async function runSync(args, options = {}) {
 	const cwd = process.cwd();
@@ -6259,50 +6682,54 @@ async function runSync(args, options = {}) {
 		}
 	}
 	console.log();
-	if (!agentResult.isAgent) intro(import_picocolors.default.bgCyan(import_picocolors.default.black(" skills experimental_sync ")));
+	if (!agentResult.isAgent) intro(import_picocolors.default.bgCyan(import_picocolors.default.black(" skills sync ")));
 	if (agentResult.isAgent) log.info(import_picocolors.default.bgCyan(import_picocolors.default.black(import_picocolors.default.bold(` ${agentResult.agent.name} `))) + " Agent detected — installing non-interactively");
 	const spinner$2 = spinner();
 	spinner$2.start("Scanning node_modules for skills…");
-	const discoveredSkills = await discoverNodeModuleSkills(cwd);
-	if (discoveredSkills.length === 0) {
-		spinner$2.stop(import_picocolors.default.yellow("No skills found"));
-		outro(import_picocolors.default.dim("No SKILL.md files found in node_modules."));
+	const discovery = await discoverNodeModuleSkills(cwd, options.recursive ?? false);
+	if (discovery.errors.length > 0) {
+		spinner$2.stop(import_picocolors.default.red("Invalid skills field"));
+		for (const error of discovery.errors) log.error(error);
+		outro(import_picocolors.default.red("Fix the \"skills\" field in package.json and run sync again."));
+		process.exitCode = 1;
+		return;
+	}
+	const discoveredSkills = discovery.skills.filter((skill) => allowedByFilters(skill, options));
+	const remote = filterRemoteRequests(discovery.remote, options);
+	spinner$2.stop(discoveredSkills.length === 0 ? import_picocolors.default.yellow("No skills found") : `Found ${import_picocolors.default.green(String(discoveredSkills.length))} skill${discoveredSkills.length > 1 ? "s" : ""} in node_modules`);
+	for (const warning of discovery.warnings) log.warn(warning);
+	const localLock = await readLocalLock(cwd);
+	if (options.cleanup !== false) {
+		const keep = new Set(discoveredSkills.map((skill) => sanitizeName(skill.name)));
+		const keepRemote = (entry, name) => options.remote === false || remote.some((r) => requestsLockedSkill(r, name, entry) && remoteAllowsSkill(r, name, options));
+		const stale = await pruneStaleSkills(cwd, keep, keepRemote, localLock, options.dryRun ?? false);
+		for (const name of stale) log.info(`${options.dryRun ? "Would remove" : "Removed"} ${import_picocolors.default.cyan(name)} ${import_picocolors.default.dim("(no longer provided by a dependency)")}`);
+	}
+	const remoteRequests = (options.remote === false ? [] : remote).filter((request) => !isRemoteInstalled(request, localLock, cwd));
+	const cachedRemoteSkills = [];
+	if (options.remote !== false) {
+		const shippedNames = new Set(discoveredSkills.map((skill) => sanitizeName(skill.name)));
+		for (const [name, entry] of Object.entries(localLock.skills)) {
+			if (shippedNames.has(sanitizeName(name))) continue;
+			if (!remote.some((request) => !remoteRequests.includes(request) && requestsLockedSkill(request, name, entry) && remoteAllowsSkill(request, name, options))) continue;
+			const skill = await parseSkillMd(join(getCanonicalPath(name, { cwd }), "SKILL.md"));
+			if (skill) cachedRemoteSkills.push({
+				skill,
+				source: entry.source
+			});
+		}
+	}
+	if (discoveredSkills.length === 0 && remoteRequests.length === 0 && cachedRemoteSkills.length === 0) {
+		outro(import_picocolors.default.dim("Nothing to sync."));
 		return;
 	}
-	spinner$2.stop(`Found ${import_picocolors.default.green(String(discoveredSkills.length))} skill${discoveredSkills.length > 1 ? "s" : ""} in node_modules`);
 	for (const skill of discoveredSkills) {
 		log.info(`${import_picocolors.default.cyan(skill.name)} ${import_picocolors.default.dim(`from ${skill.packageName}`)}`);
 		if (skill.description) log.message(import_picocolors.default.dim(`  ${skill.description}`));
 	}
-	const localLock = await readLocalLock(cwd);
-	const toInstall = [];
-	const upToDate = [];
-	if (options.force) {
-		toInstall.push(...discoveredSkills);
-		log.info(import_picocolors.default.dim("Force mode: reinstalling all skills"));
-	} else {
-		for (const skill of discoveredSkills) {
-			const existingEntry = localLock.skills[skill.name];
-			if (existingEntry) {
-				if (await computeSkillFolderHash(skill.path) === existingEntry.computedHash) {
-					upToDate.push(skill.name);
-					continue;
-				}
-			}
-			toInstall.push(skill);
-		}
-		if (upToDate.length > 0) log.info(import_picocolors.default.dim(`${upToDate.length} skill${upToDate.length !== 1 ? "s" : ""} already up to date`));
-		if (toInstall.length === 0) {
-			console.log();
-			outro(import_picocolors.default.green("All skills are up to date."));
-			return;
-		}
-	}
-	log.info(`${toInstall.length} skill${toInstall.length !== 1 ? "s" : ""} to install/update`);
 	let targetAgents;
 	const validAgents = Object.keys(agents);
 	const universalAgents = getUniversalAgents();
-	const visibleUniversalAgents = getVisibleUniversalAgents();
 	if (options.agent?.includes("*")) {
 		targetAgents = validAgents;
 		log.info(`Installing to all ${targetAgents.length} agents`);
@@ -6319,54 +6746,14 @@ async function runSync(args, options = {}) {
 		const installedAgents = await detectInstalledAgents();
 		const totalAgents = Object.keys(agents).length;
 		spinner$2.stop(`${totalAgents} agents`);
-		if (installedAgents.length === 0) if (options.yes) {
+		if (installedAgents.length === 0 && options.yes) {
 			targetAgents = universalAgents;
 			log.info("Installing to universal agents");
-		} else {
-			const selected = await searchMultiselect({
-				message: "Which agents do you want to install to?",
-				items: getNonUniversalAgents().map((a) => ({
-					value: a,
-					label: agents[a].displayName,
-					hint: agents[a].skillsDir
-				})),
-				initialSelected: [],
-				lockedSection: {
-					title: "Universal (.agents/skills)",
-					items: visibleUniversalAgents.map((a) => ({
-						value: a,
-						label: agents[a].displayName
-					})),
-					hiddenCount: universalAgents.length - visibleUniversalAgents.length
-				}
-			});
-			if (isCancelled(selected)) {
-				cancel("Sync cancelled");
-				process.exit(0);
-			}
-			targetAgents = selected;
-		}
-		else if (installedAgents.length === 1 || options.yes) {
+		} else if (installedAgents.length === 1 || options.yes) {
 			targetAgents = [...installedAgents];
 			for (const ua of universalAgents) if (!targetAgents.includes(ua)) targetAgents.push(ua);
 		} else {
-			const selected = await searchMultiselect({
-				message: "Which agents do you want to install to?",
-				items: getNonUniversalAgents().filter((a) => installedAgents.includes(a)).map((a) => ({
-					value: a,
-					label: agents[a].displayName,
-					hint: agents[a].skillsDir
-				})),
-				initialSelected: installedAgents.filter((a) => !universalAgents.includes(a)),
-				lockedSection: {
-					title: "Universal (.agents/skills)",
-					items: visibleUniversalAgents.map((a) => ({
-						value: a,
-						label: agents[a].displayName
-					})),
-					hiddenCount: universalAgents.length - visibleUniversalAgents.length
-				}
-			});
+			const selected = await promptForAgentChoice(getNonUniversalAgents().filter((a) => installedAgents.length === 0 || installedAgents.includes(a)), installedAgents.filter((a) => !universalAgents.includes(a)));
 			if (isCancelled(selected)) {
 				cancel("Sync cancelled");
 				process.exit(0);
@@ -6374,14 +6761,40 @@ async function runSync(args, options = {}) {
 			targetAgents = selected;
 		}
 	}
+	const { install: toInstall, skipped } = await resolveConflicts(discoveredSkills, targetAgents, localLock.skills, cwd);
+	for (const { skill, reason } of skipped) log.warn(`Skipped ${import_picocolors.default.cyan(skill.name)} ${import_picocolors.default.dim(`from ${skill.packageName}`)}: ${reason}`);
+	const cachedToInstall = [];
+	for (const cached of cachedRemoteSkills) {
+		const { skill } = cached;
+		const missing = targetAgents.filter((agent) => !existsSync(getInstallPath(skill.name, agent, { cwd })));
+		if (missing.length === 0) continue;
+		const reason = await blockedReason(skill.name, missing, localLock.skills[skill.name], cwd);
+		if (reason) log.warn(`Skipped ${import_picocolors.default.cyan(skill.name)}: ${reason}`);
+		else cachedToInstall.push({
+			...cached,
+			agents: missing
+		});
+	}
+	if (toInstall.length === 0 && remoteRequests.length === 0 && cachedToInstall.length === 0) {
+		console.log();
+		outro(import_picocolors.default.yellow("Nothing to sync."));
+		return;
+	}
+	const mode = options.copy ? "copy" : "link";
 	const summaryLines = [];
 	for (const skill of toInstall) {
-		const shortCanonical = shortenPath$1(getCanonicalPath(skill.name, { global: false }), cwd);
+		const canonicalPath = getCanonicalPath(skill.name, { cwd });
 		summaryLines.push(`${import_picocolors.default.cyan(skill.name)} ${import_picocolors.default.dim(`← ${skill.packageName}`)}`);
-		summaryLines.push(`  ${import_picocolors.default.dim(shortCanonical)}`);
+		summaryLines.push(`  ${import_picocolors.default.dim(`${shortenPath$1(canonicalPath, cwd)} ${mode === "link" ? "→" : "copied from"} ${shortenPath$1(skill.path, cwd)}`)}`);
 	}
+	for (const request of remoteRequests) summaryLines.push(`${import_picocolors.default.cyan(getProjectLockSource(request.parsed))} ${import_picocolors.default.dim(`← ${request.via} (remote)`)}`);
+	for (const { skill, source, agents: missing } of cachedToInstall) summaryLines.push(`${import_picocolors.default.cyan(skill.name)} ${import_picocolors.default.dim(`← ${source} (cached), link to ${missing.join(", ")}`)}`);
 	console.log();
 	note(summaryLines.join("\n"), "Sync Summary");
+	if (options.dryRun) {
+		outro(import_picocolors.default.dim("Dry run — nothing changed."));
+		return;
+	}
 	if (!options.yes) {
 		const confirmed = await confirm({ message: "Proceed with sync?" });
 		if (isCancel(confirmed) || !confirmed) {
@@ -6391,11 +6804,27 @@ async function runSync(args, options = {}) {
 	}
 	spinner$2.start("Syncing skills…");
 	const results = [];
+	for (const { skill, source, agents: missing } of cachedToInstall) for (const agent of missing) {
+		const result = await installSkillForAgent(skill, agent, {
+			cwd,
+			mode: "symlink",
+			createMissingAgentRoot: true
+		});
+		results.push({
+			skill: skill.name,
+			packageName: source,
+			agent: agents[agent].displayName,
+			success: result.success,
+			path: result.path,
+			canonicalPath: result.canonicalPath,
+			error: result.error
+		});
+	}
 	for (const skill of toInstall) for (const agent of targetAgents) {
 		const result = await installSkillForAgent(skill, agent, {
 			global: false,
 			cwd,
-			mode: "symlink"
+			mode: agent === "eve" ? "copy" : mode
 		});
 		results.push({
 			skill: skill.name,
@@ -6416,9 +6845,45 @@ async function runSync(args, options = {}) {
 		await addSkillToLocalLock(skill.name, {
 			source: skill.packageName,
 			sourceType: "node_modules",
+			skillPath: skill.skillPath,
+			...skill.packageVersion && { version: skill.packageVersion },
+			...skill.via && { via: skill.via },
 			computedHash
 		}, cwd);
 	} catch {}
+	const claimed = new Set(discoveredSkills.map((skill) => sanitizeName(skill.name)));
+	const lockEntryFor = (name) => Object.entries(localLock.skills).find(([key]) => sanitizeName(key) === name)?.[1];
+	for (const request of remoteRequests) {
+		const label = getProjectLockSource(request.parsed);
+		const result = await installFromSource(request.parsed, {
+			skills: request.skills,
+			agents: targetAgents,
+			via: request.via,
+			select: async (skills) => {
+				const selected = [];
+				for (const skill of skills) {
+					const name = sanitizeName(skill.name);
+					if (!remoteAllowsSkill(request, name, options)) continue;
+					const reason = claimed.has(name) ? "another source in this sync provides it" : await blockedReason(name, targetAgents, lockEntryFor(name), cwd);
+					if (reason) {
+						log.warn(`Skipped ${import_picocolors.default.cyan(name)} from ${label}: ${reason}`);
+						continue;
+					}
+					claimed.add(name);
+					selected.push(skill);
+				}
+				return selected;
+			}
+		});
+		if (result.error) {
+			log.error(`Failed to install from ${import_picocolors.default.cyan(label)}: ${result.error}`);
+			process.exitCode = 1;
+			continue;
+		}
+		if (result.installed.length > 0) log.success(`Installed ${result.installed.map((name) => import_picocolors.default.cyan(name)).join(", ")} from ${label}`);
+		for (const failure of result.failed) log.error(failure);
+		if (result.failed.length > 0) process.exitCode = 1;
+	}
 	console.log();
 	if (successful.length > 0) {
 		const bySkill = /* @__PURE__ */ new Map();
@@ -6430,7 +6895,7 @@ async function runSync(args, options = {}) {
 		const resultLines = [];
 		for (const [skillName, skillResults] of bySkill) {
 			const firstResult = skillResults[0];
-			const pkg = toInstall.find((s) => s.name === skillName)?.packageName;
+			const pkg = firstResult.packageName;
 			if (firstResult.canonicalPath) {
 				const shortPath = shortenPath$1(firstResult.canonicalPath, cwd);
 				resultLines.push(`${import_picocolors.default.green("✓")} ${skillName} ${import_picocolors.default.dim(`← ${pkg}`)}`);
@@ -6442,13 +6907,14 @@ async function runSync(args, options = {}) {
 		note(resultLines.join("\n"), title);
 	}
 	if (failed.length > 0) {
+		process.exitCode = 1;
 		console.log();
 		log.error(import_picocolors.default.red(`Failed to install ${failed.length}`));
 		for (const r of failed) log.message(`  ${import_picocolors.default.red("✗")} ${r.skill} → ${r.agent}: ${import_picocolors.default.dim(r.error)}`);
 	}
 	track({
 		event: "experimental_sync",
-		skillCount: String(toInstall.length),
+		skillCount: String(toInstall.length + cachedToInstall.length),
 		successCount: String(successfulSkillNames.size),
 		agents: targetAgents.join(",")
 	});
@@ -6457,21 +6923,23 @@ async function runSync(args, options = {}) {
 }
 function parseSyncOptions(args) {
 	const options = {};
-	for (let i = 0; i < args.length; i++) {
+	let i = 0;
+	const takeValues = () => {
+		const values = [];
+		while (args[i + 1] !== void 0 && !args[i + 1].startsWith("-")) values.push(args[++i]);
+		return values;
+	};
+	for (; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "-y" || arg === "--yes") options.yes = true;
-		else if (arg === "-f" || arg === "--force") options.force = true;
-		else if (arg === "-a" || arg === "--agent") {
-			options.agent = options.agent || [];
-			i++;
-			let nextArg = args[i];
-			while (i < args.length && nextArg && !nextArg.startsWith("-")) {
-				options.agent.push(nextArg);
-				i++;
-				nextArg = args[i];
-			}
-			i--;
-		}
+		else if (arg === "--copy") options.copy = true;
+		else if (arg === "--dry-run") options.dryRun = true;
+		else if (arg === "--no-cleanup") options.cleanup = false;
+		else if (arg === "--no-remote") options.remote = false;
+		else if (arg === "-r" || arg === "--recursive") options.recursive = true;
+		else if (arg === "-a" || arg === "--agent") options.agent = [...options.agent ?? [], ...takeValues()];
+		else if (arg === "--include") options.include = [...options.include ?? [], ...takeValues()];
+		else if (arg === "--exclude") options.exclude = [...options.exclude ?? [], ...takeValues()];
 	}
 	return { options };
 }
@@ -6568,14 +7036,27 @@ async function runInstallFromLock(args) {
 	}
 	const remoteCount = skillEntries.length - nodeModuleSkills.length;
 	if (remoteCount > 0) log.info(`Restoring ${import_picocolors.default.cyan(String(remoteCount))} skill${remoteCount !== 1 ? "s" : ""} from skills-lock.json into ${import_picocolors.default.dim(".agents/skills/")}`);
-	for (const [source, { skills }] of bySource) try {
-		await runAdd([source], {
-			skill: skills,
-			agent: universalAgentNames,
-			yes: true
+	for (const [source, { sourceType, skills }] of bySource) {
+		if (sourceType === "well-known") {
+			await runAdd([source], {
+				skill: skills,
+				agent: universalAgentNames,
+				yes: true
+			});
+			continue;
+		}
+		const result = await installFromSource(parseSource(source), {
+			skills,
+			agents: universalAgentNames
 		});
-	} catch (error) {
-		log.error(`Failed to install from ${import_picocolors.default.cyan(source)}: ${error instanceof Error ? error.message : "Unknown error"}`);
+		if (result.error) {
+			log.error(`Failed to install from ${import_picocolors.default.cyan(source)}: ${result.error}`);
+			process.exitCode = 1;
+			continue;
+		}
+		log.success(`Restored ${result.installed.map((name) => import_picocolors.default.cyan(name)).join(", ")}`);
+		for (const failure of result.failed) log.error(failure);
+		if (result.failed.length > 0) process.exitCode = 1;
 	}
 	if (nodeModuleSkills.length > 0) {
 		log.info(`${import_picocolors.default.cyan(String(nodeModuleSkills.length))} skill${nodeModuleSkills.length !== 1 ? "s" : ""} from node_modules`);
@@ -6739,14 +7220,18 @@ async function runList(args) {
 		console.log();
 	}
 }
-function resolveSkillsToRemove(requested, folderNames, lockKeys = []) {
+function resolveSkillsToRemove(requested, folderNames, lockKeys = [], sourceByKey = {}) {
 	const identityBySanitized = /* @__PURE__ */ new Map();
 	for (const folder of folderNames) identityBySanitized.set(sanitizeName(folder), folder);
 	for (const key of lockKeys) identityBySanitized.set(sanitizeName(key), key);
 	const matched = /* @__PURE__ */ new Set();
 	for (const name of requested) {
 		const hit = identityBySanitized.get(sanitizeName(name));
-		if (hit) matched.add(hit);
+		if (hit) {
+			matched.add(hit);
+			continue;
+		}
+		for (const key of lockKeys) if (sourceByKey[key] === name) matched.add(key);
 	}
 	return Array.from(matched);
 }
@@ -6794,9 +7279,11 @@ async function removeCommand(skillNames, options) {
 	}
 	const installedSkills = Array.from(skillNamesSet).sort();
 	spinner$1.stop(`Found ${installedSkills.length} unique installed skill(s)`);
-	const lockSkillsKeys = isGlobal ? Object.keys((await readSkillLock()).skills) : Object.keys((await readLocalLock(cwd)).skills);
+	const lockEntries = isGlobal ? (await readSkillLock()).skills : (await readLocalLock(cwd)).skills;
+	const lockSkillsKeys = Object.keys(lockEntries);
+	const sourceByKey = Object.fromEntries(lockSkillsKeys.map((key) => [key, lockEntries[key]?.source]));
 	const requestedSkills = options.all ? [...installedSkills, ...lockSkillsKeys] : skillNames;
-	const resolvedRequestedSkills = options.all || skillNames.length > 0 ? resolveSkillsToRemove(requestedSkills, installedSkills, lockSkillsKeys) : [];
+	const resolvedRequestedSkills = options.all || skillNames.length > 0 ? resolveSkillsToRemove(requestedSkills, installedSkills, lockSkillsKeys, sourceByKey) : [];
 	if (installedSkills.length === 0 && resolvedRequestedSkills.length === 0) {
 		outro(import_picocolors.default.yellow("No skills found to remove."));
 		return;
@@ -6993,7 +7480,7 @@ function normalizeSkillName(name) {
 function normalizeSkillPath(path) {
 	return path.replace(/\\/g, "/").replace(/\/+/g, "/");
 }
-function resolveSkillLocations(lockedSkillNames, lockSkills, discovered) {
+function resolveSkillLocations(lockedSkillNames, lockSkills, discovered, options = {}) {
 	const discoveredPaths = new Set(discovered.map((skill) => normalizeSkillPath(skill.skillPath)));
 	const pathsByName = /* @__PURE__ */ new Map();
 	for (const skill of discovered) {
@@ -7010,11 +7497,16 @@ function resolveSkillLocations(lockedSkillNames, lockSkills, discovered) {
 		if (!lockedPath) continue;
 		const normalizedLockedPath = normalizeSkillPath(lockedPath);
 		const candidates = [...pathsByName.get(normalizeSkillName(name)) ?? []];
+		const lockedPathStillExists = discoveredPaths.has(normalizedLockedPath);
+		if (lockedPathStillExists && options.exactPathDisambiguates) {
+			resolvedPaths.set(name, normalizedLockedPath);
+			continue;
+		}
 		if (candidates.length > 1) {
 			ambiguousSkills.push(name);
 			continue;
 		}
-		if (discoveredPaths.has(normalizedLockedPath)) {
+		if (lockedPathStillExists) {
 			resolvedPaths.set(name, normalizedLockedPath);
 			continue;
 		}
@@ -7173,8 +7665,8 @@ async function promptDeletions(source, deletedSkills, isGlobal, options) {
 		});
 	}
 }
-async function checkAndPromptForDeletions(source, allLockedForSource, lockSkills, isGlobal, options, discovered) {
-	const resolution = resolveSkillLocations(allLockedForSource, lockSkills, discovered);
+async function checkAndPromptForDeletions(source, allLockedForSource, lockSkills, isGlobal, options, discovered, locationOptions = {}) {
+	const resolution = resolveSkillLocations(allLockedForSource, lockSkills, discovered, locationOptions);
 	if (resolution.ambiguousSkills.length > 0) {
 		console.log();
 		console.log(`${DIM$1}Warning:${RESET$1} Multiple current paths match these skills from ${DIM$1}${source}${RESET$1}; skipping them rather than deleting or migrating the wrong skill:`);
@@ -7387,7 +7879,7 @@ async function updateGlobalSkills(options = {}) {
 				name: skill.name,
 				skillPath: join(relative(tempDir, skill.path), "SKILL.md").split(sep).join("/")
 			}));
-			const resolution = await checkAndPromptForDeletions(source, Object.entries(lock.skills).filter(([_, entry]) => entry.source === source && entry.ref === firstEntry.ref).map(([name, _]) => name), lock.skills, true, options, discoveredLocations);
+			const resolution = await checkAndPromptForDeletions(source, Object.entries(lock.skills).filter(([_, entry]) => entry.source === source && entry.ref === firstEntry.ref).map(([name, _]) => name), lock.skills, true, options, discoveredLocations, { exactPathDisambiguates: !shouldUseFullDepthForUpdate(firstEntry) });
 			const deletedSkillSet = new Set(resolution.deletedSkills);
 			for (const { name: skillName, entry } of itemsForSource) {
 				if (deletedSkillSet.has(skillName)) continue;
@@ -7595,7 +8087,7 @@ async function updateProjectSkills(options = {}) {
 				name: skill.name,
 				skillPath: join(relative(tempDir, skill.path), "SKILL.md").split(sep).join("/")
 			}));
-			const resolution = await checkAndPromptForDeletions(source, allLockedForSource, localLock.skills, false, options, discoveredLocations);
+			const resolution = await checkAndPromptForDeletions(source, allLockedForSource, localLock.skills, false, options, discoveredLocations, { exactPathDisambiguates: !shouldUseFullDepthForUpdate(firstEntry) });
 			deletedSkills = resolution.deletedSkills;
 			resolvedPaths = resolution.resolvedPaths;
 			for (const [name, skillPath] of resolution.resolvedPaths) try {
@@ -8160,7 +8652,7 @@ function showBanner() {
 	console.log();
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx skills experimental_install${RESET} ${DIM}Restore from skills-lock.json${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx skills init ${DIM}[name]${RESET}          ${DIM}Create a new skill${RESET}`);
-	console.log(`  ${DIM}$${RESET} ${TEXT}npx skills experimental_sync${RESET}    ${DIM}Sync skills from node_modules${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx skills sync${RESET}                 ${DIM}Sync skills from node_modules${RESET}`);
 	console.log();
 	console.log(`${DIM}try:${RESET} npx skills add vercel-labs/agent-skills`);
 	console.log();
@@ -8168,6 +8660,37 @@ function showBanner() {
 	console.log();
 }
 function showHelp() {
+	const examples = [
+		["skills add vercel-labs/agent-skills"],
+		["skills use vercel-labs/agent-skills@vercel-optimize | claude"],
+		["skills use vercel-labs/agent-skills --skill vercel-optimize --agent claude-code"],
+		["skills add vercel-labs/agent-skills -g"],
+		["skills add vercel-labs/agent-skills --agent claude-code cursor"],
+		["skills add vercel-labs/agent-skills --skill pr-review commit"],
+		["skills add vercel-labs/agent-skills --json -y", "JSON output"],
+		["skills remove", "interactive remove"],
+		["skills remove web-design", "remove by name"],
+		["skills rm --global frontend-design"],
+		["skills list", "list project skills"],
+		["skills ls -g", "list global skills"],
+		["skills ls -a claude-code", "filter by agent"],
+		["skills ls --json", "JSON output"],
+		["skills find", "interactive search"],
+		["skills find typescript", "search by keyword"],
+		["skills find react --owner vercel", "search within an owner"],
+		["skills update"],
+		["skills update my-skill", "update a single skill"],
+		["skills update -g", "update global skills only"],
+		["skills experimental_install", "restore from skills-lock.json"],
+		["skills init my-skill"],
+		["skills sync", "sync from node_modules"],
+		["skills sync -y", "sync without prompts"]
+	];
+	const exampleWidth = Math.max(...examples.filter(([, description]) => description).map(([command]) => command.length));
+	const formattedExamples = examples.map(([command, description]) => {
+		const comment = description ? `${" ".repeat(exampleWidth - command.length + 2)}${DIM}# ${description}${RESET}` : "";
+		return `  ${DIM}$${RESET} ${command}${comment}`;
+	}).join("\n");
 	console.log(`
 ${BOLD}Usage:${RESET} skills <command> [options]
 
@@ -8197,7 +8720,7 @@ ${BOLD}Update Options:${RESET}
 ${BOLD}Project:${RESET}
   experimental_install Restore skills from skills-lock.json
   init [name]          Initialize a skill (creates <name>/SKILL.md or ./SKILL.md)
-  experimental_sync    Sync skills from node_modules into agent directories
+  sync                 Sync skills from node_modules into agent directories (alias: experimental_sync)
 
 ${BOLD}Add Options:${RESET}
   -g, --global           Install skill globally (user-level) instead of project-level
@@ -8224,9 +8747,16 @@ ${BOLD}Remove Options:${RESET}
   -y, --yes              Skip confirmation prompts
   --all                  Remove every installed skill (-y implied). Do not combine with named skills.
   
-${BOLD}Experimental Sync Options:${RESET}
+${BOLD}Sync Options:${RESET}
   -a, --agent <agents>   Specify agents to install to (use '*' for all agents)
   -y, --yes              Skip confirmation prompts
+  --copy                 Copy skills instead of linking them to node_modules
+  --dry-run              Show what would change without changing anything
+  --no-cleanup           Keep skills whose package no longer ships them
+  --no-remote            Skip git sources listed in package.json skills fields
+  -r, --recursive        Also sync the dependencies of each workspace package
+  --include <patterns>   Only sync matching packages (<pkg>) or skills (<pkg>#<skill>)
+  --exclude <patterns>   Skip matching packages (<pkg>) or skills (<pkg>#<skill>)
 
 ${BOLD}List Options:${RESET}
   -g, --global           List global skills (default: project)
@@ -8238,30 +8768,7 @@ ${BOLD}Options:${RESET}
   --version, -v     Show version number
 
 ${BOLD}Examples:${RESET}
-  ${DIM}$${RESET} skills add vercel-labs/agent-skills
-  ${DIM}$${RESET} skills use vercel-labs/agent-skills@vercel-optimize | claude
-  ${DIM}$${RESET} skills use vercel-labs/agent-skills --skill vercel-optimize --agent claude-code
-  ${DIM}$${RESET} skills add vercel-labs/agent-skills -g
-  ${DIM}$${RESET} skills add vercel-labs/agent-skills --agent claude-code cursor
-  ${DIM}$${RESET} skills add vercel-labs/agent-skills --skill pr-review commit
-  ${DIM}$${RESET} skills add vercel-labs/agent-skills --json -y ${DIM}# JSON output${RESET}
-  ${DIM}$${RESET} skills remove                        ${DIM}# interactive remove${RESET}
-  ${DIM}$${RESET} skills remove web-design             ${DIM}# remove by name${RESET}
-  ${DIM}$${RESET} skills rm --global frontend-design
-  ${DIM}$${RESET} skills list                          ${DIM}# list project skills${RESET}
-  ${DIM}$${RESET} skills ls -g                         ${DIM}# list global skills${RESET}
-  ${DIM}$${RESET} skills ls -a claude-code             ${DIM}# filter by agent${RESET}
-  ${DIM}$${RESET} skills ls --json                      ${DIM}# JSON output${RESET}
-  ${DIM}$${RESET} skills find                          ${DIM}# interactive search${RESET}
-  ${DIM}$${RESET} skills find typescript               ${DIM}# search by keyword${RESET}
-  ${DIM}$${RESET} skills find react --owner vercel     ${DIM}# search within an owner${RESET}
-  ${DIM}$${RESET} skills update
-  ${DIM}$${RESET} skills update my-skill             ${DIM}# update a single skill${RESET}
-  ${DIM}$${RESET} skills update -g                    ${DIM}# update global skills only${RESET}
-  ${DIM}$${RESET} skills experimental_install            ${DIM}# restore from skills-lock.json${RESET}
-  ${DIM}$${RESET} skills init my-skill
-  ${DIM}$${RESET} skills experimental_sync              ${DIM}# sync from node_modules${RESET}
-  ${DIM}$${RESET} skills experimental_sync -y           ${DIM}# sync without prompts${RESET}
+${formattedExamples}
 
 Discover more skills at ${TEXT}https://skills.sh/${RESET}
 `);
@@ -8402,6 +8909,7 @@ async function main() {
 			await removeCommand(skills, removeOptions);
 			break;
 		}
+		case "sync":
 		case "experimental_sync": {
 			if (!inAgent) showLogo();
 			const { options: syncOptions } = parseSyncOptions(restArgs);