pruff-skills 1.11.0 → 1.12.1

package/README.md

@@ -142,7 +142,7 @@ npx pruff-skills add <skill> -g -a claude-code -y
 | `npx pruff-skills list`            | List installed skills (alias: `ls`)           |
 | `npx pruff-skills find [query]`    | Search the Pruff catalog interactively or by keyword |
 | `npx pruff-skills remove [skills]` | Remove installed skills from agents           |
-| `npx pruff-skills update [skills]` | Update installed skills to latest versions    |
+| `npx pruff-skills update [skills]` | Show what changed upstream (modified / new / deleted), then update only that |
 | `npx pruff-skills init [name]`     | Create a new `SKILL.md` template              |
 | `npx pruff-skills restore`         | Reinstall everything recorded in `skills-lock.json` |
 | `npx pruff-skills sync`            | Install skills found in `node_modules` into agent dirs |
@@ -155,6 +155,7 @@ Troubleshooting: if a command fails, run `npx pruff-skills doctor` and paste the
 npx pruff-skills list                 # list installed skills
 npx pruff-skills find logs            # search the catalog by keyword
 npx pruff-skills update -g            # update global skills
+npx pruff-skills update --dry-run     # show the plan, change nothing
 npx pruff-skills remove <skill>    # remove a skill
 ```
 

package/dist/cli.mjs

@@ -7,7 +7,7 @@ import "./_chunks/libs/@kwsites/promise-deferred.mjs";
 import { t as esm_default } from "./_chunks/libs/simple-git.mjs";
 import { t as xdgConfig } from "./_chunks/libs/xdg-basedir.mjs";
 import { t as require_dist } from "./_chunks/libs/@vercel/detect-agent.mjs";
-import { accessSync, chmodSync, constants, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "fs";
+import { accessSync, chmodSync, constants, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "fs";
 import { basename, delimiter, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { stripVTControlCharacters } from "node:util";
@@ -30,6 +30,7 @@ const PROBE_TIMEOUT_MS = 2500;
 const probeCache = /* @__PURE__ */ new Map();
 let currentStep = "start";
 let failure = null;
+let usageError = false;
 const tail = [];
 function setStep(step) {
 	currentStep = step;
@@ -40,9 +41,13 @@ function recordFailure(message) {
 		message
 	};
 }
+function markUsageError() {
+	usageError = true;
+}
 function resetDiagnosticsState() {
 	currentStep = "start";
 	failure = null;
+	usageError = false;
 	tail.length = 0;
 }
 function recordedFailure() {
@@ -333,7 +338,7 @@ async function withDiagnostics(command, args, fn) {
 	};
 	let printed = false;
 	const emit = (exitCode, error) => {
-		if (printed) return;
+		if (printed || usageError) return;
 		printed = true;
 		const message = error ?? recordedFailure()?.message ?? lastErrorLine(tail);
 		restore();
@@ -1041,6 +1046,14 @@ async function getPluginGroupings(basePath) {
 	} catch {}
 	return groupings;
 }
+const AGENTS_DIR$1 = ".agents";
+const SKILLS_SUBDIR = "skills";
+const INSTALL_EXCLUDED_FILES = new Set(["metadata.json"]);
+const INSTALL_EXCLUDED_DIRS = new Set([
+	".git",
+	"__pycache__",
+	"__pypackages__"
+]);
 const LOCAL_LOCK_FILE = "skills-lock.json";
 const CURRENT_VERSION$1 = 1;
 function getLocalLockPath(cwd) {
@@ -1077,8 +1090,14 @@ async function writeLocalLock(lock, cwd) {
 	await writeFile(lockPath, JSON.stringify(sorted, null, 2) + "\n", "utf-8");
 }
 async function computeSkillFolderHash(skillDir) {
+	return hashSkillFiles(skillDir, false);
+}
+async function computeSkillContentHash(skillDir) {
+	return hashSkillFiles(skillDir, true);
+}
+async function hashSkillFiles(skillDir, installedOnly) {
 	const files = [];
-	await collectFiles(skillDir, skillDir, files);
+	await collectFiles(skillDir, skillDir, files, installedOnly);
 	files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
 	const hash = createHash("sha256");
 	for (const file of files) {
@@ -1087,14 +1106,16 @@ async function computeSkillFolderHash(skillDir) {
 	}
 	return hash.digest("hex");
 }
-async function collectFiles(baseDir, currentDir, results) {
+async function collectFiles(baseDir, currentDir, results, installedOnly) {
 	const entries = await readdir(currentDir, { withFileTypes: true });
 	await Promise.all(entries.map(async (entry) => {
 		const fullPath = join(currentDir, entry.name);
 		if (entry.isDirectory()) {
 			if (entry.name === ".git" || entry.name === "node_modules") return;
-			await collectFiles(baseDir, fullPath, results);
+			if (installedOnly && INSTALL_EXCLUDED_DIRS.has(entry.name)) return;
+			await collectFiles(baseDir, fullPath, results, installedOnly);
 		} else if (entry.isFile()) {
+			if (installedOnly && INSTALL_EXCLUDED_FILES.has(entry.name)) return;
 			const content = await readFile(fullPath);
 			const relativePath = relative(baseDir, fullPath).split("\\").join("/");
 			results.push({
@@ -1109,6 +1130,13 @@ async function addSkillToLocalLock(skillName, entry, cwd) {
 	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;
+	delete lock.skills[skillName];
+	await writeLocalLock(lock, cwd);
+	return true;
+}
 function createEmptyLocalLock() {
 	return {
 		version: CURRENT_VERSION$1,
@@ -1972,8 +2000,6 @@ function getNonUniversalAgents() {
 function isUniversalAgent(type) {
 	return agents[type].skillsDir === ".agents/skills";
 }
-const AGENTS_DIR$1 = ".agents";
-const SKILLS_SUBDIR = "skills";
 function sanitizeName(name) {
 	return name.toLowerCase().replace(/[^a-z0-9._]+/g, "-").replace(/^[.\-]+|[.\-]+$/g, "").substring(0, 255) || "unnamed-skill";
 }
@@ -2152,15 +2178,9 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 		};
 	}
 }
-const EXCLUDE_FILES$1 = new Set(["metadata.json"]);
-const EXCLUDE_DIRS$1 = new Set([
-	".git",
-	"__pycache__",
-	"__pypackages__"
-]);
 const isExcluded$1 = (name, isDirectory = false) => {
-	if (EXCLUDE_FILES$1.has(name)) return true;
-	if (isDirectory && EXCLUDE_DIRS$1.has(name)) return true;
+	if (INSTALL_EXCLUDED_FILES.has(name)) return true;
+	if (isDirectory && INSTALL_EXCLUDED_DIRS.has(name)) return true;
 	return false;
 };
 async function copyDirectory(src, dest) {
@@ -3113,6 +3133,33 @@ async function dismissPrompt(promptKey) {
 	lock.dismissed[promptKey] = true;
 	await writeSkillLock(lock);
 }
+const DIVERGENT_HASH = "divergent";
+function findInstalledSkillDirs(skillName, cwd) {
+	const candidates = [getCanonicalPath(skillName, { cwd })];
+	for (const [type, config] of Object.entries(agents)) {
+		if (isUniversalAgent(type)) continue;
+		candidates.push(join(cwd, config.skillsDir, sanitizeName(skillName)));
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const dirs = [];
+	for (const dir of candidates) {
+		if (!existsSync(join(dir, "SKILL.md"))) continue;
+		let real = dir;
+		try {
+			real = realpathSync(dir);
+		} catch {}
+		if (seen.has(real)) continue;
+		seen.add(real);
+		dirs.push(dir);
+	}
+	return dirs;
+}
+async function hashInstalledSkill(skillName, cwd) {
+	const dirs = findInstalledSkillDirs(skillName, cwd);
+	if (dirs.length === 0) return null;
+	const hashes = new Set(await Promise.all(dirs.map((dir) => computeSkillContentHash(dir))));
+	return hashes.size === 1 ? [...hashes][0] : DIVERGENT_HASH;
+}
 const DOWNLOAD_BASE_URL = process.env.PRUFF_SKILLS_DOWNLOAD_URL || "";
 const FETCH_TIMEOUT = 1e4;
 function toSkillSlug(name) {
@@ -3791,6 +3838,7 @@ async function runAdd(args, options = {}) {
 		installTipShown = true;
 	};
 	if (!source) {
+		markUsageError();
 		console.log();
 		console.log(import_picocolors.default.bgRed(import_picocolors.default.white(import_picocolors.default.bold(" ERROR "))) + " " + import_picocolors.default.red("Missing required argument: source"));
 		console.log();
@@ -4255,12 +4303,14 @@ async function runAdd(args, options = {}) {
 				if (successfulSkillNames.has(skillDisplayName)) try {
 					const computedHash = blobResult && "snapshotHash" in skill ? skill.snapshotHash : await computeSkillFolderHash(skill.path);
 					const skillPathValue = skillFiles[skill.name];
+					const installedHash = await hashInstalledSkill(skill.name, cwd);
 					await addSkillToLocalLock(skill.name, {
 						source: lockSource || parsed.url,
 						ref: parsed.ref,
 						sourceType: parsed.type,
 						...skillPathValue && { skillPath: skillPathValue },
-						computedHash
+						computedHash,
+						...installedHash && installedHash !== DIVERGENT_HASH && { installedHash }
 					}, cwd);
 				} catch {}
 			}
@@ -4554,7 +4604,7 @@ async function updateAgents(options = {}) {
 			result.unchanged.push(name);
 			continue;
 		}
-		await writeFile(dest, content);
+		if (!options.dryRun) await writeFile(dest, content);
 		result.updated.push(name);
 	}
 	return result;
@@ -4756,10 +4806,10 @@ async function runRules(args) {
 	await addRules(names, options);
 }
 const execFileAsync$2 = promisify(execFile);
-const RESET$3 = "\x1B[0m";
-const BOLD$3 = "\x1B[1m";
-const DIM$3 = "\x1B[38;5;102m";
-const TEXT$2 = "\x1B[38;5;145m";
+const RESET$4 = "\x1B[0m";
+const BOLD$4 = "\x1B[1m";
+const DIM$4 = "\x1B[38;5;102m";
+const TEXT$3 = "\x1B[38;5;145m";
 const CYAN$1 = "\x1B[36m";
 const GREEN = "\x1B[32m";
 const MAGENTA = "\x1B[35m";
@@ -4850,10 +4900,10 @@ const MOVE_UP = (n) => `\x1b[${n}A`;
 const MOVE_TO_COL = (n) => `\x1b[${n}G`;
 function rowBadge(skill) {
 	const parts = [];
-	if (skill.category) parts.push(`${CYAN$1}${skill.category}${RESET$3}`);
-	if (skill.installed) parts.push(`${GREEN}installed${RESET$3}`);
+	if (skill.category) parts.push(`${CYAN$1}${skill.category}${RESET$4}`);
+	if (skill.installed) parts.push(`${GREEN}installed${RESET$4}`);
 	if (parts.length === 0) return "";
-	return ` ${DIM$3}[${RESET$3}${parts.join(`${DIM$3} · ${RESET$3}`)}${DIM$3}]${RESET$3}`;
+	return ` ${DIM$4}[${RESET$4}${parts.join(`${DIM$4} · ${RESET$4}`)}${DIM$4}]${RESET$4}`;
 }
 async function runSearchPrompt(kind, alreadyPicked = /* @__PURE__ */ new Set(), initialQuery = "") {
 	let results = [];
@@ -4871,33 +4921,33 @@ async function runSearchPrompt(kind, alreadyPicked = /* @__PURE__ */ new Set(),
 		if (lastRenderedLines > 0) process.stdout.write(MOVE_UP(lastRenderedLines) + MOVE_TO_COL(1));
 		process.stdout.write(CLEAR_DOWN);
 		const lines = [];
-		const cursor = `${BOLD$3}_${RESET$3}`;
-		lines.push(`${TEXT$2}Search ${noun}:${RESET$3} ${query}${cursor}`);
+		const cursor = `${BOLD$4}_${RESET$4}`;
+		lines.push(`${TEXT$3}Search ${noun}:${RESET$4} ${query}${cursor}`);
 		lines.push("");
-		if (loading && results.length === 0) lines.push(`${DIM$3}Loading catalog…${RESET$3}`);
-		else if (results.length === 0) lines.push(`${DIM$3}${query ? `No ${noun} match "${query}"` : `No ${noun} in catalog`}${RESET$3}`);
+		if (loading && results.length === 0) lines.push(`${DIM$4}Loading catalog…${RESET$4}`);
+		else if (results.length === 0) lines.push(`${DIM$4}${query ? `No ${noun} match "${query}"` : `No ${noun} in catalog`}${RESET$4}`);
 		else {
 			const maxVisible = 12;
 			const start = Math.max(0, Math.min(selectedIndex - maxVisible + 1, results.length - maxVisible));
 			const from = Math.max(0, start);
 			const visible = results.slice(from, from + maxVisible);
-			if (from > 0) lines.push(`  ${DIM$3}↑ ${from} more${RESET$3}`);
+			if (from > 0) lines.push(`  ${DIM$4}↑ ${from} more${RESET$4}`);
 			for (let i = 0; i < visible.length; i++) {
 				const idx = from + i;
 				const skill = visible[i];
 				const isSelected = idx === selectedIndex;
-				const arrow = isSelected ? `${BOLD$3}>${RESET$3}` : " ";
-				const box = picked.has(skill.name) ? `${GREEN}${CHECKED}${RESET$3}` : `${DIM$3}${UNCHECKED}${RESET$3}`;
-				const name = isSelected ? `${BOLD$3}${skill.name}${RESET$3}` : `${TEXT$2}${skill.name}${RESET$3}`;
-				const loadingIndicator = loading && idx === 0 ? ` ${DIM$3}...${RESET$3}` : "";
+				const arrow = isSelected ? `${BOLD$4}>${RESET$4}` : " ";
+				const box = picked.has(skill.name) ? `${GREEN}${CHECKED}${RESET$4}` : `${DIM$4}${UNCHECKED}${RESET$4}`;
+				const name = isSelected ? `${BOLD$4}${skill.name}${RESET$4}` : `${TEXT$3}${skill.name}${RESET$4}`;
+				const loadingIndicator = loading && idx === 0 ? ` ${DIM$4}...${RESET$4}` : "";
 				lines.push(`  ${arrow} ${box} ${name}${rowBadge(skill)}${loadingIndicator}`);
 			}
 			const remaining = results.length - (from + visible.length);
-			if (remaining > 0) lines.push(`  ${DIM$3}↓ ${remaining} more${RESET$3}`);
+			if (remaining > 0) lines.push(`  ${DIM$4}↓ ${remaining} more${RESET$4}`);
 		}
 		lines.push("");
-		const count = picked.size > 0 ? ` ${GREEN}(${picked.size} selected)${RESET$3}` : "";
-		lines.push(`${DIM$3}up/down navigate | space toggle | enter done${count}${DIM$3} | esc back${RESET$3}`);
+		const count = picked.size > 0 ? ` ${GREEN}(${picked.size} selected)${RESET$4}` : "";
+		lines.push(`${DIM$4}up/down navigate | space toggle | enter done${count}${DIM$4} | esc back${RESET$4}`);
 		for (const line of lines) process.stdout.write(line + "\n");
 		lastRenderedLines = lines.length;
 	}
@@ -4982,22 +5032,22 @@ async function runSearchPrompt(kind, alreadyPicked = /* @__PURE__ */ new Set(),
 async function runFind(args) {
 	const query = args.join(" ");
 	const isNonInteractive = !process.stdin.isTTY;
-	const agentTip = `${DIM$3}Tip: if running in a coding agent, follow these steps:${RESET$3}
-${DIM$3}  1) npx pruff-skills find [query]${RESET$3}
-${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
+	const agentTip = `${DIM$4}Tip: if running in a coding agent, follow these steps:${RESET$4}
+${DIM$4}  1) npx pruff-skills find [query]${RESET$4}
+${DIM$4}  2) npx pruff-skills add <skill>${RESET$4}`;
 	if (query) {
 		const results = await searchSkillsAPI(query);
 		String(results.length);
 		if (results.length === 0) {
-			console.log(`${DIM$3}Nothing in the catalog matches "${query}"${RESET$3}`);
+			console.log(`${DIM$4}Nothing in the catalog matches "${query}"${RESET$4}`);
 			return;
 		}
-		console.log(`${DIM$3}Install a skill with${RESET$3} npx pruff-skills add <name>${DIM$3}, a subagent with${RESET$3} npx pruff-skills agents add <name>${DIM$3}, a rule with${RESET$3} npx pruff-skills rules add <name>`);
+		console.log(`${DIM$4}Install a skill with${RESET$4} npx pruff-skills add <name>${DIM$4}, a subagent with${RESET$4} npx pruff-skills agents add <name>${DIM$4}, a rule with${RESET$4} npx pruff-skills rules add <name>`);
 		console.log();
 		for (const skill of results.slice(0, 10)) {
-			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$3}` : skill.kind === "rule" ? ` ${BLUE$1}[rule]${RESET$3}` : ` ${CYAN$1}[skill]${RESET$3}`;
-			console.log(`${TEXT$2}${skill.name}${RESET$3}${kindBadge}${rowBadge(skill)}`);
-			if (skill.description) console.log(`${DIM$3}└ ${skill.description}${RESET$3}`);
+			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$4}` : skill.kind === "rule" ? ` ${BLUE$1}[rule]${RESET$4}` : ` ${CYAN$1}[skill]${RESET$4}`;
+			console.log(`${TEXT$3}${skill.name}${RESET$4}${kindBadge}${rowBadge(skill)}`);
+			if (skill.description) console.log(`${DIM$4}└ ${skill.description}${RESET$4}`);
 			console.log();
 		}
 		return;
@@ -5005,7 +5055,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	if (isNonInteractive || await isRunningInAgent()) {
 		console.log(agentTip);
 		console.log();
-		console.log(`${DIM$3}Usage: npx pruff-skills find <query>${RESET$3}`);
+		console.log(`${DIM$4}Usage: npx pruff-skills find <query>${RESET$4}`);
 		return;
 	}
 	const all = await searchSkillsAPI("");
@@ -5030,7 +5080,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	const pickedByKind = new Map(KINDS.map((k) => [k.value, /* @__PURE__ */ new Set()]));
 	const totalPicked = () => [...pickedByKind.values()].reduce((n, set) => n + set.size, 0);
 	const cancelled = () => {
-		console.log(`${DIM$3}Search cancelled${RESET$3}`);
+		console.log(`${DIM$4}Search cancelled${RESET$4}`);
 		console.log();
 	};
 	for (;;) {
@@ -5061,10 +5111,10 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 			for (const kind of KINDS) {
 				const names = [...pickedByKind.get(kind.value)];
 				if (names.length === 0) continue;
-				console.log(`${TEXT$2}${kind.label}${RESET$3} ${DIM$3}(${names.length})${RESET$3}`);
+				console.log(`${TEXT$3}${kind.label}${RESET$4} ${DIM$4}(${names.length})${RESET$4}`);
 				for (const name of names) {
-					const note = all.find((s) => s.kind === kind.value && s.name === name)?.installed ? ` ${DIM$3}— already installed, will reinstall${RESET$3}` : "";
-					console.log(`  ${DIM$3}·${RESET$3} ${name}${note}`);
+					const note = all.find((s) => s.kind === kind.value && s.name === name)?.installed ? ` ${DIM$4}— already installed, will reinstall${RESET$4}` : "";
+					console.log(`  ${DIM$4}·${RESET$4} ${name}${note}`);
 				}
 			}
 			console.log();
@@ -5091,7 +5141,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	console.log();
 	if (skills.length > 0) {
 		const pkg = CATALOG_SOURCE;
-		console.log(`${TEXT$2}Installing ${BOLD$3}${skills.join(", ")}${RESET$3} from ${DIM$3}${pkg}${RESET$3}...`);
+		console.log(`${TEXT$3}Installing ${BOLD$4}${skills.join(", ")}${RESET$4} from ${DIM$4}${pkg}${RESET$4}...`);
 		console.log();
 		const { source, options } = parseAddOptions([
 			pkg,
@@ -5103,7 +5153,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	if (agents.length > 0) await addAgents(agents, {});
 	if (rules.length > 0) await addRules(rules, {});
 	console.log();
-	console.log(`${DIM$3}Installed.${RESET$3} ${TEXT$2}npx pruff-skills list${RESET$3} ${DIM$3}shows what's installed.${RESET$3}`);
+	console.log(`${DIM$4}Installed.${RESET$4} ${TEXT$3}npx pruff-skills list${RESET$4} ${DIM$4}shows what's installed.${RESET$4}`);
 	console.log();
 }
 const isCancelled = (value) => typeof value === "symbol";
@@ -5452,9 +5502,9 @@ async function runInstallFromLock(args) {
 		}
 	}
 }
-const RESET$2 = "\x1B[0m";
-const BOLD$2 = "\x1B[1m";
-const DIM$2 = "\x1B[38;5;102m";
+const RESET$3 = "\x1B[0m";
+const BOLD$3 = "\x1B[1m";
+const DIM$3 = "\x1B[38;5;102m";
 const CYAN = "\x1B[36m";
 const YELLOW = "\x1B[33m";
 const LIST_JSON_SCHEMA_VERSION = 1;
@@ -5491,8 +5541,8 @@ async function runList(args) {
 		const validAgents = Object.keys(agents);
 		const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
 		if (invalidAgents.length > 0) {
-			console.log(`${YELLOW}Invalid agents: ${invalidAgents.join(", ")}${RESET$2}`);
-			console.log(`${DIM$2}Valid agents: ${validAgents.join(", ")}${RESET$2}`);
+			console.log(`${YELLOW}Invalid agents: ${invalidAgents.join(", ")}${RESET$3}`);
+			console.log(`${DIM$3}Valid agents: ${validAgents.join(", ")}${RESET$3}`);
 			process.exit(1);
 		}
 		agentFilter = options.agent;
@@ -5518,21 +5568,21 @@ async function runList(args) {
 	const cwd = process.cwd();
 	const scopeLabel = scope ? "Global" : "Project";
 	if (installedSkills.length === 0) {
-		console.log(`${DIM$2}No ${scopeLabel.toLowerCase()} skills found.${RESET$2}`);
-		if (scope) console.log(`${DIM$2}Try listing project skills without -g${RESET$2}`);
-		else console.log(`${DIM$2}Try listing global skills with -g${RESET$2}`);
+		console.log(`${DIM$3}No ${scopeLabel.toLowerCase()} skills found.${RESET$3}`);
+		if (scope) console.log(`${DIM$3}Try listing project skills without -g${RESET$3}`);
+		else console.log(`${DIM$3}Try listing global skills with -g${RESET$3}`);
 		return;
 	}
 	function printSkill(skill, indent = false, maxNameLength = 0, maxPathLength = 0) {
 		const prefix = indent ? "  " : "";
 		const shortPath = shortenPath(skill.canonicalPath, cwd);
 		const agentNames = skill.agents.map((a) => agents[a].displayName);
-		const agentInfo = skill.agents.length > 0 ? formatList(agentNames) : `${YELLOW}not linked${RESET$2}`;
+		const agentInfo = skill.agents.length > 0 ? formatList(agentNames) : `${YELLOW}not linked${RESET$3}`;
 		const paddedName = sanitizeMetadata(skill.name).padEnd(maxNameLength);
 		const paddedPath = shortPath.padEnd(maxPathLength);
-		console.log(`${prefix}${CYAN}${paddedName}${RESET$2} ${DIM$2}${paddedPath}${RESET$2} ${DIM$2}Agents:${RESET$2} ${agentInfo}`);
+		console.log(`${prefix}${CYAN}${paddedName}${RESET$3} ${DIM$3}${paddedPath}${RESET$3} ${DIM$3}Agents:${RESET$3} ${agentInfo}`);
 	}
-	console.log(`${BOLD$2}${scopeLabel} Skills${RESET$2}`);
+	console.log(`${BOLD$3}${scopeLabel} Skills${RESET$3}`);
 	console.log();
 	const groupedSkills = {};
 	const ungroupedSkills = [];
@@ -5548,7 +5598,7 @@ async function runList(args) {
 		const sortedGroups = Object.keys(groupedSkills).sort();
 		for (const group of sortedGroups) {
 			const title = group.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-			console.log(`${BOLD$2}${title}${RESET$2}`);
+			console.log(`${BOLD$3}${title}${RESET$3}`);
 			const skills = groupedSkills[group];
 			if (skills) {
 				let maxNameLength = 0;
@@ -5564,7 +5614,7 @@ async function runList(args) {
 			console.log();
 		}
 		if (ungroupedSkills.length > 0) {
-			console.log(`${BOLD$2}General${RESET$2}`);
+			console.log(`${BOLD$3}General${RESET$3}`);
 			let maxNameLength = 0;
 			let maxPathLength = 0;
 			for (const skill of ungroupedSkills) {
@@ -5787,6 +5837,81 @@ function parseRemoveOptions(args) {
 		options
 	};
 }
+const RESET$2 = "\x1B[0m";
+const BOLD$2 = "\x1B[1m";
+const DIM$2 = "\x1B[38;5;102m";
+const TEXT$2 = "\x1B[38;5;145m";
+function classifyTrackedSkill(h) {
+	if (h.diskHash === null) return {
+		status: "missing",
+		locallyEdited: false
+	};
+	const divergent = h.diskHash === DIVERGENT_HASH;
+	if (h.catalogHash && h.catalogHash === h.lockHash) {
+		const installed = h.installedHash ?? h.catalogContentHash;
+		return {
+			status: "unchanged",
+			locallyEdited: divergent || h.diskHash !== installed
+		};
+	}
+	if (h.catalogContentHash && h.diskHash === h.catalogContentHash) return {
+		status: "rebaseline",
+		locallyEdited: false
+	};
+	const installed = h.installedHash ?? h.lockHash;
+	return {
+		status: "modified",
+		locallyEdited: divergent || h.diskHash !== installed
+	};
+}
+function emptyPlan() {
+	return {
+		modified: [],
+		missing: [],
+		rebaseline: [],
+		unchanged: [],
+		conflicts: [],
+		localEdits: [],
+		deleted: [],
+		available: [],
+		untracked: [],
+		failedSources: []
+	};
+}
+function addClassified(plan, entry, c) {
+	if (c.status === "unchanged") {
+		plan.unchanged.push(entry);
+		if (c.locallyEdited) plan.localEdits.push(entry);
+		return;
+	}
+	if (c.status === "modified" && c.locallyEdited) {
+		plan.conflicts.push(entry);
+		return;
+	}
+	plan[c.status].push(entry);
+}
+function names(entries) {
+	return entries.map((e) => sanitizeMetadata(e.name)).join(", ");
+}
+function line(label, entries, note) {
+	if (entries.length === 0) return;
+	const suffix = note ? ` ${DIM$2}— ${note}${RESET$2}` : "";
+	console.log(`  ${TEXT$2}${label} (${entries.length}):${RESET$2} ${names(entries)}${suffix}`);
+}
+function printPlan(plan, opts = {}) {
+	console.log(`${BOLD$2}Plan${RESET$2}`);
+	line("Modified upstream", plan.modified, "will update");
+	line("Missing on disk", plan.missing, "will reinstall");
+	line("Modified upstream + edited locally", plan.conflicts, opts.force ? "will overwrite (--force)" : "local edits kept unless you confirm or pass --force");
+	line("Deleted upstream", plan.deleted);
+	line("Already current", plan.rebaseline, "lock hash refreshed, nothing reinstalled");
+	line("New in catalog", plan.available, "not installed");
+	line("Installed but not tracked", plan.untracked, "not in skills-lock.json");
+	line("Edited locally", plan.localEdits, "unchanged upstream, left as is");
+	if (plan.unchanged.length > 0) console.log(`  ${DIM$2}Up to date: ${plan.unchanged.length}${RESET$2}`);
+	for (const source of plan.failedSources) console.log(`  ${DIM$2}✗ Could not read ${sanitizeMetadata(source)} — its skills were not checked${RESET$2}`);
+	console.log();
+}
 function formatSourceInput(sourceUrl, ref) {
 	if (!ref) return sourceUrl;
 	return `${sourceUrl}#${ref}`;
@@ -5830,6 +5955,8 @@ function parseUpdateOptions(args) {
 	for (const arg of args) if (arg === "-g" || arg === "--global") options.global = true;
 	else if (arg === "-p" || arg === "--project") options.project = true;
 	else if (arg === "-y" || arg === "--yes") options.yes = true;
+	else if (arg === "--dry-run") options.dryRun = true;
+	else if (arg === "--force") options.force = true;
 	else if (!arg.startsWith("-")) positional.push(arg);
 	if (positional.length > 0) options.skills = positional;
 	return options;
@@ -5950,7 +6077,9 @@ async function checkAndPromptForDeletions(source, allLockedForSource, lockSkills
 		console.log();
 		console.log(`${DIM$1}Warning:${RESET$1} The following skills from ${DIM$1}${source}${RESET$1} appear to have been deleted upstream:`);
 		for (const s of deletedSkills) console.log(`  ${DIM$1}•${RESET$1} ${s}`);
-		if (options.yes || !process.stdin.isTTY) console.log(`${DIM$1}Skipping deletion in non-interactive mode.${RESET$1}`);
+		const isNonInteractive = options.yes || !process.stdin.isTTY;
+		if (options.dryRun) console.log(`${DIM$1}Dry run — nothing removed.${RESET$1}`);
+		else if (isNonInteractive) console.log(`${DIM$1}Skipping deletion in non-interactive mode.${RESET$1}`);
 		else {
 			const confirmed = await ye({ message: `Would you like to remove the local copies of these deleted skills?` });
 			if (confirmed && !pD(confirmed)) for (const s of deletedSkills) {
@@ -6086,6 +6215,16 @@ async function updateGlobalSkills(options = {}) {
 	}
 	console.log(`${TEXT$1}Found ${updates.length} global update(s)${RESET$1}`);
 	console.log();
+	if (options.dryRun) {
+		for (const update of updates) console.log(`  ${TEXT$1}•${RESET$1} ${sanitizeMetadata(update.name)} ${DIM$1}would update${RESET$1}`);
+		printSkippedSkills(skipped);
+		console.log(`${DIM$1}Dry run — nothing was changed.${RESET$1}`);
+		return {
+			successCount,
+			failCount,
+			checkedCount
+		};
+	}
 	for (const update of updates) {
 		const safeName = sanitizeMetadata(update.name);
 		console.log(`${TEXT$1}Updating ${safeName}...${RESET$1}`);
@@ -6125,36 +6264,7 @@ async function updateGlobalSkills(options = {}) {
 		checkedCount
 	};
 }
-async function updateProjectSkills(options = {}) {
-	const projectSkills = await getProjectSkillsForUpdate(options.skills);
-	let successCount = 0;
-	let failCount = 0;
-	let upToDateCount = 0;
-	if (projectSkills.length === 0) {
-		if (!options.skills) {
-			console.log(`${DIM$1}No project skills to update.${RESET$1}`);
-			console.log(`${DIM$1}Install project skills with${RESET$1} ${TEXT$1}npx pruff-skills add <skill>${RESET$1}`);
-		}
-		return {
-			successCount,
-			failCount,
-			foundCount: 0,
-			upToDateCount
-		};
-	}
-	const updatable = projectSkills.filter((s) => s.entry.skillPath);
-	const legacy = projectSkills.filter((s) => !s.entry.skillPath);
-	if (updatable.length === 0) {
-		console.log(`${DIM$1}No project skills can be updated in place.${RESET$1}`);
-		printLegacyProjectSkills(legacy);
-		return {
-			successCount,
-			failCount,
-			foundCount: projectSkills.length,
-			upToDateCount
-		};
-	}
-	const cwd = process.cwd();
+function printUpdateTargets(cwd) {
 	const targetAgentNames = [];
 	let hasUniversal = false;
 	for (const [type, config] of Object.entries(agents)) if (isUniversalAgent(type)) {
@@ -6167,95 +6277,253 @@ async function updateProjectSkills(options = {}) {
 	if (hasUniversal) targetParts.push("Universal");
 	targetParts.push(...targetAgentNames);
 	if (targetParts.length > 0) console.log(`${TEXT$1}Updating for: ${targetParts.join(", ")}${RESET$1}`);
-	console.log(`${TEXT$1}Refreshing ${updatable.length} skill(s)...${RESET$1}`);
-	console.log();
+}
+async function safeHash(hash, dir) {
+	try {
+		return await hash(dir) || "";
+	} catch {
+		return "";
+	}
+}
+async function buildProjectPlan(updatable, localLock, cwd, skillFilter) {
+	const plan = emptyPlan();
+	const hashes = /* @__PURE__ */ new Map();
 	const bySource = /* @__PURE__ */ new Map();
 	for (const skill of updatable) {
-		const source = skill.entry.source;
-		const existing = bySource.get(source) || [];
+		const existing = bySource.get(skill.entry.source) || [];
 		existing.push(skill);
-		bySource.set(source, existing);
-	}
-	const localLock = await readLocalLock();
-	const cliEntry = join(__dirname$2, "..", "bin", "cli.mjs");
-	if (!existsSync(cliEntry)) {
-		console.log(`${DIM$1}✗ CLI entrypoint not found at ${cliEntry}${RESET$1}`);
-		return {
-			successCount,
-			failCount: updatable.length,
-			foundCount: projectSkills.length,
-			upToDateCount
-		};
+		bySource.set(skill.entry.source, existing);
 	}
 	for (const [source, skillsForSource] of bySource) {
 		const firstEntry = skillsForSource[0].entry;
 		const parsedSource = parseSource(firstEntry.source);
-		const sourceUrl = parsedSource.url;
 		const ref = firstEntry.ref ?? parsedSource.ref;
-		const allLockedForSource = Object.entries(localLock.skills).filter(([_, entry]) => entry.source === source).map(([name, _]) => name);
 		let tempDir = null;
-		let deletedSkills = [];
-		const unchangedSkills = /* @__PURE__ */ new Set();
 		try {
-			tempDir = await cloneRepo$1(sourceUrl, ref);
-			const discoveredPaths = (await discoverSkills(tempDir)).map((s) => {
-				return join(relative(tempDir, s.path), "SKILL.md").split(sep).join("/");
-			});
-			deletedSkills = await checkAndPromptForDeletions(source, allLockedForSource, localLock.skills, false, options, discoveredPaths);
+			setStep(`update:check:${source}`);
+			tempDir = await cloneRepo$1(parsedSource.url, ref);
+			const discovered = await discoverSkills(tempDir);
+			const byPath = new Map(discovered.map((s) => [join(relative(tempDir, s.path), "SKILL.md").split(sep).join("/"), s]));
 			for (const skill of skillsForSource) {
-				const { skillPath, computedHash } = skill.entry;
-				if (!skillPath || !computedHash || deletedSkills.includes(skill.name)) continue;
-				const currentHash = await computeSkillFolderHash(join(tempDir, dirname(skillPath))).catch(() => "");
-				if (currentHash && currentHash === computedHash) unchangedSkills.add(skill.name);
+				const entry = {
+					name: skill.name,
+					source
+				};
+				const found = byPath.get(skill.entry.skillPath);
+				if (!found) {
+					plan.deleted.push(entry);
+					continue;
+				}
+				const [catalogHash, catalogContentHash, diskHash] = await Promise.all([
+					safeHash(computeSkillFolderHash, found.path),
+					safeHash(computeSkillContentHash, found.path),
+					hashInstalledSkill(skill.name, cwd)
+				]);
+				hashes.set(skill.name, {
+					catalogHash,
+					catalogContentHash,
+					diskHash
+				});
+				addClassified(plan, entry, classifyTrackedSkill({
+					lockHash: skill.entry.computedHash,
+					installedHash: skill.entry.installedHash,
+					catalogHash,
+					catalogContentHash,
+					diskHash
+				}));
+			}
+			for (const skill of discovered) {
+				if (skill.name in localLock.skills) continue;
+				if (!matchesSkillFilter(skill.name, skillFilter)) continue;
+				const entry = {
+					name: skill.name,
+					source
+				};
+				if (findInstalledSkillDirs(skill.name, cwd).length > 0) plan.untracked.push(entry);
+				else plan.available.push(entry);
 			}
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			console.log(`${DIM$1}✗ Failed to check for deleted skills from ${source}: ${sanitizeMetadata(reason)}${RESET$1}`);
+			console.log(`${DIM$1}✗ Failed to read ${source}: ${sanitizeMetadata(reason)}${RESET$1}`);
+			plan.failedSources.push(source);
 		} finally {
 			if (tempDir) await cleanupTempDir(tempDir);
 		}
-		const remainingSkills = skillsForSource.filter((s) => !deletedSkills.includes(s.name));
-		for (const skill of remainingSkills) {
-			const safeName = sanitizeMetadata(skill.name);
-			if (unchangedSkills.has(skill.name)) {
-				upToDateCount++;
-				console.log(`${TEXT$1}✓${RESET$1} ${safeName} ${DIM$1}is up to date${RESET$1}`);
-				continue;
-			}
-			console.log(`${TEXT$1}Updating ${safeName}...${RESET$1}`);
-			const installUrl = formatSourceInput(skill.entry.source, skill.entry.ref);
-			if (spawnSync(process.execPath, [
-				cliEntry,
-				"add",
-				installUrl,
-				"--skill",
-				skill.name,
-				"-y"
-			], {
-				stdio: [
-					"inherit",
-					"pipe",
-					"pipe"
-				],
-				encoding: "utf-8",
-				shell: process.platform === "win32"
-			}).status === 0) {
-				successCount++;
-				console.log(`  ${TEXT$1}✓${RESET$1} Updated ${safeName}`);
-			} else {
-				failCount++;
-				console.log(`  ${DIM$1}✗ Failed to update ${safeName}${RESET$1}`);
-			}
-		}
 	}
-	printLegacyProjectSkills(legacy);
 	return {
-		successCount,
-		failCount,
-		foundCount: projectSkills.length,
-		upToDateCount
+		plan,
+		hashes
 	};
 }
+async function selectEntries(message, entries, hint) {
+	if (entries.length === 0) return [];
+	const picked = await searchMultiselect({
+		message,
+		items: entries.map((e) => ({
+			value: e,
+			label: e.name,
+			hint: hint(e)
+		}))
+	});
+	if (typeof picked === "symbol") return [];
+	return picked;
+}
+async function applyDeletions(deleted, interactive, cwd) {
+	if (deleted.length === 0) return;
+	if (!interactive) {
+		console.log(`${DIM$1}Deleted-upstream skills kept (non-interactive).${RESET$1}`);
+		return;
+	}
+	const confirmed = await ye({ message: `Remove the local copies of ${deleted.length} skill(s) deleted upstream?` });
+	if (!confirmed || pD(confirmed)) return;
+	for (const { name } of deleted) {
+		if (findInstalledSkillDirs(name, cwd).length > 0) {
+			console.log(`${DIM$1}Removing${RESET$1} ${sanitizeMetadata(name)}...`);
+			await removeCommand([name], {
+				yes: true,
+				global: false
+			});
+		}
+		await removeSkillFromLocalLock(name, cwd);
+	}
+}
+async function refreshLockHashes(plan, hashes, cwd) {
+	const lock = await readLocalLock(cwd);
+	const edited = new Set(plan.localEdits.map((e) => e.name));
+	let changed = false;
+	for (const { name } of plan.rebaseline) {
+		const h = hashes.get(name);
+		const entry = lock.skills[name];
+		if (!h || !entry || !h.diskHash) continue;
+		lock.skills[name] = {
+			...entry,
+			computedHash: h.catalogHash,
+			installedHash: h.diskHash
+		};
+		changed = true;
+	}
+	for (const { name } of plan.unchanged) {
+		const h = hashes.get(name);
+		const entry = lock.skills[name];
+		if (!h || !entry || entry.installedHash || edited.has(name) || !h.diskHash) continue;
+		lock.skills[name] = {
+			...entry,
+			installedHash: h.diskHash
+		};
+		changed = true;
+	}
+	if (changed) await writeLocalLock(lock, cwd);
+}
+function installFromSource(cliEntry, installUrl, skillNames) {
+	return spawnSync(process.execPath, [
+		cliEntry,
+		"add",
+		installUrl,
+		"--skill",
+		...skillNames,
+		"-y"
+	], {
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
+		encoding: "utf-8",
+		shell: process.platform === "win32"
+	}).status === 0;
+}
+async function updateProjectSkills(options = {}) {
+	const result = {
+		successCount: 0,
+		failCount: 0,
+		foundCount: 0,
+		upToDateCount: 0,
+		installedCount: 0,
+		rebaselinedCount: 0
+	};
+	const projectSkills = await getProjectSkillsForUpdate(options.skills);
+	result.foundCount = projectSkills.length;
+	if (projectSkills.length === 0) {
+		if (!options.skills) {
+			console.log(`${DIM$1}No project skills to update.${RESET$1}`);
+			console.log(`${DIM$1}Install project skills with${RESET$1} ${TEXT$1}npx pruff-skills add <skill>${RESET$1}`);
+		}
+		return result;
+	}
+	const updatable = projectSkills.filter((s) => s.entry.skillPath);
+	const legacy = projectSkills.filter((s) => !s.entry.skillPath);
+	if (updatable.length === 0) {
+		console.log(`${DIM$1}No project skills can be updated in place.${RESET$1}`);
+		printLegacyProjectSkills(legacy);
+		return result;
+	}
+	const cwd = process.cwd();
+	printUpdateTargets(cwd);
+	console.log(`${TEXT$1}Comparing ${updatable.length} skill(s) with their sources...${RESET$1}`);
+	console.log();
+	const { plan, hashes } = await buildProjectPlan(updatable, await readLocalLock(cwd), cwd, options.skills);
+	printPlan(plan, { force: options.force });
+	printLegacyProjectSkills(legacy);
+	result.upToDateCount = plan.unchanged.length;
+	if (options.dryRun) {
+		console.log(`${DIM$1}Dry run — nothing was changed.${RESET$1}`);
+		return result;
+	}
+	const interactive = !options.yes && process.stdin.isTTY === true;
+	await applyDeletions(plan.deleted, interactive, cwd);
+	await refreshLockHashes(plan, hashes, cwd);
+	result.rebaselinedCount = plan.rebaseline.length;
+	result.upToDateCount += plan.rebaseline.length;
+	let overwrite = [];
+	if (options.force) overwrite = plan.conflicts;
+	else if (interactive) overwrite = await selectEntries("Changed upstream and edited locally. Overwrite which? (none selected keeps your edits)", plan.conflicts, () => "local edits will be lost");
+	let toInstall = [];
+	if (interactive) toInstall = await selectEntries("Install new skills from your sources?", [...plan.available, ...plan.untracked], (e) => plan.untracked.includes(e) ? "already on disk, untracked — overwrites it" : e.source);
+	else if (plan.available.length > 0) console.log(`${DIM$1}To install new skills: ${TEXT$1}npx pruff-skills add <source> --skill <name>${RESET$1}`);
+	const toUpdate = [
+		...plan.modified,
+		...plan.missing,
+		...overwrite
+	];
+	if (toUpdate.length === 0 && toInstall.length === 0) return result;
+	const cliEntry = join(__dirname$2, "..", "bin", "cli.mjs");
+	if (!existsSync(cliEntry)) {
+		console.log(`${DIM$1}✗ CLI entrypoint not found at ${cliEntry}${RESET$1}`);
+		result.failCount += toUpdate.length + toInstall.length;
+		return result;
+	}
+	const refBySource = new Map(updatable.map((s) => [s.entry.source, s.entry.ref]));
+	const batches = /* @__PURE__ */ new Map();
+	for (const e of [...toUpdate, ...toInstall]) {
+		const batch = batches.get(e.source) || [];
+		batch.push(e);
+		batches.set(e.source, batch);
+	}
+	for (const [source, entries] of batches) {
+		const label = entries.map((e) => sanitizeMetadata(e.name)).join(", ");
+		console.log(`${TEXT$1}Installing from ${sanitizeMetadata(source)}: ${label}${RESET$1}`);
+		setStep(`update:install:${source}`);
+		installFromSource(cliEntry, formatSourceInput(source, refBySource.get(source)), entries.map((e) => e.name));
+	}
+	const after = await readLocalLock(cwd);
+	const isNew = new Set(toInstall.map((e) => e.name));
+	for (const e of [...toUpdate, ...toInstall]) {
+		const safeName = sanitizeMetadata(e.name);
+		const entry = after.skills[e.name];
+		const expected = hashes.get(e.name)?.catalogHash;
+		if (!(isNew.has(e.name) ? Boolean(entry) : Boolean(entry && (!expected || entry.computedHash === expected)))) {
+			result.failCount++;
+			console.log(`  ${DIM$1}✗ Failed to ${isNew.has(e.name) ? "install" : "update"} ${safeName}${RESET$1}`);
+		} else if (isNew.has(e.name)) {
+			result.installedCount++;
+			console.log(`  ${TEXT$1}✓${RESET$1} Installed ${safeName}`);
+		} else {
+			result.successCount++;
+			console.log(`  ${TEXT$1}✓${RESET$1} Updated ${safeName}`);
+		}
+	}
+	return result;
+}
 function printLegacyProjectSkills(legacy) {
 	if (legacy.length === 0) return;
 	console.log();
@@ -6269,14 +6537,18 @@ function printLegacyProjectSkills(legacy) {
 async function syncAgentsForScope(isGlobal, options) {
 	const result = await updateAgents({
 		global: isGlobal,
-		names: options.skills
+		names: options.skills,
+		dryRun: options.dryRun
 	});
 	const label = isGlobal ? "global" : "project";
 	if (result.catalogUnavailable) {
 		console.log(`  ${DIM$1}✗ Could not read the subagent catalog — skipped ${label} subagents${RESET$1}`);
 		return result;
 	}
-	for (const name of result.updated) console.log(`  ${TEXT$1}✓${RESET$1} Synced ${sanitizeMetadata(name)}`);
+	for (const name of result.updated) {
+		const verb = options.dryRun ? "Would sync" : "Synced";
+		console.log(`  ${TEXT$1}✓${RESET$1} ${verb} ${sanitizeMetadata(name)}`);
+	}
 	for (const name of result.unchanged) console.log(`  ${TEXT$1}✓${RESET$1} ${sanitizeMetadata(name)} ${DIM$1}is up to date${RESET$1}`);
 	for (const name of result.failed) console.log(`  ${DIM$1}✗ Failed to sync ${sanitizeMetadata(name)}${RESET$1}`);
 	if (result.localOnly.length > 0) {
@@ -6301,6 +6573,8 @@ async function runUpdate(args = []) {
 	let totalFail = 0;
 	let totalFound = 0;
 	let totalUpToDate = 0;
+	let totalInstalled = 0;
+	let totalRebaselined = 0;
 	if (scope === "global" || scope === "both") {
 		if (scope === "both" && !options.skills) console.log(`${BOLD$1}Global Skills${RESET$1}`);
 		setStep("update:global-skills");
@@ -6313,15 +6587,17 @@ async function runUpdate(args = []) {
 	if (scope === "project" || scope === "both") {
 		if (scope === "both" && !options.skills) console.log(`${BOLD$1}Project Skills${RESET$1}`);
 		setStep("update:project-skills");
-		const { successCount, failCount, foundCount, upToDateCount } = await updateProjectSkills(options);
+		const { successCount, failCount, foundCount, upToDateCount, installedCount, rebaselinedCount } = await updateProjectSkills(options);
 		totalUpToDate += upToDateCount;
+		totalInstalled += installedCount;
+		totalRebaselined += rebaselinedCount;
 		totalSuccess += successCount;
 		totalFail += failCount;
 		totalFound += foundCount;
 	}
 	console.log();
 	console.log(`${BOLD$1}Subagents${RESET$1}`);
-	console.log(`${DIM$1}ALL installed subagents will be updated and synced with the repo — local edits are overwritten.${RESET$1}`);
+	console.log(options.dryRun ? `${DIM$1}Dry run — subagents are compared, not written.${RESET$1}` : `${DIM$1}ALL installed subagents will be updated and synced with the repo — local edits are overwritten.${RESET$1}`);
 	setStep("update:sync-agents");
 	const agentScopes = scope === "both" ? [true, false] : scope === "global" ? [true] : [false];
 	let agentsSynced = 0;
@@ -6340,8 +6616,13 @@ async function runUpdate(args = []) {
 	totalUpToDate += agentsUnchanged;
 	if (options.skills && totalFound === 0) console.log(`${DIM$1}No installed skills found matching: ${options.skills.join(", ")}${RESET$1}`);
 	console.log();
-	if (totalSuccess > 0) console.log(`${TEXT$1}✓ Updated ${totalSuccess} item(s)${RESET$1}`);
-	else if (totalUpToDate > 0 && totalFail === 0) console.log(`${TEXT$1}✓ Everything is up to date${RESET$1}`);
+	const parts = [];
+	if (totalSuccess > 0) parts.push(`${totalSuccess} ${options.dryRun ? "to update" : "updated"}`);
+	if (totalInstalled > 0) parts.push(`${totalInstalled} installed`);
+	if (totalRebaselined > 0) parts.push(`${totalRebaselined} already current (lock refreshed)`);
+	if (totalUpToDate - totalRebaselined > 0) parts.push(`${totalUpToDate - totalRebaselined} up to date`);
+	if (totalSuccess + totalInstalled === 0 && totalFail === 0 && totalUpToDate > 0) console.log(`${TEXT$1}✓ Everything is up to date${RESET$1} ${DIM$1}(${parts.join(" · ")})${RESET$1}`);
+	else if (parts.length > 0) console.log(`${TEXT$1}✓ ${parts.join(" · ")}${RESET$1}`);
 	if (totalFail > 0) {
 		recordFailure(`Failed to update ${totalFail} item(s)`);
 		console.log(`${DIM$1}Failed to update ${totalFail} item(s)${RESET$1}`);
@@ -10236,14 +10517,17 @@ ${BOLD}Troubleshooting:${RESET}
                        add, update, rules add, agents add or onboarding fails.
 
 ${BOLD}Updates:${RESET}
-  update [skills...]   Update skills to latest versions (alias: upgrade)
-                     Also syncs ALL installed subagents with the catalog,
-                     overwriting local edits.
+  update [skills...]   Compare installed skills with their source, print a plan
+                     (modified / new / deleted / up to date) and apply only what
+                     changed (alias: upgrade). Also syncs ALL installed subagents
+                     with the catalog, overwriting local edits.
 
 ${BOLD}Update Options:${RESET}
   -g, --global           Update global skills only
   -p, --project          Update project skills only
   -y, --yes              Skip scope prompt (auto-detect: project if in a project, else global)
+  --dry-run              Print the plan and change nothing
+  --force                Overwrite skills edited locally that also changed upstream
 
 ${BOLD}Project:${RESET}
   restore              Restore skills from skills-lock.json
@@ -10307,6 +10591,7 @@ ${BOLD}Examples:${RESET}
   ${DIM}$${RESET} pruff-skills update
   ${DIM}$${RESET} pruff-skills update <skill>         ${DIM}# update a single skill${RESET}
   ${DIM}$${RESET} pruff-skills update -g                  ${DIM}# update global skills only${RESET}
+  ${DIM}$${RESET} pruff-skills update --dry-run           ${DIM}# show what would change${RESET}
   ${DIM}$${RESET} pruff-skills restore                     ${DIM}# restore from skills-lock.json${RESET}
   ${DIM}$${RESET} pruff-skills init my-skill
   ${DIM}$${RESET} pruff-skills sync                        ${DIM}# sync from node_modules${RESET}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {