@crustjs/skills 0.0.3 → 0.0.4

package/README.md

@@ -106,6 +106,8 @@ crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --no-clean
 
 High-level API that runs the full pipeline: introspection, rendering, and writing to disk.
 
+The `meta.name` must be a valid skill name — lowercase alphanumeric with hyphens, 1–64 characters (validated against the [Agent Skills spec](https://agentskills.io/specification) pattern). Use `isValidSkillName()` to check before calling.
+
 ```ts
 import { generateSkill } from "@crustjs/skills";
 
@@ -114,6 +116,7 @@ const result = await generateSkill({
   meta: { name: "my-cli", description: "My CLI tool", version: "1.0.0" },
   outDir: "./dist",  // default: "."
   clean: true,       // default: true — removes existing skill dir first
+  force: false,      // default: false — throws SkillConflictError if dir exists without crust.json
 });
 
 // result.outputDir — absolute path to the generated skill directory
@@ -147,6 +150,55 @@ for (const file of files) {
 }
 ```
 
+### `isValidSkillName(name)`
+
+Validates a skill name against the [Agent Skills spec](https://agentskills.io/specification) pattern: 1–64 lowercase alphanumeric characters and hyphens, no leading/trailing/consecutive hyphens.
+
+```ts
+import { isValidSkillName } from "@crustjs/skills";
+
+isValidSkillName("my-cli");     // true
+isValidSkillName("My_CLI");     // false — uppercase and underscores not allowed
+isValidSkillName("-leading");   // false — leading hyphen
+isValidSkillName("a".repeat(65)); // false — exceeds 64 characters
+```
+
+> **Note:** `generateSkill()` automatically validates `meta.name` (after prepending `use-`) and throws a descriptive error if the name is invalid.
+
+## Skill Metadata
+
+The `SkillMeta` object controls the generated `SKILL.md` frontmatter. Beyond the required `name`, `description`, and `version` fields, several optional fields are supported:
+
+```ts
+const meta: SkillMeta = {
+  name: "my-cli",
+  description: "CLI tool for managing widgets",
+  version: "1.0.0",
+
+  // Optional fields — emitted in SKILL.md YAML frontmatter when set
+  allowedTools: "Bash(my-cli *) Read Grep",   // Pre-approved tools (avoids per-use prompts)
+  license: "MIT",                              // License name or reference
+  compatibility: "Requires my-cli on PATH",    // Environment requirements (max 500 chars)
+  disableModelInvocation: false,               // true = agent won't auto-load; user must invoke manually
+};
+```
+
+| Field | Frontmatter Key | Description |
+| ----- | --------------- | ----------- |
+| `allowedTools` | `allowed-tools` | Space-delimited list of pre-approved tools (e.g. `Bash(my-cli *) Read Grep`) |
+| `license` | `license` | License name or file reference |
+| `compatibility` | `compatibility` | Environment requirements or compatibility notes |
+| `disableModelInvocation` | `disable-model-invocation` | When `true`, prevents agents from auto-loading the skill |
+
+## Escaping
+
+The renderer automatically handles special characters in generated output:
+
+- **YAML frontmatter**: Values containing YAML-special characters (`:`, `#`, `*`, `!`, `[`, `{`, `'`, `"`, etc.) are wrapped in double quotes with internal quotes escaped.
+- **Markdown tables**: Literal `|` characters in argument/flag descriptions are escaped as `\|` to prevent broken table rendering.
+
+No manual escaping is needed — pass raw values and the renderer handles the rest.
+
 ## Output Structure
 
 Generated output goes to `<outDir>/skills/use-<name>/` (the `use-` prefix is applied automatically):
@@ -161,7 +213,7 @@ skills/use-my-cli/
     db/
       migrate.md      # Nested subcommand
       seed.md
-  manifest.json       # Machine-readable bundle metadata
+  crust.json          # Machine-readable bundle metadata (Crust ownership marker)
 ```
 
 ### File Details
@@ -171,7 +223,26 @@ skills/use-my-cli/
 | `SKILL.md` | Agent entrypoint with YAML frontmatter. Directs agents to load specific command files on demand (lazy loading). |
 | `command-index.md` | Markdown table listing every command, its type (runnable/group), and documentation path. |
 | `commands/*.md` | Per-command reference files. Leaf commands include usage, arguments, flags, defaults, and aliases. Group commands list subcommands with links. |
-| `manifest.json` | JSON metadata: name, description, version, entrypoint, and list of all command paths. |
+| `crust.json` | Crust-specific JSON metadata: name, description, version, entrypoint, and list of all command paths. Also serves as an ownership marker — its presence indicates the skill was generated by Crust. |
+
+## Conflict Detection
+
+Each skill directory contains a `crust.json` file that acts as an ownership marker. If `generateSkill()` encounters an existing directory without `crust.json`, it throws a `SkillConflictError` to prevent overwriting skills created manually or by other tools.
+
+Pass `force: true` to overwrite, or handle the error:
+
+```ts
+import { generateSkill, SkillConflictError } from "@crustjs/skills";
+
+try {
+  await generateSkill({ command, meta, agents });
+} catch (err) {
+  if (err instanceof SkillConflictError) {
+    console.error(`Conflict: ${err.details.outputDir}`);
+    // err.details.agent — the agent where the conflict occurred
+  }
+}
+```
 
 ## Installing Generated Skills
 

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { AnyCommand } from "@crustjs/core";
 * Metadata for the generated skill bundle.
 *
 * This information populates the `SKILL.md` frontmatter and distribution
-* metadata files (`manifest.json`).
+* metadata files (`crust.json`).
 *
 * @example
 * ```ts
@@ -21,14 +21,52 @@ interface SkillMeta {
 	*
 	* `generateSkill()`, `uninstallSkill()`, and `skillStatus()` automatically
 	* prefix `use-` to this name for output directory paths, SKILL.md frontmatter,
-	* and manifest.json metadata. For example, `name: "my-cli"` produces output
+	* and crust.json metadata. For example, `name: "my-cli"` produces output
 	* under `use-my-cli/`.
+	*
+	* The resolved name (with `use-` prefix) must conform to the Agent Skills
+	* spec: 1–64 lowercase alphanumeric characters and hyphens, no leading/
+	* trailing/consecutive hyphens.
 	*/
 	name: string;
 	/** Human-readable description of what the CLI does */
 	description: string;
 	/** Version string for the generated skill bundle */
 	version: string;
+	/**
+	* License name or reference to a bundled license file.
+	*
+	* Emitted in SKILL.md YAML frontmatter as `license:`.
+	*/
+	license?: string;
+	/**
+	* Environment requirements or compatibility notes (max 500 chars per spec).
+	*
+	* Indicates intended product, required system packages, network access, etc.
+	* Emitted in SKILL.md YAML frontmatter as `compatibility:`.
+	*
+	* @example "Requires deploy-cli installed on PATH"
+	*/
+	compatibility?: string;
+	/**
+	* When `true`, prevents agents from automatically loading this skill.
+	* Users must invoke it manually with `/skill-name`.
+	*
+	* Emitted in SKILL.md YAML frontmatter as `disable-model-invocation: true`.
+	* @default false
+	*/
+	disableModelInvocation?: boolean;
+	/**
+	* Space-delimited list of pre-approved tools the skill may use.
+	*
+	* For CLI skills, setting this to `Bash(<cli-name> *)` allows agents to
+	* execute the CLI without per-use permission prompts.
+	*
+	* Emitted in SKILL.md YAML frontmatter as `allowed-tools:`.
+	*
+	* @example "Bash(my-cli *) Read Grep"
+	*/
+	allowedTools?: string;
 }
 /** Supported agent targets for skill installation. */
 type AgentTarget = "claude-code" | "opencode";
@@ -75,6 +113,13 @@ interface GenerateOptions {
 	* @default true
 	*/
 	clean?: boolean;
+	/**
+	* When `true`, overwrite an existing skill directory even if it was not
+	* created by Crust (i.e. has no `crust.json`). Without this flag, a
+	* conflict throws a {@link SkillConflictError}.
+	* @default false
+	*/
+	force?: boolean;
 }
 /** Status of an individual agent installation. */
 type InstallStatus = "installed" | "updated" | "up-to-date";
@@ -157,11 +202,12 @@ interface StatusResult {
 * new version is detected. Set `autoInstall: true` to also install skills that
 * are not yet present.
 *
-* **Interactive command**: set `command: true` to register a `skill` subcommand
-* that presents a single multiselect prompt for toggling agent installations.
+* **Interactive command** (default): registers a `skill` subcommand that
+* presents a single multiselect prompt for toggling agent installations.
+* Set `command: false` to disable the command.
 */
 interface SkillPluginOptions {
-	/** Skill version string — compared against the installed manifest */
+	/** Skill version string — compared against the installed crust.json */
 	version: string;
 	/**
 	* Installation scope.
@@ -191,7 +237,7 @@ interface SkillPluginOptions {
 	*
 	* - `true`: register with default name `"skill"`
 	* - `string`: register with a custom command name
-	* @default false
+	* @default true
 	*/
 	command?: boolean | string;
 }
@@ -220,10 +266,51 @@ interface SkillPluginOptions {
 * ```
 */
 declare function detectInstalledAgents(home?: string): Promise<AgentTarget[]>;
+/** Details about the conflict between an existing skill and an incoming one. */
+interface SkillConflictDetails {
+	/** The agent where the conflict was detected */
+	agent: AgentTarget;
+	/** Absolute path to the conflicting skill directory */
+	outputDir: string;
+}
+/**
+* Thrown when `generateSkill()` detects that the target skill directory
+* already exists but was not created by Crust (i.e. has no `crust.json`).
+*
+* This prevents Crust from silently overwriting a skill that was manually
+* created or installed by another tool.
+*
+* @example
+* ```ts
+* import { generateSkill, SkillConflictError } from "@crustjs/skills";
+*
+* try {
+*   await generateSkill({ command, meta, agents });
+* } catch (err) {
+*   if (err instanceof SkillConflictError) {
+*     console.error(
+*       `Conflict: "${err.details.outputDir}" already exists and was not created by Crust.`,
+*     );
+*   }
+* }
+* ```
+*/
+declare class SkillConflictError extends Error {
+	readonly name = "SkillConflictError";
+	readonly details: SkillConflictDetails;
+	constructor(details: SkillConflictDetails);
+}
+/**
+* Validates a resolved skill name against the Agent Skills specification.
+*
+* @param name - The resolved skill name to validate (already has `use-` prefix)
+* @returns `true` if valid, `false` otherwise
+*/
+declare function isValidSkillName(name: string): boolean;
 /**
 * Resolves the canonical skill name by applying the `use-` prefix.
 *
-* All generated output (directory names, manifest metadata, SKILL.md content)
+* All generated output (directory names, crust.json metadata, SKILL.md content)
 * uses the resolved name. Consumers pass the raw CLI name (e.g. `"my-cli"`),
 * and this function returns the prefixed form (e.g. `"use-my-cli"`).
 *
@@ -241,13 +328,16 @@ declare function resolveSkillName(name: string): string;
 *
 * For each target agent:
 * 1. Resolves the output directory via {@link resolveAgentPath}
-* 2. Checks the installed version — skips if up-to-date
-* 3. Builds a canonical manifest from the command tree
-* 4. Renders markdown files + `manifest.json`
-* 5. Writes files to the agent's skill directory
+* 2. Checks for conflicts — if the directory exists but has no `crust.json`,
+*    it was not created by Crust and a {@link SkillConflictError} is thrown
+* 3. Checks the installed version — skips if up-to-date
+* 4. Builds a canonical manifest from the command tree
+* 5. Renders markdown files + `crust.json`
+* 6. Writes files to the agent's skill directory
 *
 * @param options - Generation options including command, metadata, agents, and scope
 * @returns Per-agent installation results
+* @throws {SkillConflictError} If the output directory exists but was not created by Crust
 *
 * @example
 * ```ts
@@ -299,11 +389,12 @@ import { CrustPlugin } from "@crustjs/core";
 * new version is detected. Set `autoInstall: true` to also install skills that
 * are not yet present.
 *
-* **Interactive command**: set `command: true` to register a `skill` subcommand
-* that presents a single multiselect prompt for toggling agent installations.
+* **Interactive command** (default): registers a `skill` subcommand that
+* presents a single multiselect prompt for toggling agent installations.
 * Detected agents are shown with their current installation status pre-filled.
 * The system reconciles the desired state: newly selected agents are installed,
 * deselected agents are uninstalled, and already-correct agents are skipped.
+* Set `command: false` to disable command injection.
 *
 * @param options - Plugin configuration with version and scope
 * @returns A `CrustPlugin` to register in a command's `plugins` array
@@ -327,4 +418,4 @@ import { CrustPlugin } from "@crustjs/core";
 * ```
 */
 declare function skillPlugin(options: SkillPluginOptions): CrustPlugin;
-export { uninstallSkill, skillStatus, skillPlugin, resolveSkillName, generateSkill, detectInstalledAgents, UninstallStatus, UninstallResult, UninstallOptions, StatusResult, StatusOptions, SkillPluginOptions, SkillMeta, Scope, InstallStatus, GenerateResult, GenerateOptions, AgentTarget, AgentResult };
+export { uninstallSkill, skillStatus, skillPlugin, resolveSkillName, isValidSkillName, generateSkill, detectInstalledAgents, UninstallStatus, UninstallResult, UninstallOptions, StatusResult, StatusOptions, SkillPluginOptions, SkillMeta, SkillConflictError, SkillConflictDetails, Scope, InstallStatus, GenerateResult, GenerateOptions, AgentTarget, AgentResult };

package/dist/index.js

@@ -40,6 +40,16 @@ function resolveAgentConfigDir(home, agent) {
       return join(home, ".config", "opencode");
   }
 }
+// src/errors.ts
+class SkillConflictError extends Error {
+  name = "SkillConflictError";
+  details;
+  constructor(details) {
+    const message = `Skill conflict for agent "${details.agent}": ` + `directory "${details.outputDir}" already exists but was not created by Crust ` + `(no crust.json found). Delete or rename the conflicting skill to resolve.`;
+    super(message);
+    this.details = details;
+  }
+}
 // src/generate.ts
 import { access as access2, mkdir, rm, writeFile } from "fs/promises";
 import { dirname, join as join3 } from "path";
@@ -133,6 +143,15 @@ function serializeDefault(value) {
 }
 
 // src/render.ts
+function escapeYaml(value) {
+  if (/[:#[\]{}&*!|>'"`,@?\\]|^\s|\s$|^---|[\n\r]/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r")}"`;
+  }
+  return value;
+}
+function escapeTableCell(value) {
+  return value.replace(/(?<!\\)\|/g, "\\|");
+}
 function renderSkill(manifest, meta) {
   const files = [];
   const allNodes = collectNodes(manifest);
@@ -186,8 +205,20 @@ function relativePath(from, to) {
 function renderSkillMd(manifest, meta) {
   const lines = [];
   lines.push("---");
-  lines.push(`name: ${meta.name}`);
-  lines.push(`description: ${meta.description}`);
+  lines.push(`name: ${escapeYaml(meta.name)}`);
+  lines.push(`description: ${escapeYaml(meta.description)}`);
+  if (meta.license) {
+    lines.push(`license: ${escapeYaml(meta.license)}`);
+  }
+  if (meta.compatibility) {
+    lines.push(`compatibility: ${escapeYaml(meta.compatibility)}`);
+  }
+  if (meta.disableModelInvocation) {
+    lines.push("disable-model-invocation: true");
+  }
+  if (meta.allowedTools) {
+    lines.push(`allowed-tools: ${escapeYaml(meta.allowedTools)}`);
+  }
   lines.push("metadata:");
   lines.push(`  version: "${meta.version}"`);
   lines.push("---");
@@ -198,13 +229,15 @@ function renderSkillMd(manifest, meta) {
     lines.push(manifest.description);
     lines.push("");
   }
-  lines.push("## Command Reference");
+  const cliName = meta.name.startsWith("use-") ? meta.name.slice(4) : meta.name;
+  lines.push(`Use this skill when working with \`${cliName}\` commands, or when you need help with \`${cliName}\` syntax, flags, or subcommands.`);
   lines.push("");
-  lines.push("This skill provides documentation for all available CLI commands.");
+  lines.push("## Command Reference");
   lines.push("");
-  lines.push(`For a complete list of commands and their documentation paths, see [command-index.md](command-index.md).`);
+  lines.push(`For the full list of commands and their documentation paths, see [command-index.md](command-index.md). ` + "**Do not read all command files at once.** Instead:");
   lines.push("");
-  lines.push("When you need details about a specific command, load the corresponding file from the `commands/` directory rather than reading all files at once.");
+  lines.push("1. Check [command-index.md](command-index.md) to find the relevant command");
+  lines.push("2. Read only the specific file from the `commands/` directory that you need");
   lines.push("");
   if (manifest.children.length > 0) {
     lines.push("## Available Commands");
@@ -358,7 +391,7 @@ function renderArgsTable(args) {
   for (const arg of args) {
     const name = arg.variadic ? `${arg.name}...` : arg.name;
     const required = arg.required ? "Yes" : "No";
-    const desc = formatArgDescription(arg);
+    const desc = escapeTableCell(formatArgDescription(arg));
     lines.push(`| \`${name}\` | ${arg.type} | ${required} | ${desc} |`);
   }
   return lines;
@@ -380,7 +413,7 @@ function renderFlagsTable(flags) {
   for (const flag of flags) {
     const name = formatFlagName(flag);
     const required = flag.required ? "Yes" : "No";
-    const desc = formatFlagDescription(flag);
+    const desc = escapeTableCell(formatFlagDescription(flag));
     lines.push(`| ${name} | ${flag.type} | ${required} | ${desc} |`);
   }
   return lines;
@@ -450,9 +483,10 @@ function arraysEqual(a, b) {
 // src/version.ts
 import { readFile } from "fs/promises";
 import { join as join2 } from "path";
+var CRUST_MANIFEST = "crust.json";
 async function readInstalledVersion(dir) {
   try {
-    const raw = await readFile(join2(dir, "manifest.json"), "utf-8");
+    const raw = await readFile(join2(dir, CRUST_MANIFEST), "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed === "object" && parsed !== null && "version" in parsed && typeof parsed.version === "string") {
       return parsed.version;
@@ -462,26 +496,31 @@ async function readInstalledVersion(dir) {
     return null;
   }
 }
-async function checkVersion(dir, newVersion) {
-  const installed = await readInstalledVersion(dir);
-  if (installed === null) {
-    return { status: "installed", installedVersion: null };
-  }
-  if (installed !== newVersion) {
-    return { status: "updated", installedVersion: installed };
-  }
-  return { status: "up-to-date", installedVersion: installed };
-}
 
 // src/generate.ts
+var SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function isValidSkillName(name) {
+  return name.length >= 1 && name.length <= 64 && SKILL_NAME_PATTERN.test(name);
+}
 function resolveSkillName(name) {
   return name.startsWith("use-") ? name : `use-${name}`;
 }
 async function generateSkill(options) {
-  const { command, meta, agents, scope = "global", clean = true } = options;
+  const {
+    command,
+    meta,
+    agents,
+    scope = "global",
+    clean = true,
+    force = false
+  } = options;
+  const resolvedName = resolveSkillName(meta.name);
+  if (!isValidSkillName(resolvedName)) {
+    throw new Error(`Invalid skill name "${resolvedName}": must be 1\u201364 lowercase ` + `alphanumeric characters and hyphens, no leading/trailing/consecutive ` + `hyphens. Pattern: ${SKILL_NAME_PATTERN.source}`);
+  }
   const resolvedMeta = {
     ...meta,
-    name: resolveSkillName(meta.name)
+    name: resolvedName
   };
   const manifest = buildManifest(command);
   const renderedFiles = renderSkill(manifest, resolvedMeta);
@@ -490,7 +529,14 @@ async function generateSkill(options) {
   const results = [];
   for (const agent of agents) {
     const outputDir = resolveAgentPath(agent, scope, resolvedMeta.name);
-    const { status, installedVersion } = await checkVersion(outputDir, resolvedMeta.version);
+    const installedVersion = await readInstalledVersion(outputDir);
+    if (installedVersion === null) {
+      const dirExists = await access2(outputDir).then(() => true).catch(() => false);
+      if (dirExists && !force) {
+        throw new SkillConflictError({ agent, outputDir });
+      }
+    }
+    const status = installedVersion === null ? "installed" : installedVersion === resolvedMeta.version ? "up-to-date" : "updated";
     if (status === "up-to-date") {
       results.push({
         agent,
@@ -550,12 +596,12 @@ async function skillStatus(options) {
 function renderDistributionMetadata(manifest, meta) {
   return [
     {
-      path: "manifest.json",
-      content: renderManifestJson(manifest, meta)
+      path: CRUST_MANIFEST,
+      content: renderCrustJson(manifest, meta)
     }
   ];
 }
-function renderManifestJson(manifest, meta) {
+function renderCrustJson(manifest, meta) {
   const commands = collectCommandPaths(manifest);
   const obj = {
     name: meta.name,
@@ -595,7 +641,7 @@ async function writeFiles(baseDir, files) {
 }
 // src/plugin.ts
 import { defineCommand } from "@crustjs/core";
-import { multiselect, spinner } from "@crustjs/prompts";
+import { confirm, multiselect, spinner } from "@crustjs/prompts";
 function deriveSkillMeta(command, version) {
   return {
     name: command.meta.name,
@@ -610,7 +656,7 @@ function skillPlugin(options) {
     name: "skills",
     setup(context, actions) {
       rootCmd = context.rootCommand;
-      if (options.command) {
+      if (options.command !== false) {
         const name = typeof options.command === "string" ? options.command : "skill";
         skillCmd = buildSkillCommand(rootCmd, options);
         actions.addSubCommand(rootCmd, name, skillCmd);
@@ -642,15 +688,32 @@ function skillPlugin(options) {
         return false;
       });
       if (needsUpdate.length > 0) {
-        const result = await generateSkill({
-          command: rootCmd,
-          meta,
-          agents: needsUpdate.map((a) => a.agent),
-          scope: options.scope
-        });
-        const agentNames = result.agents.filter((a) => a.status !== "up-to-date").map((a) => AGENT_LABELS[a.agent]);
-        if (agentNames.length > 0) {
-          console.log(`Skill "${meta.name}" v${meta.version} installed for ${agentNames.join(", ")}`);
+        try {
+          const result = await generateSkill({
+            command: rootCmd,
+            meta,
+            agents: needsUpdate.map((a) => a.agent),
+            scope: options.scope
+          });
+          const installedAgents = result.agents.filter((a) => a.status === "installed").map((a) => AGENT_LABELS[a.agent]);
+          const updatedAgents = result.agents.filter((a) => a.status === "updated").map((a) => AGENT_LABELS[a.agent]);
+          if (installedAgents.length > 0) {
+            if (options.command !== false) {
+              const manageCommand = `${rootCmd.meta.name} skill`;
+              console.log(`Auto-installed skill "${meta.name}" v${meta.version} for ${installedAgents.join(", ")}. Manage with \`${manageCommand}\`.`);
+            } else {
+              console.log(`Auto-installed skill "${meta.name}" v${meta.version} for ${installedAgents.join(", ")}.`);
+            }
+          }
+          if (updatedAgents.length > 0) {
+            console.log(`Updated skill "${meta.name}" to v${meta.version} for ${updatedAgents.join(", ")}.`);
+          }
+        } catch (err) {
+          if (err instanceof SkillConflictError) {
+            console.warn(`Skill conflict: "${err.details.outputDir}" already exists ` + `but was not created by ${meta.name}. Skipping auto-update. ` + `Delete or rename the conflicting skill to resolve.`);
+          } else {
+            throw err;
+          }
         }
       }
       await next();
@@ -702,19 +765,50 @@ function buildSkillCommand(rootCmd, options) {
       const toUninstall = installedAgents.filter((agent) => !selected.includes(agent));
       const agentsToGenerate = [...toInstall, ...toUpdate];
       if (agentsToGenerate.length > 0) {
-        const result = await spinner({
-          message: "Installing skills...",
-          task: async () => generateSkill({
-            command: rootCmd,
-            meta,
-            agents: agentsToGenerate,
-            scope
-          })
-        });
-        console.log(`
+        try {
+          const result = await spinner({
+            message: "Installing skills...",
+            task: async () => generateSkill({
+              command: rootCmd,
+              meta,
+              agents: agentsToGenerate,
+              scope
+            })
+          });
+          console.log(`
+Installed "${meta.name}" v${meta.version}`);
+          for (const r of result.agents) {
+            console.log(`  ${AGENT_LABELS[r.agent]} \u2192 ${r.outputDir}`);
+          }
+        } catch (err) {
+          if (err instanceof SkillConflictError) {
+            const overwrite = await confirm({
+              message: `"${err.details.outputDir}" already exists but was not ` + `created by Crust. Overwrite?`,
+              default: false
+            });
+            if (overwrite) {
+              const result = await spinner({
+                message: "Overwriting skill...",
+                task: async () => generateSkill({
+                  command: rootCmd,
+                  meta,
+                  agents: [err.details.agent],
+                  scope,
+                  force: true
+                })
+              });
+              console.log(`
 Installed "${meta.name}" v${meta.version}`);
-        for (const r of result.agents) {
-          console.log(`  ${AGENT_LABELS[r.agent]} \u2192 ${r.outputDir}`);
+              for (const r of result.agents) {
+                console.log(`  ${AGENT_LABELS[r.agent]} \u2192 ${r.outputDir}`);
+              }
+            } else {
+              console.log(`
+Skipped ${AGENT_LABELS[err.details.agent]}`);
+            }
+          } else {
+            throw err;
+          }
         }
       }
       if (toUninstall.length > 0) {
@@ -743,6 +837,8 @@ export {
   skillStatus,
   skillPlugin,
   resolveSkillName,
+  isValidSkillName,
   generateSkill,
-  detectInstalledAgents
+  detectInstalledAgents,
+  SkillConflictError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/skills",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Agent skill generation from Crust command definitions",
 	"type": "module",
 	"license": "MIT",