@politty/zod 0.0.0

package/dist/skill.d.ts

@@ -0,0 +1,608 @@
+import { Z as UnknownKeysMode, b as ArgsSchema, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
+import { z } from "zod";
+//#region ../core/src/skill/types.d.ts
+/**
+ * SKILL.md frontmatter metadata, validated against the Agent Skills
+ * specification (https://agentskills.io/specification). Unknown fields are
+ * preserved (passthrough) so spec extensions and vendor keys round-trip
+ * intact.
+ *
+ * Provenance for politty-managed installs is recorded under
+ * `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
+ */
+interface SkillFrontmatter {
+  /** Skill identifier. Lowercase alphanumerics + hyphens, 1..64 chars. */
+  name: string;
+  /** Human-readable description (1..1024 chars). */
+  description: string;
+  /** SPDX license identifier or free-form string. */
+  license?: string;
+  /** Runtime / tool compatibility string (<=500 chars). */
+  compatibility?: string;
+  /** Metadata map (spec: string keys, string values). */
+  metadata?: Record<string, string>;
+  /** Experimental spec field. */
+  "allowed-tools"?: string;
+  /** Unknown fields are preserved verbatim. */
+  [key: string]: unknown;
+}
+/**
+ * A skill discovered from a source directory (npm package).
+ */
+interface DiscoveredSkill {
+  /** Parsed frontmatter metadata */
+  frontmatter: SkillFrontmatter;
+  /** Path to the directory containing SKILL.md */
+  sourcePath: string;
+  /** Raw SKILL.md content (frontmatter + body) */
+  rawContent: string;
+}
+/**
+ * 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.
+ */
+declare const SCAN_ERROR_REASONS: readonly ["parse-failed", "name-mismatch", "read-failed", "missing-source"];
+/** Kind of problem encountered by {@link scanSourceDir}. */
+type ScanErrorReason = (typeof SCAN_ERROR_REASONS)[number];
+/**
+ * A non-fatal problem encountered while scanning a source directory.
+ *
+ * Scan errors (invalid frontmatter, name/parent-dir mismatch, unreadable
+ * files) are collected rather than thrown so that a single malformed skill
+ * does not hide the rest from CLI commands.
+ */
+interface ScanError {
+  /** Directory that produced the error. */
+  path: string;
+  /** Kind of problem encountered. */
+  reason: ScanErrorReason;
+  /** Human-readable detail, suitable for logging. */
+  message: string;
+  /**
+   * Parsed frontmatter `name`, when the scan got far enough to read it.
+   * Currently populated only for `name-mismatch` — both the directory
+   * basename and this frontmatter name correspond to plausible existing
+   * install slot names (depending on which side the user just renamed),
+   * so `sync`'s orphan-retention guard needs both to avoid reaping an
+   * installed slot belonging to a source skill that failed this scan.
+   */
+  skillName?: string;
+}
+/**
+ * Result of scanning a source directory for SKILL.md files.
+ */
+interface ScanResult {
+  /** Valid, spec-compliant skills. */
+  skills: DiscoveredSkill[];
+  /** Directories that looked like skills but failed validation. */
+  errors: ScanError[];
+}
+/**
+ * How an install materializes skill files under `.agents/skills/<name>`
+ * and each `SYMLINK_TARGETS` entry.
+ *
+ * - `"symlink"` (default): symlink the source into place. Source updates
+ *   propagate live. Throws with guidance to retry with `"copy"` when
+ *   `symlinkSync` fails (e.g. Windows without Developer Mode, filesystems
+ *   that do not support symlinks).
+ * - `"copy"`: recursive copy. Source updates require re-running `skills
+ *   sync`. Works on any filesystem, trades liveness for portability.
+ */
+type InstallMode = "symlink" | "copy";
+/** Options for {@link installSkill}. */
+interface InstallSkillOptions {
+  /** Install materialization strategy. Default: `"symlink"`. */
+  mode?: InstallMode;
+}
+/** Options for {@link uninstallSkill}. */
+interface UninstallSkillOptions {
+  /**
+   * If set, `uninstallSkill` also removes a real directory at the install
+   * path when its SKILL.md's `metadata["politty-cli"]` matches this stamp
+   * (a copy-mode install this CLI owns). Without this option, only
+   * symlinks are removed — real directories are assumed to be legacy or
+   * manual installs and left untouched.
+   */
+  expectedOwnership?: string;
+}
+/**
+ * Per-flag overrides for the built-in skill subcommand options.
+ *
+ * Pass through {@link SkillCommandOptions.flags} to resolve collisions with
+ * CLI-level global flags. Setting `alias` to `false` disables the short
+ * alias entirely; passing a string renames it.
+ */
+interface SkillFlagOverrides {
+  /**
+   * `--exclude` flag on `skills sync`. The default short alias is `-x`.
+   */
+  exclude?: {
+    alias?: string | false;
+  };
+  /**
+   * `--verbose` flag shared by `skills add` and `skills sync`. The default
+   * short alias is `-v`.
+   *
+   * This is independent of {@link SkillCommandOptions.globalArgs}'s
+   * field-name auto-detection (which drops the flag entirely when the
+   * host's `globalArgs` already defines a `verbose` field). `alias` instead
+   * resolves a *short-alias-only* collision — e.g. the host's `globalArgs`
+   * uses `-v` for an unrelated flag (not named `verbose`), so auto-detection
+   * doesn't apply, but the single-character alias still collides.
+   */
+  verbose?: {
+    alias?: string | false;
+  };
+}
+/**
+ * Options for `withSkillCommand`.
+ */
+interface SkillCommandOptions {
+  /**
+   * Source directory containing SKILL.md files.
+   *
+   * Each subdirectory whose name matches its `SKILL.md` frontmatter `name`
+   * is treated as a skill. Symlinks within the source tree are followed.
+   *
+   * @example
+   * ```typescript
+   * // Resolves to ../skills relative to the current file.
+   * // Works from both src/ and dist/ if at the same depth.
+   * const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
+   * ```
+   */
+  sourceDir: string;
+  /**
+   * npm package name that owns this CLI's bundled skills.
+   *
+   * Each source `SKILL.md` must pre-declare
+   * `metadata["politty-cli"]: "{package}:{cliName}"`. The `skills add` and
+   * `skills sync` subcommands verify this stamp before installing — two
+   * tools managing skills in the same project cannot accidentally clobber
+   * each other. `installSkill` itself does not compare ownership;
+   * programmatic callers that bypass `withSkillCommand` are responsible
+   * for matching the stamp against their own `{package}:{cliName}` up
+   * front. (In `mode: "copy"`, `installSkill` additionally requires
+   * *some* `politty-cli` stamp on the source and throws otherwise — the
+   * caller-side ownership check naturally satisfies that precondition.)
+   */
+  package: string;
+  /**
+   * Default install mode for the `skills add` and `skills sync` commands.
+   * Defaults to `"symlink"` — install fails with a clear error on
+   * filesystems without symlink support (e.g. Windows without Developer
+   * Mode). Set to `"copy"` to always copy. See {@link InstallMode}.
+   */
+  mode?: InstallMode;
+  /**
+   * Project root directory used by every `skills` subcommand for resolving
+   * `.agents/skills/...` install paths.
+   *
+   * Default: walk up from `process.cwd()` and use the first ancestor that
+   * contains `.git/` or `package.json`; fall back to `process.cwd()` when
+   * neither is found. This avoids creating `<sub>/.agents/skills/...` when
+   * the CLI is invoked from a subdirectory of the project.
+   *
+   * Pass an explicit absolute (or cwd-relative) path to override — for
+   * example, the directory of a CLI-specific config file.
+   */
+  cwd?: string;
+  /**
+   * The host CLI's global args schema — the same value passed to
+   * `runMain`/`runCommand`'s `globalArgs` option.
+   *
+   * When provided, `skills add`/`skills sync`'s `--verbose` and `skills
+   * list`'s `--json` are automatically omitted from their own schema if
+   * this schema already defines a same-named *non-positional boolean*
+   * field — no manual configuration needed, and the host's global flag of
+   * the same name takes over instead.
+   *
+   * A same-named field of another type (e.g. a string verbosity level)
+   * doesn't trigger this — the local boolean flag stays declared. However,
+   * politty itself independently rejects that combination: when
+   * `globalArgs` and a command's own schema declare a same-named field
+   * with different definitions, `runMain`/`runCommand` throws
+   * `FieldTypeConflictError` at parse time. {@link SkillFlagOverrides} can't
+   * help here — it only renames the short alias (`-v`/`-x`), not the long
+   * `--verbose`/`--json` field name itself, so the conflicting name stays
+   * either way. A host whose `globalArgs` uses a non-boolean `verbose`/
+   * `json` field must rename or remove that global field (or make it a
+   * plain boolean) instead.
+   *
+   * (Historical note: this omission used to also be required to work around
+   * a politty core bug where a global flag typed *before* the subcommand
+   * resolved correctly as a global value, but a same-named local field's
+   * own default would then overwrite it during the merge. That bug is
+   * fixed in politty core independently of this option — a same-named
+   * local and global field with *identical* definitions now resolves
+   * correctly regardless of position. This option still omits the local
+   * flag by default for simplicity: hosts don't need to duplicate the
+   * flag's definition on both schemas to get the expected behavior.)
+   *
+   * @example
+   * ```ts
+   * const globalArgs = z.object({
+   *   verbose: arg(z.boolean().default(false), { alias: "v" }),
+   * });
+   *
+   * const cli = withSkillCommand(baseCommand, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   globalArgs, // skills add/sync automatically drop their own --verbose
+   * });
+   *
+   * runMain(cli, { globalArgs }); // same schema, passed to the real entry point
+   * ```
+   */
+  globalArgs?: ArgsSchema;
+  /**
+   * Unknown-keys handling for the `add`/`sync`/`remove`/`list` arg schemas
+   * (applied uniformly to all four).
+   *
+   * - `"strip"` (default) — matches politty's own `z.object()` default:
+   *   an unrecognized flag prints a warning and its value is dropped from
+   *   the parsed args.
+   * - `"strict"` — an unrecognized flag is a hard error, matching a host
+   *   CLI that uses `z.strictObject()`/`.strict()` throughout.
+   * - `"passthrough"` — matches `z.object().passthrough()`: no warning,
+   *   and unlike `"strip"`, the unrecognized flag's value is *kept* on the
+   *   parsed args object under its raw CLI name (e.g. `args["some-flag"]`)
+   *   rather than dropped.
+   *
+   * This only governs flags the parser cannot attribute to *either* this
+   * subcommand's own schema or the host's `globalArgs` schema — a value
+   * that legitimately arrives via `globalArgs` (see
+   * {@link SkillCommandOptions.globalArgs}) is validated separately against
+   * that schema and merged in afterward, so it is never rejected here.
+   */
+  unknownKeys?: UnknownKeysMode;
+  /**
+   * Customize built-in subcommand flags. Use to resolve collisions with
+   * the CLI's global flags or to opt out of short aliases.
+   *
+   * @example
+   * ```ts
+   * // CLI already uses -x globally; rename the exclude alias.
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   flags: { exclude: { alias: "X" } },
+   * });
+   *
+   * // Disable the short alias entirely.
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   flags: { exclude: { alias: false } },
+   * });
+   * ```
+   */
+  flags?: SkillFlagOverrides;
+  /**
+   * Append a one-line skills usage hint to the wrapped command's
+   * `description` so `--help` advertises the skills subcommand.
+   *
+   * - `undefined` (default) — append a default hint mentioning the
+   *   available subcommands.
+   * - `string` — append this exact string instead.
+   * - `false` — leave the description untouched.
+   */
+  descriptionAppend?: string | false;
+  /**
+   * Override the primary (dispatched) name and aliases of `skills add` and
+   * `skills remove`. In each array, the *first* element becomes the
+   * subcommand's primary name; every element after it becomes an alias.
+   *
+   * Default: `add: ["add", "install"]`, `remove: ["remove", "uninstall"]`.
+   *
+   * Useful when a host CLI wants to rename these subcommands outright, drop
+   * the `install`/`uninstall` backward-compatibility aliases, add further
+   * aliases, or some combination of all three.
+   *
+   * @example
+   * ```ts
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   commandMap: {
+   *     add: ["setup", "add", "install"], // renamed to "setup"; "add"/"install" still work
+   *     remove: ["remove"], // no aliases at all
+   *   },
+   * });
+   * ```
+   */
+  commandMap?: {
+    /** Primary name + aliases for `skills add`. Default: `["add", "install"]`. */
+    add?: string[];
+    /** Primary name + aliases for `skills remove`. Default: `["remove", "uninstall"]`. */
+    remove?: string[];
+  };
+  /**
+   * Override the description text for the `skills` command and/or its
+   * built-in subcommands. Any key left unset keeps politty's default
+   * description for that command.
+   *
+   * Keys refer to the subcommand's *canonical role*, not its dispatched
+   * name — e.g. `descriptions.add` still applies after `commandMap.add`
+   * renames the subcommand to something else.
+   *
+   * @example
+   * ```ts
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   commandMap: { add: ["setup", "add", "install"] },
+   *   descriptions: {
+   *     skills: "Manage My Agent skills",
+   *     add: "Install My Agent skills", // still keyed by "add", not "setup"
+   *   },
+   * });
+   * ```
+   */
+  descriptions?: {
+    /** Description for the top-level `skills` command. Default: `"Manage agent skills"`. */
+    skills?: string;
+    /** Description for `skills sync`. Default: `"Remove and reinstall all skills from source"`. */
+    sync?: string;
+    /** Description for `skills add`. Default: `"Install skills from source"`. */
+    add?: string;
+    /** Description for `skills remove`. Default: `"Remove installed skills"`. */
+    remove?: string;
+    /** Description for `skills list`. Default: `"List available skills from source"`. */
+    list?: string;
+  };
+}
+/**
+ * Result of wrapping `T` with {@link withSkillCommand} — `T` with a
+ * `skills` entry added to (and required on) `subCommands`, so consumers can
+ * access `command.subCommands.skills` without an `as AnyCommand` cast.
+ */
+type WithSkillCommand<T extends AnyCommand> = T & {
+  subCommands: NonNullable<T["subCommands"]> & {
+    skills: AnyCommand;
+  };
+};
+//#endregion
+//#region ../core/src/skill/frontmatter.d.ts
+/**
+ * Result of parsing a SKILL.md file.
+ */
+interface ParsedSkillMd {
+  /** Parsed and validated frontmatter */
+  frontmatter: SkillFrontmatter;
+  /** Markdown body (content after frontmatter) */
+  body: string;
+  /** Full raw content */
+  rawContent: string;
+}
+/**
+ * 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` — 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"
+ * ```
+ */
+declare function parseFrontmatter(content: string): {
+  data: Record<string, unknown>;
+  body: string;
+  parseError?: string;
+};
+/**
+ * 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.
+ */
+declare function parseSkillMd(content: string): ParsedSkillMd | null;
+//#endregion
+//#region ../core/src/skill/installer.d.ts
+/**
+ * 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.
+ */
+declare const OWNERSHIP_METADATA_KEY = "politty-cli";
+/**
+ * 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.
+ */
+declare function installSkill(skill: DiscoveredSkill, cwd?: string, options?: InstallSkillOptions): void;
+/**
+ * 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.
+ */
+declare function uninstallSkill(name: string, cwd?: string, options?: UninstallSkillOptions): void;
+/**
+ * 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).
+ */
+declare function hasInstalledSkill(name: string, cwd?: string): boolean;
+/**
+ * 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.
+ */
+declare function readInstalledOwnership(name: string, cwd?: string): string | null;
+//#endregion
+//#region ../core/src/skill/scanner.d.ts
+/**
+ * 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
+ * ```
+ */
+declare function scanSourceDir(sourceDir: string): ScanResult;
+//#endregion
+//#region ../core/src/skill/index.d.ts
+/**
+ * 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.
+ */
+declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): WithSkillCommand<T>;
+//#endregion
+//#region src/skill-frontmatter-schema.d.ts
+/**
+ * Zod schema for SKILL.md frontmatter.
+ *
+ * @deprecated Kept as a public export of `politty/skill` for backwards
+ * compatibility. politty itself no longer validates frontmatter through
+ * this schema — see `validateSkillFrontmatter` in `frontmatter.ts`, which
+ * implements the same Agent Skills specification rules without a runtime
+ * zod dependency. Keep the two in sync when the spec changes.
+ *
+ * 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}"`.
+ */
+declare const skillFrontmatterSchema: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodString;
+  license: z.ZodOptional<z.ZodString>;
+  compatibility: z.ZodOptional<z.ZodString>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  "allowed-tools": z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+//#endregion
+export { type DiscoveredSkill, type InstallMode, type InstallSkillOptions, OWNERSHIP_METADATA_KEY, type ParsedSkillMd, SCAN_ERROR_REASONS, type ScanError, type ScanErrorReason, type ScanResult, type SkillCommandOptions, type SkillFlagOverrides, type SkillFrontmatter, type UninstallSkillOptions, type WithSkillCommand, hasInstalledSkill, installSkill, parseFrontmatter, parseSkillMd, readInstalledOwnership, scanSourceDir, skillFrontmatterSchema, uninstallSkill, withSkillCommand };