@crustjs/skills 0.0.2 → 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,12 +150,61 @@ 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/<name>/`:
+Generated output goes to `<outDir>/skills/use-<name>/` (the `use-` prefix is applied automatically):
 
 ```
-skills/my-cli/
+skills/use-my-cli/
   SKILL.md            # Entrypoint — loaded by the agent
   command-index.md    # Maps all commands to documentation file paths
   commands/           # Per-command documentation mirroring the CLI hierarchy
@@ -161,8 +213,7 @@ skills/my-cli/
     db/
       migrate.md      # Nested subcommand
       seed.md
-  manifest.json       # Machine-readable bundle metadata
-  README.md           # Install instructions for consumers
+  crust.json          # Machine-readable bundle metadata (Crust ownership marker)
 ```
 
 ### File Details
@@ -172,8 +223,26 @@ skills/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. |
-| `README.md` | Human-readable install instructions for OpenCode and Claude Code. |
+| `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
 
@@ -182,13 +251,13 @@ After generating a skill bundle, consumers can install it by copying the skill d
 ### OpenCode
 
 ```sh
-cp -r skills/my-cli/ .opencode/skills/my-cli/
+cp -r skills/use-my-cli/ .opencode/skills/use-my-cli/
 ```
 
 ### Claude Code
 
 ```sh
-cp -r skills/my-cli/ .claude/skills/my-cli/
+cp -r skills/use-my-cli/ .claude/skills/use-my-cli/
 ```
 
 The agent will discover the skill from `SKILL.md` and load command documentation on demand from the `commands/` directory.

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
@@ -12,15 +12,61 @@ import { AnyCommand } from "@crustjs/core";
 *   description: "CLI tool for managing widgets",
 *   version: "1.0.0",
 * };
+* // generateSkill() will output to `use-my-cli/` with name "use-my-cli"
 * ```
 */
 interface SkillMeta {
-	/** Skill name — used as the directory name and in frontmatter */
+	/**
+	* Skill name — the user-facing CLI name (e.g. `"my-cli"`).
+	*
+	* `generateSkill()`, `uninstallSkill()`, and `skillStatus()` automatically
+	* prefix `use-` to this name for output directory paths, SKILL.md frontmatter,
+	* 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";
@@ -29,6 +75,10 @@ type Scope = "global" | "project";
 /**
 * Top-level options for generating a skill bundle from a command tree.
 *
+* The `meta.name` value is automatically prefixed with `use-` for all output
+* paths and metadata. For example, `name: "my-cli"` produces skill directories
+* named `use-my-cli/` and sets the manifest/frontmatter name to `"use-my-cli"`.
+*
 * @example
 * ```ts
 * import { generateSkill } from "@crustjs/skills";
@@ -37,7 +87,7 @@ type Scope = "global" | "project";
 * await generateSkill({
 *   command: rootCommand,
 *   meta: {
-*     name: "my-cli",
+*     name: "my-cli", // output: use-my-cli/
 *     description: "CLI tool for managing widgets",
 *     version: "1.0.0",
 *   },
@@ -63,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";
@@ -145,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
-* on the root command for manual install/uninstall/status management.
+* **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.
@@ -170,9 +228,16 @@ interface SkillPluginOptions {
 	autoUpdate?: boolean;
 	/**
 	* Register an interactive skill management subcommand on the root command.
+	*
+	* The command presents a single multiselect prompt listing all detected
+	* agents with their current installation status pre-filled. The user
+	* toggles agents on/off and the system reconciles the desired state:
+	* newly selected agents are installed, deselected agents are uninstalled,
+	* and already-correct agents are skipped.
+	*
 	* - `true`: register with default name `"skill"`
 	* - `string`: register with a custom command name
-	* @default false
+	* @default true
 	*/
 	command?: boolean | string;
 }
@@ -201,18 +266,78 @@ 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, 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"`).
+*
+* @param name - The raw CLI tool name
+* @returns The prefixed skill name
+*
+* @example
+* ```ts
+* resolveSkillName("my-cli"); // "use-my-cli"
+* ```
+*/
+declare function resolveSkillName(name: string): string;
 /**
 * Generates and installs agent skill bundles from a Crust command tree.
 *
 * 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
@@ -264,10 +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
-* on the root command for manual install/uninstall/status management. The
-* subcommand is injected via `addSubCommand` during `setup()` — if the user
-* already defines a subcommand with the same name, theirs takes priority.
+* **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
@@ -291,4 +418,4 @@ import { CrustPlugin } from "@crustjs/core";
 * ```
 */
 declare function skillPlugin(options: SkillPluginOptions): CrustPlugin;
-export { uninstallSkill, skillStatus, skillPlugin, 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,28 +496,47 @@ 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: resolvedName
+  };
   const manifest = buildManifest(command);
-  const renderedFiles = renderSkill(manifest, meta);
-  const metadataFiles = renderDistributionMetadata(manifest, meta);
+  const renderedFiles = renderSkill(manifest, resolvedMeta);
+  const metadataFiles = renderDistributionMetadata(manifest, resolvedMeta);
   const allFiles = [...renderedFiles, ...metadataFiles].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   const results = [];
   for (const agent of agents) {
-    const outputDir = resolveAgentPath(agent, scope, meta.name);
-    const { status, installedVersion } = await checkVersion(outputDir, meta.version);
+    const outputDir = resolveAgentPath(agent, scope, resolvedMeta.name);
+    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,
@@ -510,9 +563,10 @@ async function generateSkill(options) {
 }
 async function uninstallSkill(options) {
   const { name, agents, scope = "global" } = options;
+  const resolvedName = resolveSkillName(name);
   const results = [];
   for (const agent of agents) {
-    const outputDir = resolveAgentPath(agent, scope, name);
+    const outputDir = resolveAgentPath(agent, scope, resolvedName);
     const exists = await access2(outputDir).then(() => true).catch(() => false);
     if (exists) {
       await rm(outputDir, { recursive: true, force: true });
@@ -525,9 +579,10 @@ async function uninstallSkill(options) {
 }
 async function skillStatus(options) {
   const { name, agents, scope = "global" } = options;
+  const resolvedName = resolveSkillName(name);
   const results = [];
   for (const agent of agents) {
-    const outputDir = resolveAgentPath(agent, scope, name);
+    const outputDir = resolveAgentPath(agent, scope, resolvedName);
     const version = await readInstalledVersion(outputDir);
     results.push({
       agent,
@@ -541,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,
@@ -586,7 +641,7 @@ async function writeFiles(baseDir, files) {
 }
 // src/plugin.ts
 import { defineCommand } from "@crustjs/core";
-import { confirm, multiselect, select, spinner } from "@crustjs/prompts";
+import { confirm, multiselect, spinner } from "@crustjs/prompts";
 function deriveSkillMeta(command, version) {
   return {
     name: command.meta.name,
@@ -601,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);
@@ -633,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();
@@ -652,147 +724,121 @@ function buildSkillCommand(rootCmd, options) {
   return defineCommand({
     meta: {
       name: "skill",
-      description: "Manage agent skills (install, uninstall, status)"
-    },
-    flags: {
-      action: {
-        type: "string",
-        description: 'Action to perform: "install", "uninstall", or "status" (skips prompt)'
-      },
-      scope: {
-        type: "string",
-        description: 'Installation scope: "global" or "project" (skips prompt)'
-      },
-      force: {
-        type: "boolean",
-        description: "Skip confirmation prompts"
-      }
+      description: "Manage agent skill installations"
     },
-    async run({ flags }) {
+    async run() {
       const meta = deriveSkillMeta(rootCmd, options.version);
-      const actionFlag = flags.action;
-      const scopeFlag = flags.scope;
-      const forceFlag = flags.force ?? false;
-      const installedAgents = await detectInstalledAgents();
-      if (installedAgents.length === 0) {
+      const scope = options.scope ?? "global";
+      const detectedAgents = await detectInstalledAgents();
+      if (detectedAgents.length === 0) {
         console.log("No supported agents detected. Install Claude Code or OpenCode first.");
         return;
       }
-      const action = await select({
-        message: "What would you like to do?",
-        choices: [
-          { label: "Install / update skills", value: "install" },
-          { label: "Uninstall skills", value: "uninstall" },
-          { label: "Check status", value: "status" }
-        ],
-        initial: actionFlag
+      const status = await skillStatus({
+        name: meta.name,
+        agents: detectedAgents,
+        scope
       });
-      if (action === "install") {
-        await handleInstall(rootCmd, meta, options, installedAgents, scopeFlag);
-      } else if (action === "uninstall") {
-        await handleUninstall(meta, installedAgents, scopeFlag, forceFlag);
-      } else if (action === "status") {
-        await handleStatus(meta, installedAgents, scopeFlag);
-      }
-    }
-  });
-}
-async function handleInstall(rootCmd, meta, options, installedAgents, scopeFlag) {
-  const agents = await multiselect({
-    message: "Which agents?",
-    choices: installedAgents.map((a) => ({
-      label: AGENT_LABELS[a],
-      value: a
-    })),
-    default: installedAgents,
-    required: true
-  });
-  const scope = await select({
-    message: "Scope?",
-    choices: [
-      { label: "Global", value: "global", hint: "recommended" },
-      { label: "Project", value: "project" }
-    ],
-    default: options.scope ?? "global",
-    initial: scopeFlag
-  });
-  const result = await spinner({
-    message: "Installing skills...",
-    task: async () => generateSkill({
-      command: rootCmd,
-      meta,
-      agents,
-      scope
-    })
-  });
-  console.log(`
+      const installedAgents = [];
+      const choices = status.agents.map((entry) => {
+        const hint = entry.installed ? `v${entry.version} installed` : "not installed";
+        if (entry.installed) {
+          installedAgents.push(entry.agent);
+        }
+        return {
+          label: AGENT_LABELS[entry.agent],
+          value: entry.agent,
+          hint
+        };
+      });
+      const selected = await multiselect({
+        message: "Select agents to install skills for",
+        choices,
+        default: installedAgents,
+        required: false
+      });
+      const toInstall = selected.filter((agent) => !installedAgents.includes(agent));
+      const toUpdate = selected.filter((agent) => {
+        const entry = status.agents.find((a) => a.agent === agent);
+        return entry?.installed === true && entry.version !== meta.version;
+      });
+      const toUninstall = installedAgents.filter((agent) => !selected.includes(agent));
+      const agentsToGenerate = [...toInstall, ...toUpdate];
+      if (agentsToGenerate.length > 0) {
+        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) {
-    if (r.status !== "up-to-date") {
-      console.log(`  ${AGENT_LABELS[r.agent]} \u2192 ${r.outputDir}`);
-    } else {
-      console.log(`  ${AGENT_LABELS[r.agent]} \u2014 already up-to-date`);
-    }
-  }
-}
-async function handleUninstall(meta, installedAgents, scopeFlag, forceFlag) {
-  const agents = await multiselect({
-    message: "Which agents to uninstall from?",
-    choices: installedAgents.map((a) => ({
-      label: AGENT_LABELS[a],
-      value: a
-    })),
-    default: installedAgents,
-    required: true
-  });
-  const agentNames = agents.map((a) => AGENT_LABELS[a]).join(", ");
-  const confirmed = await confirm({
-    message: `Remove "${meta.name}" skills from ${agentNames}?`,
-    initial: forceFlag ? true : undefined
-  });
-  if (!confirmed) {
-    console.log("Cancelled.");
-    return;
-  }
-  const scope = scopeFlag ?? "global";
-  const result = await spinner({
-    message: "Removing skills...",
-    task: async () => uninstallSkill({
-      name: meta.name,
-      agents,
-      scope
-    })
-  });
-  const removed = result.agents.filter((a) => a.status === "removed").map((a) => AGENT_LABELS[a.agent]);
-  if (removed.length > 0) {
-    console.log(`
+          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}`);
+              }
+            } else {
+              console.log(`
+Skipped ${AGENT_LABELS[err.details.agent]}`);
+            }
+          } else {
+            throw err;
+          }
+        }
+      }
+      if (toUninstall.length > 0) {
+        const result = await spinner({
+          message: "Removing skills...",
+          task: async () => uninstallSkill({
+            name: meta.name,
+            agents: toUninstall,
+            scope
+          })
+        });
+        const removed = result.agents.filter((a) => a.status === "removed").map((a) => AGENT_LABELS[a.agent]);
+        if (removed.length > 0) {
+          console.log(`
 Removed from ${removed.join(", ")}`);
-  } else {
-    console.log(`
-No installed skills found.`);
-  }
-}
-async function handleStatus(meta, installedAgents, scopeFlag) {
-  const scope = scopeFlag ?? "global";
-  const result = await skillStatus({
-    name: meta.name,
-    agents: installedAgents,
-    scope
+        }
+      }
+      if (agentsToGenerate.length === 0 && toUninstall.length === 0) {
+        console.log("No changes.");
+      }
+    }
   });
-  console.log("");
-  console.log(`${"Agent".padEnd(14)}${"Scope".padEnd(10)}${"Version".padEnd(10)}Path`);
-  for (const entry of result.agents) {
-    const agentName = AGENT_LABELS[entry.agent];
-    const version = entry.installed ? entry.version ?? "\u2014" : "(not installed)";
-    const path = entry.installed ? entry.outputDir : "";
-    console.log(`${agentName.padEnd(14)}${scope.padEnd(10)}${version.padEnd(10)}${path}`);
-  }
-  console.log("");
 }
 export {
   uninstallSkill,
   skillStatus,
   skillPlugin,
+  resolveSkillName,
+  isValidSkillName,
   generateSkill,
-  detectInstalledAgents
+  detectInstalledAgents,
+  SkillConflictError
 };

package/package.json

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