politty 0.9.0 → 0.9.2

package/dist/skill/index.js

@@ -0,0 +1,1563 @@
+import { t as arg } from "../arg-registry-BeLLAW5-.js";
+import { n as defineCommand } from "../command-B4yA4LXX.js";
+import { a as symbols, n as logger } from "../logger-DbDkjdfO.js";
+import { z } from "zod";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { parse as parse$1 } from "yaml";
+
+//#region src/skill/frontmatter.ts
+/**
+* Skill name pattern from the Agent Skills specification:
+* https://agentskills.io/specification
+*
+* Lowercase alphanumerics separated by single hyphens, no leading/trailing
+* hyphen. Also used as the skill directory name; enforced again at scan time
+* to match the containing directory name.
+*/
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+* Max lengths come from the Agent Skills specification.
+*/
+const NAME_MAX = 64;
+const DESCRIPTION_MAX = 1024;
+const COMPATIBILITY_MAX = 500;
+/**
+* Zod schema for SKILL.md frontmatter.
+*
+* Strictly validates the fields defined in the Agent Skills specification
+* (https://agentskills.io/specification). Unknown fields are preserved via
+* `.passthrough()` so spec extensions and vendor keys round-trip intact.
+*
+* Provenance / ownership for politty-managed installs is recorded under
+* `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
+*/
+const skillFrontmatterSchema = z.object({
+	/** Skill identifier. Lowercase alphanumerics + hyphens, 1..64 chars. */
+	name: z.string().min(1).max(NAME_MAX).regex(SKILL_NAME_PATTERN, { message: "name must be lowercase alphanumerics separated by single hyphens" }),
+	/** Human-readable description (1..1024 chars). */
+	description: z.string().min(1).max(DESCRIPTION_MAX),
+	/** SPDX license identifier or free-form string. */
+	license: z.string().min(1).optional(),
+	/** Runtime / tool compatibility string (<=500 chars). */
+	compatibility: z.string().max(COMPATIBILITY_MAX).optional(),
+	/** Metadata map (spec: string keys, string values). */
+	metadata: z.record(z.string(), z.string()).optional(),
+	/** Experimental spec field. */
+	"allowed-tools": z.string().optional()
+}).passthrough();
+/**
+* Matches a YAML frontmatter block. The leading `\uFEFF?` tolerates a UTF-8
+* byte-order mark that some editors prepend to saved files.
+*/
+const FRONTMATTER_PATTERN = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/;
+/**
+* Parse YAML frontmatter from a SKILL.md string.
+*
+* `parseError` is set when the frontmatter fence was present but the YAML
+* inside failed to parse, so the scanner can distinguish "invalid YAML"
+* from "missing required field" in its diagnostics. A non-object root
+* (e.g. a top-level YAML list) also returns empty `data` without
+* `parseError` — Zod's schema validation surfaces that case clearly
+* enough on its own.
+*
+* @example
+* ```typescript
+* const result = parseFrontmatter(`---
+* name: commit
+* description: Git commit message generation
+* ---
+* # Instructions...`);
+*
+* result.data.name; // "commit"
+* ```
+*/
+function parseFrontmatter(content) {
+	const match = content.match(FRONTMATTER_PATTERN);
+	if (!match) return {
+		data: {},
+		body: content
+	};
+	const yamlBlock = match[1];
+	const body = match[2];
+	try {
+		const data = parse$1(yamlBlock);
+		if (!isPlainObject(data)) return {
+			data: {},
+			body
+		};
+		return {
+			data,
+			body
+		};
+	} catch (error) {
+		return {
+			data: {},
+			body,
+			parseError: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* Root-level plain-object check. Rejects Dates, Maps, and custom tagged types
+* at the root of the parsed YAML; nested values are still validated by the
+* Zod schema that consumes this data.
+*/
+function isPlainObject(value) {
+	if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Parse and validate a SKILL.md content string.
+*
+* @returns Parsed skill metadata and body, or `null` if the frontmatter is
+*   missing or fails schema validation.
+*/
+function parseSkillMd(content) {
+	const { data, body } = parseFrontmatter(content);
+	const result = skillFrontmatterSchema.safeParse(data);
+	if (!result.success) return null;
+	return {
+		frontmatter: result.data,
+		body,
+		rawContent: content
+	};
+}
+
+//#endregion
+//#region src/skill/installer.ts
+/** Canonical directory where skill files are stored. */
+const AGENTS_SKILLS_DIR = ".agents/skills";
+/**
+* Agent directories that get symlinks to the canonical skill directory.
+* Universal agents (Cursor, Cline, etc.) read from .agents/skills/ directly.
+*
+* Exported as the single source of truth shared with `commands.ts`'s
+* dangling-symlink reaper so the two stay in lock-step.
+*/
+const SYMLINK_TARGETS = [".claude/skills"];
+/**
+* Key used to read provenance off an installed skill. The SKILL.md's
+* `metadata["politty-cli"]` must equal `"{packageName}:{cliName}"` for the
+* owning CLI to manage it. This stamp is authored by the skill package,
+* not rewritten at install time.
+*/
+const OWNERSHIP_METADATA_KEY = "politty-cli";
+/**
+* Defense-in-depth check against path traversal. Skill names are also
+* validated by the frontmatter schema (1..64 chars, lowercase alphanumerics
+* separated by single hyphens), but we re-validate here in case a caller
+* bypasses it. The 64-char limit is intentionally duplicated rather than
+* imported from frontmatter.ts so this check stays independent.
+*/
+function assertSafeName(name) {
+	if (name.length < 1 || name.length > 64 || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) throw new Error(`Invalid skill name: ${JSON.stringify(name)}`);
+}
+/**
+* Install a skill to the project's agent skill directories.
+*
+* Canonical `.agents/skills/<name>` and each `SYMLINK_TARGETS` entry are
+* populated according to `options.mode`:
+*
+* - `"symlink"` (default): symlink to the source (or to the canonical dir
+*   for the agent-specific slots). Source updates propagate live. Throws
+*   with guidance to retry with `"copy"` on filesystems without symlink
+*   support (e.g. Windows without Developer Mode).
+* - `"copy"`: recursive copy. Works anywhere, but source updates require
+*   re-running install.
+*
+* **Symlink target convention.** Symlinks are written with relative
+* targets so an install survives when the project tree is copied or
+* mounted at a different absolute path. The two endpoints are resolved
+* asymmetrically:
+*
+* - The install root (`.agents/skills/`, each `SYMLINK_TARGETS` parent)
+*   is passed through `realpathSync` so a symlinked checkout doesn't
+*   bake a stale parent path into the relative target.
+* - The source path is resolved by {@link resolveSourcePreservingPackageHop},
+*   which walks root→leaf dereferencing every ancestor symlink (a symlinked
+*   checkout, macOS `/tmp` → `/private/tmp`, etc.) like `realpathSync` would
+*   — EXCEPT a `node_modules/<pkg>` (or `node_modules/@scope/<pkg>`)
+*   symlink, which is preserved. Following the package-manager hop would
+*   bake pnpm's volatile `node_modules/.pnpm/<pkg>@<version>_<hash>/...`
+*   into the link target and a subsequent `pnpm update` would leave every
+*   install dangling. Keeping the hop preserves the stable
+*   `node_modules/<pkg>` symlink that pnpm keeps repointing, while the
+*   project-root portion still matches the install root's realpath style
+*   so the install survives copying or remounting the project tree.
+*
+* The overlap guard and copy-mode payload still use the *fully*
+* `realpathSync`-resolved source: the guard must catch a source-side
+* symlink whose target is nested inside the install root, and the
+* copy-mode payload reads through every symlink so a copy install doesn't
+* leave dangling references back into `node_modules`.
+*
+* No absolute-path symlinks are produced by this function.
+*
+* **Atomicity.** This call is *not* transactional across multi-step
+* installs. The canonical slot is cleared then written, and each
+* `SYMLINK_TARGETS` slot is then cleared and written one at a time. A
+* crash mid-install can leave the canonical slot updated and one or
+* more agent-specific slots stale; re-running `installSkill` (or the
+* `skills sync` subcommand, which iterates over multiple skills) is
+* idempotent and converges back to the intended state. Within a single
+* slot's copy-mode write, the staging-and-rename in {@link atomicCopyDir}
+* guarantees the destination is either absent or fully populated — a
+* mid-copy failure never leaves a stamp-less partial directory that the
+* next install's `clearInstallSlot` would refuse to replace. Multi-skill
+* orchestration in {@link createSkillSyncCommand} is fail-fast — the
+* first failed skill aborts the loop without rolling back already-
+* installed siblings, again because re-running converges.
+*
+* The ownership stamp (`metadata["politty-cli"]`) is authored by the skill
+* package; the installer does not modify SKILL.md.
+*/
+function installSkill(skill, cwd = process.cwd(), options = {}) {
+	const name = skill.frontmatter.name;
+	assertSafeName(name);
+	const mode = options.mode ?? "symlink";
+	const expectedStamp = skill.frontmatter.metadata?.["politty-cli"] ?? null;
+	if (mode === "copy" && expectedStamp === null) throw new Error(`Refusing to install "${skill.frontmatter.name}" in copy mode without an ownership stamp. Add metadata.${OWNERSHIP_METADATA_KEY}="{package}:{cli}" to the source SKILL.md so subsequent installs can replace the copy in place.`);
+	const canonicalParent = resolve(cwd, AGENTS_SKILLS_DIR);
+	const resolvedSource = realpathSync(skill.sourcePath);
+	const symlinkAwareSource = resolveSourcePreservingPackageHop(skill.sourcePath);
+	const overlap = [join(resolveExistingPrefix(canonicalParent), name), ...SYMLINK_TARGETS.map((target) => join(resolveExistingPrefix(resolve(cwd, target)), name))].find((dest) => pathsOverlap(dest, resolvedSource));
+	if (overlap !== void 0) throw new Error(`Refusing to install "${name}": source ${resolvedSource} overlaps install destination ${overlap}. Choose a sourceDir outside .agents/skills/ and any agent-specific slot directory (e.g. .claude/skills/).`);
+	if (mode === "symlink") {
+		const preflightCanonicalParent = resolveExistingPrefix(canonicalParent);
+		assertRelativeLinkTarget(join(preflightCanonicalParent, name), relative(preflightCanonicalParent, symlinkAwareSource));
+		for (const target of SYMLINK_TARGETS) {
+			const preflightAgentParent = resolveExistingPrefix(resolve(cwd, target));
+			assertRelativeLinkTarget(join(preflightAgentParent, name), join(relative(preflightAgentParent, preflightCanonicalParent), name));
+		}
+	}
+	mkdirSync(canonicalParent, { recursive: true });
+	const resolvedParent = realpathSync(canonicalParent);
+	const canonicalDir = join(resolvedParent, name);
+	clearInstallSlot(canonicalDir, expectedStamp);
+	symlinkOrCopy({
+		linkTarget: relative(resolvedParent, symlinkAwareSource),
+		linkPath: canonicalDir,
+		copyFrom: resolvedSource,
+		mode
+	});
+	populateAgentDirs(cwd, name, canonicalDir, expectedStamp, mode);
+}
+/**
+* Refuse to write a symlink whose target was returned absolute. On Windows
+* `path.relative` returns an absolute path when the endpoints live on
+* different drive letters; producing an absolute symlink target would
+* silently break the "relative target" contract and surprise anyone
+* copying the project tree. Used both as the pre-flight in `installSkill`
+* (before any `clearInstallSlot`) and as the in-line guard inside
+* `symlinkOrCopy`.
+*/
+function assertRelativeLinkTarget(linkPath, linkTarget) {
+	if (isAbsolute(linkTarget)) throw new Error(`Refusing to write an absolute symlink target at ${linkPath} → ${linkTarget}. The skill source and install root appear to live on different filesystem roots (e.g. different Windows drive letters); retry with mode: "copy".`);
+}
+/**
+* Resolve `sourcePath` so every ancestor symlink (a symlinked checkout,
+* macOS `/tmp` → `/private/tmp`, etc.) gets dereferenced — EXCEPT a
+* `node_modules/<pkg>` or `node_modules/@scope/<pkg>` symlink, which is
+* preserved verbatim from that point onward.
+*
+* Used by `installSkill` to compute the canonical symlink target (see the
+* "Symlink target convention" JSDoc on `installSkill`). The project-root
+* portion of the source must end up in the same realpath style as the
+* install root so a copy/remount keeps both ends in sync; the package
+* manager hop must be preserved so a `pnpm update` that swaps the
+* `.pnpm/<pkg>@<version>_<hash>/...` hashed directory doesn't leave the
+* install dangling.
+*
+* Algorithm: walk root → leaf segment-by-segment. At each segment,
+* `lstatSync` the prefix. If it is a symlink AND its parent looks like a
+* package-manager hop (`node_modules` directly, or an `@scope/` directory
+* inside `node_modules`), return immediately with the remaining segments
+* joined lexically. Otherwise dereference via `realpathSync` (regular
+* directories are kept as-is; ancestor symlinks are followed). If the
+* path doesn't exist past some prefix, return what we have plus the
+* remaining tail lexically — installs against a missing source still
+* throw via the up-front `realpathSync(sourcePath)` call in `installSkill`.
+*/
+function resolveSourcePreservingPackageHop(sourcePath) {
+	const abs = resolve(sourcePath);
+	const { root } = parse(abs);
+	const parts = abs.slice(root.length).split(sep).filter((s) => s !== "");
+	let current = root;
+	for (const [i, segment] of parts.entries()) {
+		const next = join(current, segment);
+		let stat;
+		try {
+			stat = lstatSync(next);
+		} catch {
+			return join(current, ...parts.slice(i));
+		}
+		if (stat.isSymbolicLink()) {
+			if (isPackageManagerHop(current)) return join(current, ...parts.slice(i));
+			current = realpathSync(next);
+		} else current = next;
+	}
+	return current;
+}
+/**
+* Does `parentDir` look like the directory immediately above a
+* package-manager symlink? Two layouts qualify:
+*
+* - `<...>/node_modules` — a child symlink at this level is a plain
+*   package (`node_modules/<pkg>`).
+* - `<...>/node_modules/@<scope>` — a child symlink at this level is a
+*   scoped package (`node_modules/@scope/<pkg>`).
+*
+* Anything else (a symlinked project checkout, `/tmp`, an arbitrary
+* shortcut elsewhere in the tree) is dereferenced.
+*/
+function isPackageManagerHop(parentDir) {
+	if (basename(parentDir) === "node_modules") return true;
+	return basename(parentDir).startsWith("@") && basename(dirname(parentDir)) === "node_modules";
+}
+/**
+* Resolve `p`'s deepest existing ancestor through `realpathSync` and then
+* re-append the lexical tail. Used to compare a not-yet-created destination
+* path against a realpath'd source without materialising the destination —
+* this catches /tmp ↔ /private/tmp style remaps even when the destination
+* parents don't exist yet.
+*/
+function resolveExistingPrefix(p) {
+	let cur = p;
+	const tail = [];
+	while (true) try {
+		const r = realpathSync(cur);
+		return tail.length === 0 ? r : resolve(r, ...tail.reverse());
+	} catch {
+		const parent = dirname(cur);
+		if (parent === cur) return p;
+		tail.push(cur.slice(parent.length).replace(/^[/\\]+/, ""));
+		cur = parent;
+	}
+}
+/**
+* Uninstall a skill from the project's agent skill directories.
+*
+* Each slot is unlinked only when its ownership can be proven:
+* - Agent-specific symlink slots (`.claude/skills/<name>` etc.) — a live
+*   symlink is unlinked only when it routes to our canonical slot, so a
+*   foreign tool's symlink at the same shared path is left untouched.
+* - The canonical slot (`.agents/skills/<name>`) — a live symlink is
+*   unlinked only when its routed-to SKILL.md carries
+*   `options.expectedOwnership`, so another politty-based CLI's live
+*   install in the same shared namespace is left untouched.
+* - Real directories at any slot are removed only when the directory's
+*   SKILL.md carries `options.expectedOwnership`. Unstamped or foreign
+*   real directories are left alone so legacy/manual installs are not
+*   silently recursively deleted.
+*
+* `skills remove` / `skills sync` always pass `expectedOwnership`. Direct
+* programmatic callers that omit it get the legacy permissive behaviour
+* on symlinks (unconditional unlink) but the conservative behaviour on
+* real directories (no-op). Broken (dangling) canonical symlinks are
+* outside this function's purview — they have no SKILL.md to read, so
+* `cleanupBrokenSlot` handles them with a routing check instead.
+*/
+function uninstallSkill(name, cwd = process.cwd(), options = {}) {
+	assertSafeName(name);
+	const expected = options.expectedOwnership ?? null;
+	const canonicalSlot = resolve(cwd, AGENTS_SKILLS_DIR, name);
+	for (const target of SYMLINK_TARGETS) removeInstalledSlot(resolve(cwd, target, name), expected, { restrictSymlinkTo: canonicalSlot });
+	removeInstalledSlot(canonicalSlot, expected);
+}
+/**
+* Does the symlink at `slot` route to `expected`?
+*
+* Used to gate symlink unlinking in shared-namespace agent slots
+* (`.claude/skills/<name>` etc.) so we never silently clobber a symlink
+* another tool installed there.
+*
+* Resolution rules:
+* - Absolute symlink target → compare directly.
+* - Relative target → resolve against the symlink's directory (lexical),
+*   which works even for a dangling symlink we still expect to own.
+* - When both endpoints exist, also match via `realpathSync` so a
+*   logically-equivalent path through a parent symlink still matches.
+*/
+function symlinkRoutesTo$1(slot, expected) {
+	let raw;
+	try {
+		raw = readlinkSync(slot);
+	} catch {
+		return false;
+	}
+	const resolvedTarget = isAbsolute(raw) ? raw : resolve(dirname(slot), raw);
+	if (resolvedTarget === expected) return true;
+	try {
+		return realpathSync(resolvedTarget) === realpathSync(expected);
+	} catch {
+		return false;
+	}
+}
+/**
+* Remove a previously-installed slot:
+* - Symlink at an agent-specific slot (`restrictSymlinkTo` provided) →
+*   unlink only when the symlink resolves to that target. A foreign
+*   symlink (another tool, manual install) is left alone so removing one
+*   owned canonical skill never deletes another tool's link.
+* - Symlink at the canonical slot (no `restrictSymlinkTo`) → unlink only
+*   when its routed-to SKILL.md carries `expectedStamp`. `.agents/skills/`
+*   is a namespace shared by every politty-based CLI, so unconditionally
+*   unlinking would let a programmatic `uninstallSkill` caller delete a
+*   foreign CLI's live install. `expectedStamp === null` preserves the
+*   legacy permissive behaviour for callers that opt out of ownership
+*   checks entirely (e.g. teardown helpers).
+* - Real directory whose SKILL.md carries `expectedStamp` → rm -rf. This
+*   handles copy-mode installs that share the same canonical path as the
+*   symlink-mode installs.
+* - Anything else (absent, real dir without matching stamp, real file,
+*   broken symlink with no stamp to read) → no-op; caller can detect
+*   nothing changed by checking after the call.
+*
+* `unlinkSync` (not `rmSync`) is required for symlinks to directories —
+* `rmSync` without `recursive: true` errors "Path is a directory" on a
+* dir-symlink, but passing `recursive: true` would follow the symlink and
+* delete its target contents.
+*/
+function removeInstalledSlot(path, expectedStamp, options = {}) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (err) {
+		if (isNodeError$1(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) return;
+		throw err;
+	}
+	if (stat.isSymbolicLink()) {
+		if (options.restrictSymlinkTo !== void 0) {
+			if (symlinkRoutesTo$1(path, options.restrictSymlinkTo)) unlinkSync(path);
+			return;
+		}
+		if (expectedStamp === null || readStampAt(path) === expectedStamp) unlinkSync(path);
+		return;
+	}
+	if (stat.isDirectory() && expectedStamp !== null && readStampAt(path) === expectedStamp) rmSync(path, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Clear a slot so a new install can occupy `path`.
+*
+* - Absent → no-op.
+* - Symlink (live or broken) → unlink. In a shared-namespace slot
+*   (`restrictSymlinkTo` provided), only when the symlink resolves to that
+*   target; a foreign symlink at the slot throws instead of being silently
+*   replaced.
+* - Real directory whose SKILL.md carries `expectedStamp` → rm -rf. This
+*   is how a copy-mode install gets replaced in place by another install
+*   (symlink or copy); the ownership check guarantees we are only ever
+*   removing data we previously produced.
+* - Real file or foreign real directory → throw. The ownership guards in
+*   `addSkill` / `removeOwnedSkill` usually prevent this from being
+*   reachable, but a programmatic caller or a hand-made legacy install
+*   surfaces as an actionable error here rather than silent data loss.
+*/
+function clearInstallSlot(path, expectedStamp, options = {}) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (err) {
+		if (isNodeError$1(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) return;
+		throw err;
+	}
+	if (stat.isSymbolicLink()) {
+		if (options.restrictSymlinkTo === void 0 || symlinkRoutesTo$1(path, options.restrictSymlinkTo)) {
+			unlinkSync(path);
+			return;
+		}
+		throw new Error(`Refusing to replace symlink at ${path}: it does not route to this CLI's canonical slot (${options.restrictSymlinkTo}). Remove or migrate the foreign symlink before retrying.`);
+	}
+	if (stat.isDirectory() && expectedStamp !== null && readStampAt(path) === expectedStamp) {
+		rmSync(path, {
+			recursive: true,
+			force: true
+		});
+		return;
+	}
+	throw new Error(`Refusing to replace non-symlink path at ${path}. This looks like a legacy or manual install; remove or migrate it before retrying.`);
+}
+/**
+* Create `linkPath` as a symlink to `linkTarget` (symlink mode) or
+* recursively copy `copyFrom` into `linkPath` (copy mode).
+*
+* In symlink mode, a `symlinkSync` failure is re-thrown with guidance to
+* retry with `mode: "copy"`. Windows without Developer Mode is the
+* canonical case — the underlying EPERM doesn't hint at the fix on its
+* own.
+*/
+function symlinkOrCopy(args) {
+	const { linkTarget, linkPath, copyFrom, mode } = args;
+	if (mode === "copy") {
+		atomicCopyDir(copyFrom, linkPath);
+		return;
+	}
+	assertRelativeLinkTarget(linkPath, linkTarget);
+	try {
+		symlinkSync(linkTarget, linkPath, "dir");
+	} catch (err) {
+		const cause = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to symlink ${linkPath} → ${linkTarget}: ${cause}. If this filesystem does not support symlinks (e.g. Windows without Developer Mode), retry with mode: "copy".`, { cause: err });
+	}
+}
+/**
+* Stage the copy at a sibling `<dest>.partial-XXXXXX` and rename it into
+* place only after the full copy succeeds. A partial copy that throws
+* partway (unreadable child, cyclic symlink, EIO, etc.) is removed before
+* the error propagates, so `dest` is never left as a stamp-less real
+* directory that `clearInstallSlot` would later refuse to replace.
+*
+* The staging directory lives in `dest`'s parent so `renameSync` stays on
+* the same filesystem (cross-device rename would fail with EXDEV).
+* Callers run `clearInstallSlot(dest, ...)` first, so `dest` is expected
+* to be absent when this is called — the `renameSync` simply moves the
+* fully-populated temp into place. A `*.partial-*` sibling surviving a
+* crash (e.g. `kill -9` between `copyDirRecursive` and `renameSync`) is
+* left as harmless on-disk garbage; subsequent installs ignore it.
+*/
+function atomicCopyDir(src, dest) {
+	const tmp = mkdtempSync(`${dest}.partial-`);
+	try {
+		copyDirRecursive(src, tmp);
+		renameSync(tmp, dest);
+	} catch (err) {
+		try {
+			rmSync(tmp, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw err;
+	}
+}
+/**
+* Recursively copy `src` to `dest` following symlinks (`statSync`, not
+* `lstatSync`). Symlinks in the source are materialised as copies of
+* their target content so the install does not leave dangling references
+* back into `node_modules`. Non-regular files (sockets, devices) are
+* ignored.
+*
+* `activeRealPaths` tracks the realpath of every directory currently on
+* the recursion stack so a directory symlink pointing at an ancestor
+* (e.g. `foo/bar -> ../..`) fails fast instead of recursing until the
+* stack overflows or the disk fills.
+*
+* Callers wrap this through {@link atomicCopyDir} so a partial copy is
+* never left at the final destination.
+*/
+function copyDirRecursive(src, dest, activeRealPaths = /* @__PURE__ */ new Set()) {
+	const stat = statSync(src);
+	if (stat.isDirectory()) {
+		const realSrc = realpathSync(src);
+		if (activeRealPaths.has(realSrc)) throw new Error(`Refusing to recursively copy cyclic directory symlink at ${src} (resolves to ${realSrc}, already on the copy stack).`);
+		activeRealPaths.add(realSrc);
+		try {
+			mkdirSync(dest, { recursive: true });
+			for (const entry of readdirSync(src)) copyDirRecursive(join(src, entry), join(dest, entry), activeRealPaths);
+		} finally {
+			activeRealPaths.delete(realSrc);
+		}
+		return;
+	}
+	if (stat.isFile()) copyFileSync(src, dest);
+}
+/**
+* Read the `metadata["politty-cli"]` stamp from a SKILL.md at `<dir>/SKILL.md`.
+* Returns `null` when the file is absent (ENOENT/ENOTDIR), has no
+* frontmatter, or has no string-valued stamp. Other read failures
+* (EACCES/EPERM/IO) propagate — `clearInstallSlot` and
+* `removeInstalledSlot` gate destructive `rmSync`/`unlinkSync` on the
+* stamp matching, so silently treating an unreadable owned copy as
+* "unstamped" would either strand an agent slot after deleting the
+* canonical or report a misleading "legacy or manual install" message
+* from `clearInstallSlot`'s no-clobber guard. Symmetric with
+* `readInstalledOwnership`'s ENOENT/ENOTDIR-only carve-out.
+*/
+function readStampAt(dir) {
+	let content;
+	try {
+		content = readFileSync(join(dir, "SKILL.md"), "utf-8");
+	} catch (err) {
+		if (isNodeError$1(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+		throw err;
+	}
+	const { data } = parseFrontmatter(content);
+	const metadata = data.metadata;
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return null;
+	const value = metadata[OWNERSHIP_METADATA_KEY];
+	return typeof value === "string" ? value : null;
+}
+/**
+* Report whether a skill is currently installed, independent of its
+* ownership stamp. Returns `true` when `.agents/skills/<name>/SKILL.md`
+* resolves to a readable file (through a valid symlink or directly, or
+* via a copy-mode install); returns `false` when the path is absent or
+* the canonical symlink is broken (source package uninstalled).
+*
+* Callers use this to distinguish the two cases where
+* {@link readInstalledOwnership} returns `null` — "not installed" (safe
+* to install fresh) vs. "installed but unstamped" (legacy or manual
+* install that should not be silently clobbered).
+*/
+function hasInstalledSkill(name, cwd = process.cwd()) {
+	assertSafeName(name);
+	return existsSync(resolve(cwd, AGENTS_SKILLS_DIR, name, "SKILL.md"));
+}
+/**
+* Read the ownership stamp off an installed skill's SKILL.md, if any.
+*
+* For symlink-mode installs `.agents/skills/<name>` points at the source,
+* so this reads the package-authored stamp. For copy-mode installs the
+* stamp was captured at install time into the local copy.
+*
+* @returns `metadata["politty-cli"]` as `"{packageName}:{cliName}"`, or
+*   `null` if the skill is not installed *or* the stamp is absent/malformed.
+*   Use {@link hasInstalledSkill} to distinguish the two cases.
+*/
+function readInstalledOwnership(name, cwd = process.cwd()) {
+	assertSafeName(name);
+	const path = resolve(cwd, AGENTS_SKILLS_DIR, name, "SKILL.md");
+	let content;
+	try {
+		content = readFileSync(path, "utf-8");
+	} catch (err) {
+		if (isNodeError$1(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+		throw err;
+	}
+	const { data } = parseFrontmatter(content);
+	const metadata = data.metadata;
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return null;
+	const value = metadata[OWNERSHIP_METADATA_KEY];
+	return typeof value === "string" ? value : null;
+}
+/**
+* Populate each agent-specific directory so it routes to the canonical
+* install. In symlink-capable filesystems the agent slot is a symlink to
+* `.agents/skills/<name>` so one install swap updates all agent views at
+* once. When `mode` is `"copy"` the slot is a recursive copy of
+* `canonicalDir` instead.
+*/
+function populateAgentDirs(cwd, name, canonicalDir, expectedStamp, mode) {
+	for (const target of SYMLINK_TARGETS) {
+		const targetParent = resolve(cwd, target);
+		mkdirSync(targetParent, { recursive: true });
+		const resolvedTargetParent = realpathSync(targetParent);
+		const targetDir = join(resolvedTargetParent, name);
+		clearInstallSlot(targetDir, expectedStamp, { restrictSymlinkTo: canonicalDir });
+		symlinkOrCopy({
+			linkTarget: join(relative(resolvedTargetParent, realpathSync(resolve(canonicalDir, ".."))), name),
+			linkPath: targetDir,
+			copyFrom: canonicalDir,
+			mode
+		});
+	}
+}
+function isNodeError$1(err) {
+	return err instanceof Error && typeof err.code === "string";
+}
+/**
+* Do `a` and `b` refer to the same directory, or is one nested inside the
+* other? Used to refuse copy-mode installs where the source and destination
+* would recurse into each other. Inputs are expected to be `realpathSync`'d
+* absolute paths so trailing separators and symlink hops don't desynchronise
+* the comparison.
+*
+* Containment is boundary-aware: only `..` or `..<sep>...` counts as escaping
+* `outer`. A relative path like `..backup` is a same-level sibling (one
+* segment whose name happens to start with two dots), so it must NOT be
+* treated as escape. The previous `startsWith("..")` check misclassified such
+* names as outside, missing real overlaps with siblings whose name begins
+* with `..`.
+*/
+function pathsOverlap(a, b) {
+	if (a === b) return true;
+	const isContainedIn = (inner, outer) => {
+		const rel = relative(outer, inner);
+		if (rel === "" || rel === ".") return true;
+		if (isAbsolute(rel)) return false;
+		return rel !== ".." && !rel.startsWith(`..${sep}`);
+	};
+	return isContainedIn(a, b) || isContainedIn(b, a);
+}
+
+//#endregion
+//#region src/skill/scanner.ts
+const SKILL_MD = "SKILL.md";
+/**
+* Scan a source directory for SKILL.md files.
+*
+* Each immediate subdirectory is a candidate skill; its `SKILL.md` is
+* parsed and validated against the Agent Skills specification, and the
+* frontmatter `name` must match the subdirectory name (spec requirement).
+*
+* If `sourceDir` itself contains a `SKILL.md`, it is treated as a
+* single-skill source. The parent-directory-name match is not enforced in
+* that case because the caller chose an arbitrary path.
+*
+* Symlinks within the source tree are followed (symlinked skill dirs and
+* symlinked SKILL.md files are both accepted). npm packages already
+* execute arbitrary JS on install, so additional symlink-based isolation
+* here would not raise the trust boundary in any realistic threat model.
+*
+* @example
+* ```
+* sourceDir: "node_modules/@my-agent/skills/skills"
+*
+* node_modules/@my-agent/skills/skills/
+* ├── commit/
+* │   └── SKILL.md
+* └── review-pr/
+*     └── SKILL.md
+* ```
+*/
+function scanSourceDir(sourceDir) {
+	const skills = [];
+	const errors = [];
+	try {
+		let sourceStat;
+		try {
+			sourceStat = statSync(sourceDir);
+		} catch (error) {
+			if (isNodeError(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) errors.push({
+				path: sourceDir,
+				reason: "missing-source",
+				message: `Source directory does not exist: ${sourceDir}`
+			});
+			else errors.push({
+				path: sourceDir,
+				reason: "read-failed",
+				message: `Failed to stat source directory ${sourceDir}: ${errorMessage$1(error)}`
+			});
+			return {
+				skills,
+				errors
+			};
+		}
+		if (!sourceStat.isDirectory()) {
+			errors.push({
+				path: sourceDir,
+				reason: "missing-source",
+				message: `Source path is not a directory: ${sourceDir}`
+			});
+			return {
+				skills,
+				errors
+			};
+		}
+		const rootSkillMdPath = join(sourceDir, SKILL_MD);
+		const rootCheck = skillMdPresent(rootSkillMdPath);
+		if (rootCheck.kind === "error") {
+			errors.push({
+				path: sourceDir,
+				reason: "read-failed",
+				message: `Failed to check ${rootSkillMdPath}: ${rootCheck.message}`
+			});
+			return {
+				skills,
+				errors
+			};
+		}
+		if (rootCheck.kind === "present") {
+			pushResult(tryParseSkillDir(sourceDir, { enforceParentMatch: false }), skills, errors);
+			return {
+				skills,
+				errors
+			};
+		}
+		const entries = readdirSync(sourceDir, { withFileTypes: true });
+		for (const entry of entries) {
+			const skillDir = join(sourceDir, entry.name);
+			let isDir;
+			try {
+				isDir = statSync(skillDir).isDirectory();
+			} catch (error) {
+				if (isNodeError(error) && error.code === "ENOENT" && !entry.isSymbolicLink()) continue;
+				errors.push({
+					path: skillDir,
+					reason: "read-failed",
+					message: entry.isSymbolicLink() ? `Dangling symlink at ${skillDir}: ${errorMessage$1(error)}` : `Failed to stat ${skillDir}: ${errorMessage$1(error)}`
+				});
+				continue;
+			}
+			if (!isDir) continue;
+			const skillMdPath = join(skillDir, SKILL_MD);
+			const childCheck = skillMdPresent(skillMdPath);
+			if (childCheck.kind === "error") {
+				errors.push({
+					path: skillDir,
+					reason: "read-failed",
+					message: `Failed to check ${skillMdPath}: ${childCheck.message}`
+				});
+				continue;
+			}
+			if (childCheck.kind === "absent") continue;
+			pushResult(tryParseSkillDir(skillDir, { enforceParentMatch: true }), skills, errors);
+		}
+	} catch (error) {
+		errors.push({
+			path: sourceDir,
+			reason: "read-failed",
+			message: `Failed to scan ${sourceDir}: ${errorMessage$1(error)}`
+		});
+	}
+	skills.sort((a, b) => a.frontmatter.name < b.frontmatter.name ? -1 : a.frontmatter.name > b.frontmatter.name ? 1 : 0);
+	return {
+		skills,
+		errors
+	};
+}
+function tryParseSkillDir(dir, opts) {
+	const skillMdPath = join(dir, SKILL_MD);
+	let content;
+	try {
+		content = readFileSync(skillMdPath, "utf-8");
+	} catch (error) {
+		return {
+			path: dir,
+			reason: "read-failed",
+			message: `Failed to read ${skillMdPath}: ${errorMessage$1(error)}`
+		};
+	}
+	const { data, parseError } = parseFrontmatter(content);
+	if (parseError !== void 0) return {
+		path: dir,
+		reason: "parse-failed",
+		message: `Invalid SKILL.md frontmatter in ${dir}: YAML parse error: ${parseError}`
+	};
+	const result = skillFrontmatterSchema.safeParse(data);
+	if (!result.success) return {
+		path: dir,
+		reason: "parse-failed",
+		message: `Invalid SKILL.md frontmatter in ${dir}: ${result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ")}`
+	};
+	if (opts.enforceParentMatch) {
+		const parent = basename(dir);
+		if (parent !== result.data.name) return {
+			path: dir,
+			reason: "name-mismatch",
+			message: `Skill name "${result.data.name}" does not match directory "${parent}"`,
+			skillName: result.data.name
+		};
+	}
+	return {
+		frontmatter: result.data,
+		sourcePath: dir,
+		rawContent: content
+	};
+}
+function pushResult(value, skills, errors) {
+	if ("frontmatter" in value) skills.push(value);
+	else errors.push(value);
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function isNodeError(error) {
+	return error instanceof Error && typeof error.code === "string";
+}
+function skillMdPresent(path) {
+	try {
+		lstatSync(path);
+		return { kind: "present" };
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "absent" };
+		return {
+			kind: "error",
+			message: errorMessage$1(error)
+		};
+	}
+}
+
+//#endregion
+//#region src/skill/commands.ts
+/**
+* Stream scan errors. Per-error `logger.warn` writes to stderr (so a
+* malformed source SKILL.md is always loud), and trailing `logger.info`
+* summary lines echo to stdout — important for pipelines that consume
+* only stdout from the CLI. Directory-level failures (`missing-source`,
+* or per-entry failures on the source directory itself) get their own
+* stdout summary so a stdout-only consumer can tell apart "scan failed"
+* from a legitimate empty bundle.
+*
+* `silentStdout` suppresses only the stdout summary lines (per-error
+* stderr warnings still fire). Used by `skills list --json` so the
+* machine-readable JSON output on stdout stays parseable.
+*/
+function logScanErrors(errors, opts = {}) {
+	let skipped = 0;
+	let directoryFailed = false;
+	for (const err of errors) {
+		if (err.reason === "missing-source" || err.path === opts.sourceDir) {
+			directoryFailed = true;
+			logger.warn(`Failed to scan source directory ${err.path}: ${err.message}`);
+			continue;
+		}
+		skipped += 1;
+		logger.warn(`Skipping skill at ${err.path}: ${err.message}`);
+	}
+	if (opts.silentStdout) return;
+	if (skipped > 0) logger.info(`${symbols.warning} Skipped ${skipped} skill(s) due to scan errors (see warnings above).`);
+	if (directoryFailed) logger.info(`${symbols.warning} Source directory scan failed (see warnings above); subsequent operations may be skipped.`);
+}
+/**
+* Did the scan fail authoritatively at the directory level? Used by
+* commands to distinguish "legitimately empty source" from "scan
+* couldn't enumerate the source", so success-path summaries
+* ("No skills found", "no skills bundled") don't mask a config error.
+*/
+function scanFailedAtRoot(result, sourceDir) {
+	const directoryScanFailed = result.errors.some((e) => e.reason === "missing-source" || e.path === sourceDir);
+	const allSkillsInvalid = result.errors.length > 0 && result.skills.length === 0;
+	return directoryScanFailed || allSkillsInvalid;
+}
+function loadSkills(options, logOpts = {}) {
+	const result = scanSourceDir(options.sourceDir);
+	logScanErrors(result.errors, {
+		...logOpts,
+		sourceDir: options.sourceDir
+	});
+	return result;
+}
+/**
+* Build the metadata for `--exclude` honouring the configured alias.
+* `undefined` alias means `arg()` is called without an alias key.
+*/
+function excludeArgMeta(options) {
+	const meta = { description: "Skill names to exclude from sync" };
+	if (options.excludeAlias !== void 0) meta.alias = options.excludeAlias;
+	return meta;
+}
+/**
+* Create the `skills sync` subcommand.
+*
+* Removes and reinstalls all skills discovered in sourceDir. Skills owned
+* by this CLI that are no longer present in sourceDir are also removed so
+* stale skills do not linger after the CLI drops them from its bundle.
+*/
+function createSkillSyncCommand(resolved) {
+	return defineCommand({
+		name: "sync",
+		description: "Remove and reinstall all skills from source",
+		args: z.object({
+			exclude: arg(z.array(z.string()).default([]), excludeArgMeta(resolved)),
+			verbose: arg(z.boolean().default(false), {
+				alias: "v",
+				description: "Print install paths and modes"
+			})
+		}),
+		run(args) {
+			const { skills: allSkills, errors } = loadSkills(resolved);
+			const stamp = resolved.stamp;
+			const sourceNamesAll = new Set(allSkills.map((s) => s.frontmatter.name));
+			const ownedInstalled = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
+			const unknownExclude = Array.from(new Set(args.exclude)).filter((n) => !sourceNamesAll.has(n) && !ownedInstalled.has(n));
+			if (unknownExclude.length > 0) {
+				const subject = unknownExclude.length === 1 ? "Skill" : "Skills";
+				const quoted = unknownExclude.map((n) => JSON.stringify(n)).join(", ");
+				throw new Error(`--exclude: ${subject} ${quoted} not found in source directory or among installed skills.\n` + formatSkillUniverse({
+					source: allSkills,
+					installed: ownedInstalled
+				}));
+			}
+			const excluded = new Set(args.exclude);
+			const skills = allSkills.filter((s) => !excluded.has(s.frontmatter.name));
+			const rootScanFailed = scanFailedAtRoot({
+				skills: allSkills,
+				errors
+			}, resolved.sourceDir);
+			let removed = 0;
+			if (!rootScanFailed) {
+				const sourceNames = new Set(skills.map((s) => s.frontmatter.name));
+				const erroredSlotNames = /* @__PURE__ */ new Set();
+				for (const err of errors) {
+					if (err.path === resolved.sourceDir) continue;
+					erroredSlotNames.add(basename(err.path));
+					if (err.skillName !== void 0) erroredSlotNames.add(err.skillName);
+				}
+				for (const orphan of ownedInstalled) {
+					if (sourceNames.has(orphan) || excluded.has(orphan) || erroredSlotNames.has(orphan)) continue;
+					removeOwnedSkill(orphan, stamp, resolved.cwd, resolved.sourceDir);
+					removed += 1;
+				}
+			}
+			let installed = 0;
+			for (const skill of skills) {
+				addSkill(skill, stamp, resolved, args.verbose);
+				installed += 1;
+			}
+			if (installed === 0 && removed === 0) {
+				const reason = rootScanFailed ? "source directory scan failed; see warnings" : allSkills.length > 0 && skills.length === 0 ? "all skills excluded" : "no skills bundled";
+				logger.info(`No skills installed (${reason}).`);
+			} else logger.info(`Sync complete: ${installed} installed, ${removed} removed.`);
+		}
+	});
+}
+/**
+* Create the `skills add` subcommand.
+*
+* Installs skills from sourceDir. Accepts zero or more skill names; with no
+* names, installs every skill in source. With one or more names, every name
+* is validated against sourceSkills up-front so a typo never silently
+* proceeds with the valid neighbours — a single unknown name aborts the run
+* and lists every unknown name at once. Duplicates are deduplicated.
+*/
+function createSkillAddCommand(resolved) {
+	return defineCommand({
+		name: "add",
+		aliases: ["install"],
+		description: "Install skills from source",
+		args: z.object({
+			name: arg(z.array(z.string()).default([]), {
+				positional: true,
+				description: "Skill name(s) to install (default: all)",
+				placeholder: "NAME"
+			}),
+			verbose: arg(z.boolean().default(false), {
+				alias: "v",
+				description: "Print install paths and modes"
+			})
+		}),
+		run(args) {
+			const scanResult = loadSkills(resolved);
+			const sourceSkills = scanResult.skills;
+			const stamp = resolved.stamp;
+			if (args.name.length > 0) {
+				const known = new Set(sourceSkills.map((s) => s.frontmatter.name));
+				const requested = Array.from(new Set(args.name));
+				const unknown = requested.filter((n) => !known.has(n));
+				if (unknown.length > 0) {
+					const subject = unknown.length === 1 ? "Skill" : "Skills";
+					const quoted = unknown.map((n) => JSON.stringify(n)).join(", ");
+					throw new Error(`${subject} ${quoted} not found in source directory.\n` + formatSkillUniverse({ source: sourceSkills }));
+				}
+				const wanted = new Set(requested);
+				for (const skill of sourceSkills) if (wanted.has(skill.frontmatter.name)) addSkill(skill, stamp, resolved, args.verbose);
+				return;
+			}
+			if (sourceSkills.length === 0) {
+				if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("No skills installed (source directory scan failed; see warnings).");
+				else logger.info("No skills found in source directory.");
+				return;
+			}
+			for (const skill of sourceSkills) addSkill(skill, stamp, resolved, args.verbose);
+		}
+	});
+}
+/**
+* Create the `skills remove` subcommand.
+*
+* Removes installed skills. Defaults to all skills discovered in sourceDir
+* if no name is given. Only skills stamped with this CLI's ownership
+* (`metadata["politty-cli"] === "{package}:{cli}"`) are removed — skills
+* another tool installed are left untouched.
+*/
+function createSkillRemoveCommand(resolved) {
+	return defineCommand({
+		name: "remove",
+		aliases: ["uninstall"],
+		description: "Remove installed skills",
+		args: z.object({ name: arg(z.string().optional(), {
+			positional: true,
+			description: "Skill name to remove (default: all)",
+			placeholder: "NAME"
+		}) }),
+		run(args) {
+			const scanResult = loadSkills(resolved);
+			const sourceSkills = scanResult.skills;
+			const stamp = resolved.stamp;
+			if (args.name) {
+				if (sourceSkills.some((s) => s.frontmatter.name === args.name)) findOrThrow(sourceSkills, args.name);
+				if (!removeOwnedSkill(args.name, stamp, resolved.cwd, resolved.sourceDir)) if (slotPresent(args.name, resolved.cwd)) logger.info(`${args.name} is installed without a ${OWNERSHIP_METADATA_KEY} stamp this CLI recognises; refusing to remove. Remove .agents/skills/${args.name} manually if intended.`);
+				else {
+					const installed = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
+					logger.info(`${args.name} is not installed; nothing to remove.\n` + formatSkillUniverse({ installed }));
+				}
+				return;
+			}
+			if (sourceSkills.length === 0) {
+				if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("No skills found (source directory scan failed; see warnings); nothing to remove.");
+				else logger.info("No skills found in source directory; nothing to remove.");
+				return;
+			}
+			let removed = 0;
+			for (const skill of sourceSkills) if (removeOwnedSkill(skill.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir)) removed += 1;
+			if (removed === 0) logger.info("No installed skills owned by this CLI; nothing to remove.");
+		}
+	});
+}
+function listStatus(name, expectedOwnership, cwd, sourceDir) {
+	let owner;
+	try {
+		owner = readInstalledOwnership(name, cwd);
+	} catch (error) {
+		logger.warn(`Failed to read ownership for installed skill ${name}: ${errorMessage(error)}`);
+		return "unreadable";
+	}
+	if (owner === expectedOwnership) return "installed";
+	if (owner !== null) return "foreign";
+	if (!hasInstalledSkill(name, cwd)) {
+		const canonical = resolve(cwd, AGENTS_SKILLS_DIR, name);
+		if (isDanglingSymlink(canonical) && danglingRoutesToSource(canonical, sourceDir)) return "missing";
+		return slotPresent(name, cwd) ? "unstamped" : "not-installed";
+	}
+	return "unstamped";
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function slotPresent(name, cwd) {
+	try {
+		lstatSync(resolve(cwd, AGENTS_SKILLS_DIR, name));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Create the `skills list` subcommand.
+*
+* Lists available skills from the source directory.
+*/
+function createSkillListCommand(resolved) {
+	return defineCommand({
+		name: "list",
+		description: "List available skills from source",
+		args: z.object({ json: arg(z.boolean().default(false), { description: "Output as JSON" }) }),
+		run(args) {
+			const scanResult = loadSkills(resolved, { silentStdout: args.json });
+			const sourceSkills = scanResult.skills;
+			const stamp = resolved.stamp;
+			if (args.json) {
+				console.log(JSON.stringify(sourceSkills.map((s) => ({
+					name: s.frontmatter.name,
+					description: s.frontmatter.description,
+					owner: s.frontmatter.metadata?.["politty-cli"] ?? null,
+					expectedOwner: stamp,
+					status: listStatus(s.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir),
+					sourcePath: s.sourcePath
+				}))));
+				return;
+			}
+			if (sourceSkills.length === 0) {
+				if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("Source directory scan failed; see warnings.");
+				else logger.info("No skills found in source directory.");
+				return;
+			}
+			logger.info("Available skills:");
+			for (const skill of sourceSkills) {
+				const status = listStatus(skill.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir);
+				logger.info(`  ${skill.frontmatter.name.padEnd(20)} ${status.padEnd(14)} ${skill.frontmatter.description}`);
+			}
+		}
+	});
+}
+function findOrThrow(skills, name) {
+	const skill = skills.find((s) => s.frontmatter.name === name);
+	if (!skill) {
+		const available = skills.map((s) => s.frontmatter.name).join(", ") || "<none>";
+		throw new Error(`Skill "${name}" not found in source directory. Available: ${available}`);
+	}
+	return skill;
+}
+/**
+* Render skill-name lists for typo-error diagnostics. Each command lists
+* only the universe its argument actually accepts so the suggestions
+* match what the user can legitimately retype:
+*   - `add` — source only.
+*   - `remove` — installed only.
+*   - `sync --exclude` — both (a source skill skips its install, an
+*     installed-owned orphan is preserved from removal).
+* Empty sections render as `<none>` so the user can tell apart "I don't
+* know about any" from "the message forgot a section".
+*/
+function formatSkillUniverse(opts) {
+	const parts = [];
+	if (opts.source !== void 0) parts.push(`  Source: ${opts.source.map((s) => s.frontmatter.name).join(", ") || "<none>"}`);
+	if (opts.installed !== void 0) parts.push(`  Installed: ${[...opts.installed].sort().join(", ") || "<none>"}`);
+	return parts.join("\n");
+}
+function addSkill(skill, expectedOwnership, resolved, verbose) {
+	const name = skill.frontmatter.name;
+	const cwd = resolved.cwd;
+	const mode = resolved.mode;
+	const sourceOwnership = skill.frontmatter.metadata?.["politty-cli"] ?? null;
+	if (sourceOwnership !== expectedOwnership) throw new Error(`Refusing to install "${name}": source SKILL.md declares metadata.${OWNERSHIP_METADATA_KEY}=${JSON.stringify(sourceOwnership)}, expected ${JSON.stringify(expectedOwnership)}.`);
+	const actual = readInstalledOwnership(name, cwd);
+	if (actual !== null && actual !== expectedOwnership) throw new Error(`Refusing to install "${name}": owned by ${JSON.stringify(actual)}, not ${JSON.stringify(expectedOwnership)}. Check metadata.${OWNERSHIP_METADATA_KEY} in .agents/skills/${name}/SKILL.md.`);
+	const canonical = resolve(cwd, AGENTS_SKILLS_DIR, name);
+	const danglingOurs = isDanglingSymlink(canonical) && danglingRoutesToSource(canonical, resolved.sourceDir);
+	if (actual === null && slotPresent(name, cwd) && !danglingOurs) throw new Error(`Refusing to install "${name}": .agents/skills/${name} exists without a ${OWNERSHIP_METADATA_KEY} stamp, so it was not installed by this CLI. Remove it manually (or add the stamp to take ownership) before running "skills add".`);
+	installSkill(skill, cwd, mode === void 0 ? {} : { mode });
+	logger.info(`${symbols.success} Installed ${name}`);
+	if (verbose) {
+		const effectiveMode = mode ?? "symlink";
+		logger.info(`    mode=${effectiveMode}  path=${canonical}`);
+	}
+}
+/**
+* Remove a skill only if it belongs to this CLI (ownership stamp matches
+* `{package}:{cli}`). Returns `true` when something was actually removed,
+* `false` when the skill was not installed (allowing callers to surface a
+* "nothing to remove" message).
+*
+* A broken canonical symlink (`.agents/skills/<name>` exists as a symlink
+* but its target does not) is also cleaned up here, even though
+* `readInstalledOwnership` returns `null` in that case — the slot is in
+* this CLI's namespace and unlinking a dangling symlink can never delete
+* user data. This matches the `status: "missing"` listed by `skills list`.
+*
+* Throws when the skill exists but is owned by someone else — callers
+* like `sync` that iterate silently would otherwise clobber user data.
+*/
+function removeOwnedSkill(name, expectedOwnership, cwd, sourceDir) {
+	const actual = readInstalledOwnership(name, cwd);
+	if (actual === null) {
+		if (cleanupBrokenSlot(name, cwd, sourceDir)) {
+			logger.info(`${symbols.success} Removed ${name} (broken symlink)`);
+			return true;
+		}
+		return false;
+	}
+	if (actual !== expectedOwnership) throw new Error(`Refusing to remove "${name}": owned by ${JSON.stringify(actual)}, not ${JSON.stringify(expectedOwnership)}. Check metadata.${OWNERSHIP_METADATA_KEY} in .agents/skills/${name}/SKILL.md.`);
+	uninstallSkill(name, cwd, { expectedOwnership });
+	logger.info(`${symbols.success} Removed ${name}`);
+	return true;
+}
+/**
+* If `.agents/skills/<name>` is a dangling symlink that still routes to
+* this CLI's source directory, unlink it (and any agent-specific
+* dangling-symlink slots that route through it). Returns `true` when the
+* canonical slot was cleaned.
+*
+* A dangling canonical whose target lies outside our source directory
+* (e.g. a foreign politty-based CLI's stale install in the shared
+* `.agents/skills/` namespace) is left alone — without an ownership
+* stamp to read, we can't prove the slot belongs to this CLI. Live
+* symlinks (target still resolves) go through the normal stamp-checked
+* path.
+*/
+function cleanupBrokenSlot(name, cwd, sourceDir) {
+	const canonical = resolve(cwd, AGENTS_SKILLS_DIR, name);
+	if (!isDanglingSymlink(canonical)) return false;
+	if (!danglingRoutesToSource(canonical, sourceDir)) return false;
+	for (const target of SYMLINK_TARGETS) {
+		const agentSlot = resolve(cwd, target, name);
+		if (!isDanglingSymlink(agentSlot)) continue;
+		if (symlinkRoutesTo(agentSlot, canonical)) unlinkSync(agentSlot);
+	}
+	unlinkSync(canonical);
+	return true;
+}
+/**
+* Does the dangling symlink at `canonical` still route into `sourceDir`?
+* Used to confirm a stale `.agents/skills/<name>` belongs to this CLI
+* before we unlink it in the shared namespace.
+*
+* The link target is resolved lexically (the path is dangling so
+* `realpathSync` on it would fail) against the symlink's own directory.
+* `sourceDir` is resolved through `resolveDeepestExisting` so the
+* comparison survives realpath remapping (macOS `/tmp` →
+* `/private/tmp`, a project mounted through a symlink, etc) *and* the
+* documented case where the configured source path itself no longer
+* exists (the source package was uninstalled — exactly the scenario
+* `status: "missing"` is meant to surface). Containment uses the same
+* boundary-aware `..`-only escape check as `installer.ts`'s
+* `pathsOverlap` so a sibling directory whose name happens to start
+* with `..` is not misclassified as outside.
+*/
+function danglingRoutesToSource(canonical, sourceDir) {
+	let raw;
+	try {
+		raw = readlinkSync(canonical);
+	} catch {
+		return false;
+	}
+	const absoluteTarget = isAbsolute(raw) ? raw : resolve(dirname(canonical), raw);
+	const rel = relative(resolveDeepestExisting(resolve(sourceDir)), resolveDeepestExisting(absoluteTarget));
+	if (isAbsolute(rel)) return false;
+	if (rel === ".." || rel.startsWith(`..${sep}`)) return false;
+	return true;
+}
+function resolveDeepestExisting(p) {
+	let cur = p;
+	const tail = [];
+	while (true) try {
+		const r = realpathSync(cur);
+		return tail.length === 0 ? r : resolve(r, ...tail.reverse());
+	} catch {
+		const parent = dirname(cur);
+		if (parent === cur) return p;
+		tail.push(cur.slice(parent.length).replace(/^[/\\]+/, ""));
+		cur = parent;
+	}
+}
+/**
+* Does the symlink at `slot` route to `expected` (lexically, with a
+* realpath fallback)? Mirrors `symlinkRoutesTo` in `installer.ts` —
+* deliberately a local duplicate so `commands.ts` does not depend on the
+* installer's private helpers.
+*/
+function symlinkRoutesTo(slot, expected) {
+	let raw;
+	try {
+		raw = readlinkSync(slot);
+	} catch {
+		return false;
+	}
+	const resolvedTarget = isAbsolute(raw) ? raw : resolve(dirname(slot), raw);
+	if (resolvedTarget === expected) return true;
+	try {
+		return realpathSync(resolvedTarget) === realpathSync(expected);
+	} catch {
+		return false;
+	}
+}
+function isDanglingSymlink(path) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch {
+		return false;
+	}
+	if (!stat.isSymbolicLink()) return false;
+	return !existsSync(path);
+}
+/**
+* Enumerate installed skills that should be reconciled by `sync`'s orphan
+* cleanup: skills carrying this CLI's ownership stamp, plus dangling
+* canonical symlinks whose link target routes back to this CLI's source
+* directory. `.agents/skills/` is a namespace shared with every other
+* politty-based CLI, so a dangling canonical symlink without a routing
+* match likely belongs to a foreign CLI whose source was uninstalled —
+* including it would let `sync` unlink it under our authority.
+*/
+function findOwnedInstalledSkills(expectedOwnership, cwd, sourceDir) {
+	const base = resolve(cwd, AGENTS_SKILLS_DIR);
+	const owned = [];
+	let entries;
+	try {
+		entries = readdirSync(base, { withFileTypes: true });
+	} catch (err) {
+		const code = err.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return owned;
+		logger.warn(`Failed to enumerate ${base}: ${err instanceof Error ? err.message : String(err)}`);
+		return owned;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+		if (entry.name.length < 1 || entry.name.length > 64) continue;
+		if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(entry.name)) continue;
+		let owner;
+		try {
+			owner = readInstalledOwnership(entry.name, cwd);
+		} catch (err) {
+			logger.warn(`Failed to read ownership for ${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
+			continue;
+		}
+		if (owner === expectedOwnership) {
+			owned.push(entry.name);
+			continue;
+		}
+		const canonical = resolve(base, entry.name);
+		if (owner === null && isDanglingSymlink(canonical) && danglingRoutesToSource(canonical, sourceDir)) owned.push(entry.name);
+	}
+	return owned;
+}
+
+//#endregion
+//#region src/skill/options.ts
+/** Default short alias for `skills sync --exclude`. */
+const DEFAULT_EXCLUDE_ALIAS = "x";
+/** Marker files identifying a project root for find-up. */
+const PROJECT_ROOT_MARKERS = [".git", "package.json"];
+/**
+* Resolve user-facing {@link SkillCommandOptions} into the concrete shape
+* each subcommand consumes. Defaults applied here:
+*
+* - `cwd` — `findProjectRoot(process.cwd()) ?? process.cwd()`.
+* - `excludeAlias` — `"x"` unless overridden via
+*   `flags.exclude.alias` (string) or disabled (`false`).
+* - `descriptionAppend` — a one-line hint mentioning the skills
+*   subcommands. Pass an explicit string to override or `false` to opt out.
+*/
+function resolveSkillOptions(options, cliName) {
+	return {
+		sourceDir: options.sourceDir,
+		package: options.package,
+		mode: options.mode,
+		cwd: resolveCwd(options.cwd),
+		excludeAlias: resolveExcludeAlias(options.flags?.exclude?.alias),
+		descriptionAppend: resolveDescriptionAppend(options.descriptionAppend, cliName),
+		stamp: `${options.package}:${cliName}`
+	};
+}
+function resolveCwd(override) {
+	if (override !== void 0) return resolve(override);
+	const start = process.cwd();
+	return findProjectRoot(start) ?? start;
+}
+/**
+* Walk up from `start` looking for the closest directory containing one
+* of {@link PROJECT_ROOT_MARKERS}. Returns `null` when the walk reaches
+* the filesystem root without a hit.
+*
+* `.git` matches both repositories (a directory) and worktrees / submodule
+* checkouts (a file pointing at the parent gitdir) because `existsSync`
+* accepts either.
+*/
+function findProjectRoot(start) {
+	let dir = resolve(start);
+	while (true) {
+		for (const marker of PROJECT_ROOT_MARKERS) if (existsSync(resolve(dir, marker))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+function resolveExcludeAlias(value) {
+	if (value === false) return void 0;
+	if (typeof value === "string") return value;
+	return DEFAULT_EXCLUDE_ALIAS;
+}
+function resolveDescriptionAppend(value, cliName) {
+	if (value === false) return false;
+	if (typeof value === "string") return value;
+	return `Manage agent skills with \`${cliName} skills <add|sync|remove|list>\`.`;
+}
+
+//#endregion
+//#region src/skill/types.ts
+/**
+* All kinds of scan failure, as a runtime tuple so callers can exhaustively
+* iterate (e.g. for message tables). Derived {@link ScanErrorReason} stays
+* the single source of truth for the type-level enum.
+*/
+const SCAN_ERROR_REASONS = [
+	"parse-failed",
+	"name-mismatch",
+	"read-failed",
+	"missing-source"
+];
+
+//#endregion
+//#region src/skill/index.ts
+/**
+* Skill management module for coding agent CLIs.
+*
+* Provides source-directory scanning and symlink-based (or copy-based)
+* installation of SKILL.md-based agent skills, validated against the
+* Agent Skills specification (https://agentskills.io/specification).
+*
+* Provenance of politty-managed installs is recorded under
+* `metadata["politty-cli"]` as `"{packageName}:{cliName}"`, so
+* `skills remove` can safely refuse to delete skills that belong to
+* another tool.
+*
+* @example
+* ```typescript
+* import { dirname, resolve } from "node:path";
+* import { fileURLToPath } from "node:url";
+* import { defineCommand, runMain } from "politty";
+* import { withSkillCommand } from "politty/skill";
+*
+* const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
+*
+* const cli = withSkillCommand(
+*   defineCommand({
+*     name: "my-agent",
+*     description: "My coding agent CLI",
+*     subCommands: {
+*       run: runCommand,
+*     },
+*   }),
+*   { sourceDir, package: "@my-agent/skills" },
+* );
+*
+* runMain(cli);
+* ```
+*
+* SKILL.md format (spec-compliant):
+* ```markdown
+* ---
+* name: commit
+* description: Git commit message generation
+* license: MIT
+* metadata:
+*   politty-cli: "@my-agent/skills:my-agent"
+* ---
+* # Instructions for the agent...
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Wrap a command with a `skills` subcommand for managing SKILL.md-based skills.
+*
+* Adds `skills sync`, `skills add`, `skills remove`, and `skills list`.
+* The install materialization is controlled by `options.mode`
+* (see {@link SkillCommandOptions}):
+*
+* - `"symlink"` (default) — symlink the source into place. Source updates
+*   propagate live. Install errors out with guidance to retry with `"copy"`
+*   when `symlinkSync` fails (e.g. Windows without Developer Mode).
+* - `"copy"` — recursive copy. Source updates require re-running sync.
+*
+* Under both modes the canonical slot is `.agents/skills/<name>` and each
+* agent-specific directory (e.g. `.claude/skills/<name>`) is populated
+* from that canonical slot. politty never writes to `SKILL.md`. The
+* ownership stamp `metadata["politty-cli"] = "{package}:{cliName}"` must
+* be authored by the skill package itself; `add` and `sync` verify it
+* before installing and `remove` / `sync` consult it before deleting, so
+* this CLI never clobbers skills another tool installed.
+*
+* @throws if `command.subCommands.skills` already exists — silently
+*   overwriting it would hide a configuration bug.
+*/
+function withSkillCommand(command, options) {
+	if (command.subCommands && Object.hasOwn(command.subCommands, "skills")) throw new Error(`withSkillCommand: command "${command.name}" already defines a "skills" subcommand.`);
+	const resolved = resolveSkillOptions(options, command.name);
+	const skillsSubCommand = defineCommand({
+		name: "skills",
+		description: "Manage agent skills",
+		subCommands: {
+			sync: createSkillSyncCommand(resolved),
+			add: createSkillAddCommand(resolved),
+			remove: createSkillRemoveCommand(resolved),
+			list: createSkillListCommand(resolved)
+		}
+	});
+	return {
+		...command,
+		description: appendDescription(command.description, resolved.descriptionAppend),
+		subCommands: {
+			...command.subCommands,
+			skills: skillsSubCommand
+		}
+	};
+}
+/**
+* Append the configured skills hint to the root command's description.
+*
+* Returns the original description unchanged when `append` is `false` or
+* empty. When the existing description already ends with the same hint,
+* skip the append so re-wrapping (e.g. in tests) does not duplicate it.
+*
+* The separator is a blank line so help renderers display the hint as
+* its own paragraph — a single space would run the hint into the host
+* description (especially when the description has no trailing period).
+*/
+function appendDescription(existing, append) {
+	if (append === false || append === "") return existing;
+	if (!existing) return append;
+	if (existing.endsWith(append)) return existing;
+	return `${existing}\n\n${append}`;
+}
+
+//#endregion
+export { OWNERSHIP_METADATA_KEY, SCAN_ERROR_REASONS, hasInstalledSkill, installSkill, parseFrontmatter, parseSkillMd, readInstalledOwnership, scanSourceDir, skillFrontmatterSchema, uninstallSkill, withSkillCommand };
+//# sourceMappingURL=index.js.map