@crustjs/skills 0.0.2

package/README.md

@@ -0,0 +1,202 @@
+# @crustjs/skills
+
+Generate distributable AI agent skills from [Crust](https://crustjs.com) command definitions.
+
+Instead of hand-maintaining skill files for AI coding agents, generate them from your `defineCommand` metadata. The output is a portable skill bundle that developers can download and install into their own agent environments (OpenCode, Claude Code, etc.).
+
+## Install
+
+```sh
+bun add @crustjs/skills
+```
+
+## Quick Start
+
+### CLI (via `@crustjs/crust`)
+
+```sh
+crust skills generate ./src/cli.ts --name my-cli --description "My CLI tool"
+```
+
+### Programmatic API
+
+```ts
+import { generateSkill } from "@crustjs/skills";
+import { rootCommand } from "./commands.ts";
+
+const result = await generateSkill({
+  command: rootCommand,
+  meta: {
+    name: "my-cli",
+    description: "CLI tool for managing widgets",
+    version: "1.0.0",
+  },
+});
+
+console.log(`Generated ${result.files.length} files to ${result.outputDir}`);
+```
+
+## Recommended Export Pattern
+
+To avoid side effects when your command module is imported for generation, guard runtime code with `import.meta.main`:
+
+```ts
+import { defineCommand, runMain } from "@crustjs/core";
+
+// Export the command object — used by skill generation
+export const rootCommand = defineCommand({
+  meta: { name: "my-cli", description: "My CLI tool" },
+  run({ args }) {
+    console.log("Hello from my-cli!");
+  },
+});
+
+// Only run when executed directly — not when imported for generation
+if (import.meta.main) {
+  runMain(rootCommand);
+}
+```
+
+This pattern lets `crust skills generate` import the command definition without triggering `runMain`.
+
+## CLI Usage
+
+The `crust skills generate` command is provided by `@crustjs/crust`:
+
+```sh
+crust skills generate <module> [options]
+```
+
+### Arguments
+
+| Argument | Description |
+| -------- | ----------- |
+| `module` | Path to the command module (e.g. `./src/cli.ts`) |
+
+### Flags
+
+| Flag | Alias | Required | Default | Description |
+| ---- | ----- | -------- | ------- | ----------- |
+| `--name` | `-n` | Yes | - | Skill name (used as directory name) |
+| `--description` | `-d` | Yes | - | Human-readable description |
+| `--version` | `-V` | No | - | Version string |
+| `--out-dir` | `-o` | No | `.` | Output directory |
+| `--clean` | - | No | `true` | Remove existing skill directory before writing |
+| `--export` | `-e` | No | `default` | Named export to use from the module |
+
+### Examples
+
+```sh
+# Basic generation
+crust skills generate ./src/cli.ts --name my-cli --description "My CLI"
+
+# With version and custom output directory
+crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --version 1.0.0 -o ./dist
+
+# Using a named export instead of the default export
+crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --export rootCommand
+
+# Keep existing files (no clean)
+crust skills generate ./src/cli.ts -n my-cli -d "My CLI" --no-clean
+```
+
+## Programmatic API
+
+### `generateSkill(options)`
+
+High-level API that runs the full pipeline: introspection, rendering, and writing to disk.
+
+```ts
+import { generateSkill } from "@crustjs/skills";
+
+const result = await generateSkill({
+  command: rootCommand,
+  meta: { name: "my-cli", description: "My CLI tool", version: "1.0.0" },
+  outDir: "./dist",  // default: "."
+  clean: true,       // default: true — removes existing skill dir first
+});
+
+// result.outputDir — absolute path to the generated skill directory
+// result.files     — sorted list of written file paths (relative to outputDir)
+```
+
+### `buildManifest(command)`
+
+Introspects a command tree and produces a canonical, serializable manifest.
+
+```ts
+import { buildManifest } from "@crustjs/skills";
+
+const manifest = buildManifest(rootCommand);
+// manifest.name, manifest.path, manifest.args, manifest.flags, manifest.children
+```
+
+### `renderSkill(manifest, meta)`
+
+Renders markdown files from a manifest tree without writing to disk.
+
+```ts
+import { buildManifest, renderSkill } from "@crustjs/skills";
+
+const manifest = buildManifest(rootCommand);
+const files = renderSkill(manifest, { name: "my-cli", description: "My CLI" });
+
+for (const file of files) {
+  console.log(file.path);    // e.g. "SKILL.md", "commands/serve.md"
+  console.log(file.content); // markdown content
+}
+```
+
+## Output Structure
+
+Generated output goes to `<outDir>/skills/<name>/`:
+
+```
+skills/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
+    my-cli.md         # Root command
+    serve.md          # Subcommand
+    db/
+      migrate.md      # Nested subcommand
+      seed.md
+  manifest.json       # Machine-readable bundle metadata
+  README.md           # Install instructions for consumers
+```
+
+### File Details
+
+| File | Purpose |
+| ---- | ------- |
+| `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. |
+
+## Installing Generated Skills
+
+After generating a skill bundle, consumers can install it by copying the skill directory.
+
+### OpenCode
+
+```sh
+cp -r skills/my-cli/ .opencode/skills/my-cli/
+```
+
+### Claude Code
+
+```sh
+cp -r skills/my-cli/ .claude/skills/my-cli/
+```
+
+The agent will discover the skill from `SKILL.md` and load command documentation on demand from the `commands/` directory.
+
+## Documentation
+
+See the full docs at [crustjs.com](https://crustjs.com).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,294 @@
+import { AnyCommand } from "@crustjs/core";
+/**
+* Metadata for the generated skill bundle.
+*
+* This information populates the `SKILL.md` frontmatter and distribution
+* metadata files (`manifest.json`).
+*
+* @example
+* ```ts
+* const meta: SkillMeta = {
+*   name: "my-cli",
+*   description: "CLI tool for managing widgets",
+*   version: "1.0.0",
+* };
+* ```
+*/
+interface SkillMeta {
+	/** Skill name — used as the directory name and in frontmatter */
+	name: string;
+	/** Human-readable description of what the CLI does */
+	description: string;
+	/** Version string for the generated skill bundle */
+	version: string;
+}
+/** Supported agent targets for skill installation. */
+type AgentTarget = "claude-code" | "opencode";
+/** Installation scope — global (home directory) or project (cwd). */
+type Scope = "global" | "project";
+/**
+* Top-level options for generating a skill bundle from a command tree.
+*
+* @example
+* ```ts
+* import { generateSkill } from "@crustjs/skills";
+* import { rootCommand } from "./commands.ts";
+*
+* await generateSkill({
+*   command: rootCommand,
+*   meta: {
+*     name: "my-cli",
+*     description: "CLI tool for managing widgets",
+*     version: "1.0.0",
+*   },
+*   agents: ["claude-code", "opencode"],
+* });
+* ```
+*/
+interface GenerateOptions {
+	/** Root command to generate the skill from */
+	command: AnyCommand;
+	/** Skill metadata for the generated bundle */
+	meta: SkillMeta;
+	/** Agent targets to install skills for */
+	agents: AgentTarget[];
+	/**
+	* Installation scope — global (home directory) or project (cwd).
+	* @default "global"
+	*/
+	scope?: Scope;
+	/**
+	* When `true`, removes the existing skill directory before writing.
+	* Prevents stale files from previous generations.
+	* @default true
+	*/
+	clean?: boolean;
+}
+/** Status of an individual agent installation. */
+type InstallStatus = "installed" | "updated" | "up-to-date";
+/** Status of an individual agent uninstallation. */
+type UninstallStatus = "removed" | "not-found";
+/** Per-agent result from a generateSkill call. */
+interface AgentResult {
+	/** Which agent this result is for */
+	agent: AgentTarget;
+	/** Absolute path to the skill output directory for this agent */
+	outputDir: string;
+	/** List of files that were written (relative paths) */
+	files: string[];
+	/** What happened during this installation */
+	status: InstallStatus;
+	/** Previous version string when status is "updated" */
+	previousVersion?: string;
+}
+/**
+* Result returned by `generateSkill` after writing files to disk.
+*/
+interface GenerateResult {
+	/** Per-agent installation results */
+	agents: AgentResult[];
+}
+/** Options for removing installed skills. */
+interface UninstallOptions {
+	/** Skill name to uninstall */
+	name: string;
+	/** Agent targets to uninstall from */
+	agents: AgentTarget[];
+	/**
+	* Installation scope to uninstall from.
+	* @default "global"
+	*/
+	scope?: Scope;
+}
+/** Result returned by `uninstallSkill`. */
+interface UninstallResult {
+	/** Per-agent uninstall results */
+	agents: Array<{
+		agent: AgentTarget;
+		outputDir: string;
+		status: UninstallStatus;
+	}>;
+}
+/** Options for checking installed skill status. */
+interface StatusOptions {
+	/** Skill name to check */
+	name: string;
+	/** Agent targets to check */
+	agents: AgentTarget[];
+	/**
+	* Installation scope to check.
+	* @default "global"
+	*/
+	scope?: Scope;
+}
+/** Result returned by `skillStatus`. */
+interface StatusResult {
+	/** Per-agent status results */
+	agents: Array<{
+		agent: AgentTarget;
+		outputDir: string;
+		installed: boolean;
+		version?: string;
+	}>;
+}
+/**
+* Options for the skill plugin.
+*
+* The plugin reads `name` and `description` from the root command's `meta`
+* at setup time, so only `version` is required here.
+*
+* Installed agents are detected automatically by checking for global
+* configuration directories (`~/.claude/` for Claude Code,
+* `~/.config/opencode/` for OpenCode). Only detected agents are managed.
+*
+* **Auto-update** (default): silently updates already-installed skills when a
+* 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.
+*/
+interface SkillPluginOptions {
+	/** Skill version string — compared against the installed manifest */
+	version: string;
+	/**
+	* Installation scope.
+	* @default "global"
+	*/
+	scope?: Scope;
+	/**
+	* Automatically install skills when not yet present.
+	* Set to `true` to install on first CLI invocation without requiring the
+	* interactive skill command.
+	* @default false
+	*/
+	autoInstall?: boolean;
+	/**
+	* Automatically update skills when the installed version is outdated.
+	* @default true
+	*/
+	autoUpdate?: boolean;
+	/**
+	* Register an interactive skill management subcommand on the root command.
+	* - `true`: register with default name `"skill"`
+	* - `string`: register with a custom command name
+	* @default false
+	*/
+	command?: boolean | string;
+}
+/**
+* Detects which supported agents are installed by checking for the
+* existence of their global configuration directories.
+*
+* Detection always checks global paths regardless of the intended
+* installation scope — if the agent's global config directory exists,
+* the agent is considered installed.
+*
+* Detection table:
+* | Agent        | Config directory              |
+* | ------------ | ----------------------------- |
+* | `claude-code`| `<homedir>/.claude/`          |
+* | `opencode`   | `<homedir>/.config/opencode/` |
+*
+* @param home - Override the home directory for detection (defaults to `os.homedir()`).
+*               Primarily useful for testing.
+* @returns Array of detected agent targets (may be empty)
+*
+* @example
+* ```ts
+* const agents = await detectInstalledAgents();
+* // ["claude-code"] — only Claude Code config found
+* ```
+*/
+declare function detectInstalledAgents(home?: string): Promise<AgentTarget[]>;
+/**
+* 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
+*
+* @param options - Generation options including command, metadata, agents, and scope
+* @returns Per-agent installation results
+*
+* @example
+* ```ts
+* import { generateSkill } from "@crustjs/skills";
+* import { rootCommand } from "./commands.ts";
+*
+* const result = await generateSkill({
+*   command: rootCommand,
+*   meta: {
+*     name: "my-cli",
+*     description: "CLI tool for managing widgets",
+*     version: "1.0.0",
+*   },
+*   agents: ["claude-code", "opencode"],
+* });
+*
+* for (const r of result.agents) {
+*   console.log(`${r.agent}: ${r.status} → ${r.outputDir}`);
+* }
+* ```
+*/
+declare function generateSkill(options: GenerateOptions): Promise<GenerateResult>;
+/**
+* Removes installed skills from agent directories.
+*
+* @param options - Uninstall options specifying name, agents, and scope
+* @returns Per-agent uninstall results
+*/
+declare function uninstallSkill(options: UninstallOptions): Promise<UninstallResult>;
+/**
+* Checks the installation status of skills across agent directories.
+*
+* @param options - Status options specifying name, agents, and scope
+* @returns Per-agent status results
+*/
+declare function skillStatus(options: StatusOptions): Promise<StatusResult>;
+import { CrustPlugin } from "@crustjs/core";
+/**
+* Plugin that manages agent skills for a Crust CLI application.
+*
+* `name` and `description` are read from the root command's `meta` at setup
+* time — only `version` needs to be supplied in the options.
+*
+* Installed agents are detected automatically by checking for global
+* configuration directories. Only detected agents are managed by the
+* middleware and the interactive command.
+*
+* **Auto-update** (default): silently updates already-installed skills when a
+* 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.
+*
+* @param options - Plugin configuration with version and scope
+* @returns A `CrustPlugin` to register in a command's `plugins` array
+*
+* @example
+* ```ts
+* import { defineCommand, runMain } from "@crustjs/core";
+* import { skillPlugin } from "@crustjs/skills";
+*
+* const app = defineCommand({
+*   meta: { name: "my-cli", description: "My CLI" },
+*   plugins: [
+*     skillPlugin({
+*       version: "1.0.0",
+*       command: true, // registers "my-cli skill" subcommand
+*     }),
+*   ],
+* });
+*
+* runMain(app);
+* ```
+*/
+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 };

package/dist/index.js

@@ -0,0 +1,798 @@
+// @bun
+// src/agents.ts
+import { access } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var ALL_AGENTS = ["claude-code", "opencode"];
+var AGENT_LABELS = {
+  "claude-code": "Claude Code",
+  opencode: "OpenCode"
+};
+function resolveAgentPath(agent, scope, name) {
+  const base = scope === "global" ? homedir() : process.cwd();
+  switch (agent) {
+    case "claude-code":
+      return join(base, ".claude", "skills", name);
+    case "opencode":
+      if (scope === "global") {
+        return join(base, ".config", "opencode", "skills", name);
+      }
+      return join(base, ".opencode", "skills", name);
+  }
+}
+async function detectInstalledAgents(home) {
+  const resolvedHome = home ?? homedir();
+  const detected = [];
+  for (const agent of ALL_AGENTS) {
+    const configDir = resolveAgentConfigDir(resolvedHome, agent);
+    const exists = await access(configDir).then(() => true).catch(() => false);
+    if (exists) {
+      detected.push(agent);
+    }
+  }
+  return detected;
+}
+function resolveAgentConfigDir(home, agent) {
+  switch (agent) {
+    case "claude-code":
+      return join(home, ".claude");
+    case "opencode":
+      return join(home, ".config", "opencode");
+  }
+}
+// src/generate.ts
+import { access as access2, mkdir, rm, writeFile } from "fs/promises";
+import { dirname, join as join3 } from "path";
+
+// src/manifest.ts
+function buildManifest(command) {
+  return buildNode(command, []);
+}
+function buildNode(command, parentPath) {
+  const name = normalizeName(command.meta.name);
+  const path = [...parentPath, name];
+  const args = normalizeArgs(command.args);
+  const flags = normalizeFlags(command.flags);
+  const children = normalizeChildren(command.subCommands, path);
+  return {
+    name,
+    path,
+    description: command.meta.description,
+    usage: command.meta.usage,
+    runnable: typeof command.run === "function",
+    args,
+    flags,
+    children
+  };
+}
+function normalizeName(raw) {
+  return raw.trim().toLowerCase();
+}
+function normalizeArgs(argsDef) {
+  if (!argsDef || argsDef.length === 0)
+    return [];
+  return argsDef.map(normalizeArg);
+}
+function normalizeArg(arg) {
+  const result = {
+    name: arg.name,
+    type: arg.type,
+    required: arg.required === true,
+    variadic: arg.variadic === true
+  };
+  if (arg.description !== undefined) {
+    result.description = arg.description;
+  }
+  if (arg.default !== undefined) {
+    result.default = serializeDefault(arg.default);
+  }
+  return result;
+}
+function normalizeFlags(flagsDef) {
+  if (!flagsDef)
+    return [];
+  const keys = Object.keys(flagsDef).sort();
+  return keys.map((key) => {
+    return normalizeFlag(key, flagsDef[key]);
+  });
+}
+function normalizeFlag(name, flag) {
+  const result = {
+    name,
+    type: flag.type,
+    required: flag.required === true,
+    multiple: flag.multiple === true,
+    aliases: normalizeAliases(flag.alias)
+  };
+  if (flag.description !== undefined) {
+    result.description = flag.description;
+  }
+  if (flag.default !== undefined) {
+    result.default = serializeDefault(flag.default);
+  }
+  return result;
+}
+function normalizeAliases(alias) {
+  if (alias === undefined)
+    return [];
+  if (typeof alias === "string")
+    return [alias];
+  return [...alias].sort();
+}
+function normalizeChildren(subCommands, parentPath) {
+  const keys = Object.keys(subCommands).sort();
+  return keys.map((key) => {
+    return buildNode(subCommands[key], parentPath);
+  });
+}
+function serializeDefault(value) {
+  if (Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+// src/render.ts
+function renderSkill(manifest, meta) {
+  const files = [];
+  const allNodes = collectNodes(manifest);
+  files.push({
+    path: "SKILL.md",
+    content: renderSkillMd(manifest, meta)
+  });
+  files.push({
+    path: "command-index.md",
+    content: renderCommandIndex(manifest, allNodes)
+  });
+  for (const node of allNodes) {
+    const filePath = commandFilePath(node);
+    const content = node.children.length > 0 ? renderGroupCommand(node, manifest) : renderLeafCommand(node, manifest);
+    files.push({ path: filePath, content });
+  }
+  return files;
+}
+function collectNodes(root) {
+  const nodes = [root];
+  for (const child of root.children) {
+    nodes.push(...collectNodes(child));
+  }
+  return nodes;
+}
+function commandFilePath(node) {
+  if (node.path.length <= 1) {
+    return `commands/${node.name}.md`;
+  }
+  const segments = node.path.slice(1);
+  return `commands/${segments.join("/")}.md`;
+}
+function commandInvocation(node) {
+  return node.path.join(" ");
+}
+function relativePath(from, to) {
+  const fromParts = from.split("/").slice(0, -1);
+  const toParts = to.split("/");
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common++;
+  }
+  const ups = fromParts.length - common;
+  const remaining = toParts.slice(common);
+  if (ups === 0) {
+    return remaining.join("/");
+  }
+  const upSegments = Array.from({ length: ups }, () => "..");
+  return [...upSegments, ...remaining].join("/");
+}
+function renderSkillMd(manifest, meta) {
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${meta.name}`);
+  lines.push(`description: ${meta.description}`);
+  lines.push("metadata:");
+  lines.push(`  version: "${meta.version}"`);
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${meta.name}`);
+  lines.push("");
+  if (manifest.description) {
+    lines.push(manifest.description);
+    lines.push("");
+  }
+  lines.push("## Command Reference");
+  lines.push("");
+  lines.push("This skill provides documentation for all available CLI commands.");
+  lines.push("");
+  lines.push(`For a complete list of commands and their documentation paths, see [command-index.md](command-index.md).`);
+  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("");
+  if (manifest.children.length > 0) {
+    lines.push("## Available Commands");
+    lines.push("");
+    for (const child of manifest.children) {
+      const filePath = commandFilePath(child);
+      const desc = child.description ? ` - ${child.description}` : "";
+      lines.push(`- [\`${child.name}\`](${filePath})${desc}`);
+    }
+    lines.push("");
+  }
+  if (manifest.runnable) {
+    lines.push("## Usage");
+    lines.push("");
+    const rootFile = commandFilePath(manifest);
+    lines.push(`The root command is directly executable. See [${manifest.name}](${rootFile}) for usage details.`);
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function renderCommandIndex(_manifest, allNodes) {
+  const lines = [];
+  lines.push("# Command Index");
+  lines.push("");
+  lines.push("| Command | Type | Documentation |");
+  lines.push("| ------- | ---- | ------------- |");
+  for (const node of allNodes) {
+    const invocation = commandInvocation(node);
+    const filePath = commandFilePath(node);
+    const type = commandType(node);
+    lines.push(`| \`${invocation}\` | ${type} | [${filePath}](${filePath}) |`);
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}
+function commandType(node) {
+  if (node.runnable && node.children.length > 0) {
+    return "runnable, group";
+  }
+  if (node.runnable) {
+    return "runnable";
+  }
+  return "group";
+}
+function renderLeafCommand(node, root) {
+  const lines = [];
+  const invocation = commandInvocation(node);
+  lines.push(`# \`${invocation}\``);
+  lines.push("");
+  if (node.description) {
+    lines.push(node.description);
+    lines.push("");
+  }
+  lines.push("## Usage");
+  lines.push("");
+  if (node.usage) {
+    lines.push("```");
+    lines.push(node.usage);
+    lines.push("```");
+  } else {
+    lines.push("```");
+    lines.push(buildUsageLine(node));
+    lines.push("```");
+  }
+  lines.push("");
+  if (node.args.length > 0) {
+    lines.push("## Arguments");
+    lines.push("");
+    lines.push(...renderArgsTable(node.args));
+    lines.push("");
+  }
+  if (node.flags.length > 0) {
+    lines.push("## Flags");
+    lines.push("");
+    lines.push(...renderFlagsTable(node.flags));
+    lines.push("");
+  }
+  lines.push(...renderNavigation(node, root));
+  return lines.join(`
+`);
+}
+function renderGroupCommand(node, root) {
+  const lines = [];
+  const invocation = commandInvocation(node);
+  const filePath = commandFilePath(node);
+  lines.push(`# \`${invocation}\``);
+  lines.push("");
+  if (node.description) {
+    lines.push(node.description);
+    lines.push("");
+  }
+  if (node.runnable) {
+    lines.push("## Usage");
+    lines.push("");
+    if (node.usage) {
+      lines.push("```");
+      lines.push(node.usage);
+      lines.push("```");
+    } else {
+      lines.push("```");
+      lines.push(buildUsageLine(node));
+      lines.push("```");
+    }
+    lines.push("");
+    if (node.args.length > 0) {
+      lines.push("## Arguments");
+      lines.push("");
+      lines.push(...renderArgsTable(node.args));
+      lines.push("");
+    }
+    if (node.flags.length > 0) {
+      lines.push("## Flags");
+      lines.push("");
+      lines.push(...renderFlagsTable(node.flags));
+      lines.push("");
+    }
+  }
+  lines.push("## Subcommands");
+  lines.push("");
+  for (const child of node.children) {
+    const childPath = commandFilePath(child);
+    const childRelative = relativePath(filePath, childPath);
+    const desc = child.description ? ` - ${child.description}` : "";
+    lines.push(`- [\`${child.name}\`](${childRelative})${desc}`);
+  }
+  lines.push("");
+  lines.push(...renderNavigation(node, root));
+  return lines.join(`
+`);
+}
+function buildUsageLine(node) {
+  const parts = [...node.path];
+  for (const arg of node.args) {
+    if (arg.variadic) {
+      parts.push(arg.required ? `<${arg.name}...>` : `[${arg.name}...]`);
+    } else {
+      parts.push(arg.required ? `<${arg.name}>` : `[${arg.name}]`);
+    }
+  }
+  if (node.flags.length > 0) {
+    parts.push("[options]");
+  }
+  return parts.join(" ");
+}
+function renderArgsTable(args) {
+  const lines = [];
+  lines.push("| Argument | Type | Required | Description |");
+  lines.push("| -------- | ---- | -------- | ----------- |");
+  for (const arg of args) {
+    const name = arg.variadic ? `${arg.name}...` : arg.name;
+    const required = arg.required ? "Yes" : "No";
+    const desc = formatArgDescription(arg);
+    lines.push(`| \`${name}\` | ${arg.type} | ${required} | ${desc} |`);
+  }
+  return lines;
+}
+function formatArgDescription(arg) {
+  const parts = [];
+  if (arg.description) {
+    parts.push(arg.description);
+  }
+  if (arg.default !== undefined) {
+    parts.push(`Default: \`${arg.default}\``);
+  }
+  return parts.join(". ") || "-";
+}
+function renderFlagsTable(flags) {
+  const lines = [];
+  lines.push("| Flag | Type | Required | Description |");
+  lines.push("| ---- | ---- | -------- | ----------- |");
+  for (const flag of flags) {
+    const name = formatFlagName(flag);
+    const required = flag.required ? "Yes" : "No";
+    const desc = formatFlagDescription(flag);
+    lines.push(`| ${name} | ${flag.type} | ${required} | ${desc} |`);
+  }
+  return lines;
+}
+function formatFlagName(flag) {
+  const parts = [`\`--${flag.name}\``];
+  for (const alias of flag.aliases) {
+    parts.push(`\`-${alias}\``);
+  }
+  return parts.join(", ");
+}
+function formatFlagDescription(flag) {
+  const parts = [];
+  if (flag.description) {
+    parts.push(flag.description);
+  }
+  if (flag.multiple) {
+    parts.push("Can be specified multiple times");
+  }
+  if (flag.default !== undefined) {
+    parts.push(`Default: \`${flag.default}\``);
+  }
+  return parts.join(". ") || "-";
+}
+function renderNavigation(node, root) {
+  const lines = [];
+  const filePath = commandFilePath(node);
+  lines.push("---");
+  lines.push("");
+  if (node.path.length > 1) {
+    const parentPath = node.path.slice(0, -1);
+    const parentNode = findNode(root, parentPath);
+    if (parentNode) {
+      const parentFile = commandFilePath(parentNode);
+      const parentRelative = relativePath(filePath, parentFile);
+      const parentInvocation = commandInvocation(parentNode);
+      lines.push(`Parent: [\`${parentInvocation}\`](${parentRelative})`);
+      lines.push("");
+    }
+  }
+  const indexRelative = relativePath(filePath, "command-index.md");
+  lines.push(`[Command Index](${indexRelative})`);
+  lines.push("");
+  return lines;
+}
+function findNode(root, path) {
+  if (arraysEqual(root.path, path)) {
+    return root;
+  }
+  for (const child of root.children) {
+    const found = findNode(child, path);
+    if (found)
+      return found;
+  }
+  return;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  for (let i = 0;i < a.length; i++) {
+    if (a[i] !== b[i])
+      return false;
+  }
+  return true;
+}
+
+// src/version.ts
+import { readFile } from "fs/promises";
+import { join as join2 } from "path";
+async function readInstalledVersion(dir) {
+  try {
+    const raw = await readFile(join2(dir, "manifest.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed && typeof parsed.version === "string") {
+      return parsed.version;
+    }
+    return null;
+  } catch {
+    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
+async function generateSkill(options) {
+  const { command, meta, agents, scope = "global", clean = true } = options;
+  const manifest = buildManifest(command);
+  const renderedFiles = renderSkill(manifest, meta);
+  const metadataFiles = renderDistributionMetadata(manifest, meta);
+  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);
+    if (status === "up-to-date") {
+      results.push({
+        agent,
+        outputDir,
+        files: [],
+        status: "up-to-date"
+      });
+      continue;
+    }
+    const previousVersion = status === "updated" ? installedVersion ?? undefined : undefined;
+    if (clean) {
+      await cleanDirectory(outputDir);
+    }
+    await writeFiles(outputDir, allFiles);
+    results.push({
+      agent,
+      outputDir,
+      files: allFiles.map((f) => f.path),
+      status,
+      previousVersion
+    });
+  }
+  return { agents: results };
+}
+async function uninstallSkill(options) {
+  const { name, agents, scope = "global" } = options;
+  const results = [];
+  for (const agent of agents) {
+    const outputDir = resolveAgentPath(agent, scope, name);
+    const exists = await access2(outputDir).then(() => true).catch(() => false);
+    if (exists) {
+      await rm(outputDir, { recursive: true, force: true });
+      results.push({ agent, outputDir, status: "removed" });
+    } else {
+      results.push({ agent, outputDir, status: "not-found" });
+    }
+  }
+  return { agents: results };
+}
+async function skillStatus(options) {
+  const { name, agents, scope = "global" } = options;
+  const results = [];
+  for (const agent of agents) {
+    const outputDir = resolveAgentPath(agent, scope, name);
+    const version = await readInstalledVersion(outputDir);
+    results.push({
+      agent,
+      outputDir,
+      installed: version !== null,
+      version: version ?? undefined
+    });
+  }
+  return { agents: results };
+}
+function renderDistributionMetadata(manifest, meta) {
+  return [
+    {
+      path: "manifest.json",
+      content: renderManifestJson(manifest, meta)
+    }
+  ];
+}
+function renderManifestJson(manifest, meta) {
+  const commands = collectCommandPaths(manifest);
+  const obj = {
+    name: meta.name,
+    description: meta.description,
+    version: meta.version,
+    entrypoint: "SKILL.md",
+    commands
+  };
+  return `${JSON.stringify(obj, null, "\t")}
+`;
+}
+function collectCommandPaths(node) {
+  const paths = [node.path.join(" ")];
+  for (const child of node.children) {
+    paths.push(...collectCommandPaths(child));
+  }
+  return paths;
+}
+async function cleanDirectory(dir) {
+  await rm(dir, { recursive: true, force: true });
+}
+async function writeFiles(baseDir, files) {
+  const dirs = new Set;
+  for (const file of files) {
+    const filePath = join3(baseDir, file.path);
+    const dir = dirname(filePath);
+    dirs.add(dir);
+  }
+  const sortedDirs = [...dirs].sort();
+  for (const dir of sortedDirs) {
+    await mkdir(dir, { recursive: true });
+  }
+  for (const file of files) {
+    const filePath = join3(baseDir, file.path);
+    await writeFile(filePath, file.content, "utf-8");
+  }
+}
+// src/plugin.ts
+import { defineCommand } from "@crustjs/core";
+import { confirm, multiselect, select, spinner } from "@crustjs/prompts";
+function deriveSkillMeta(command, version) {
+  return {
+    name: command.meta.name,
+    description: command.meta.description ?? "",
+    version
+  };
+}
+function skillPlugin(options) {
+  let rootCmd;
+  let skillCmd = null;
+  return {
+    name: "skills",
+    setup(context, actions) {
+      rootCmd = context.rootCommand;
+      if (options.command) {
+        const name = typeof options.command === "string" ? options.command : "skill";
+        skillCmd = buildSkillCommand(rootCmd, options);
+        actions.addSubCommand(rootCmd, name, skillCmd);
+      }
+    },
+    async middleware(_context, next) {
+      if (skillCmd && _context.route?.command === skillCmd) {
+        await next();
+        return;
+      }
+      const agents = await detectInstalledAgents();
+      if (agents.length === 0) {
+        await next();
+        return;
+      }
+      const autoInstall = options.autoInstall ?? false;
+      const autoUpdate = options.autoUpdate ?? true;
+      const meta = deriveSkillMeta(rootCmd, options.version);
+      const status = await skillStatus({
+        name: meta.name,
+        agents,
+        scope: options.scope ?? "global"
+      });
+      const needsUpdate = status.agents.filter((a) => {
+        if (!a.installed)
+          return autoInstall;
+        if (a.version !== meta.version)
+          return autoUpdate;
+        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(", ")}`);
+        }
+      }
+      await next();
+    }
+  };
+}
+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"
+      }
+    },
+    async run({ flags }) {
+      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) {
+        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
+      });
+      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(`
+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(`
+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
+  });
+  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,
+  generateSkill,
+  detectInstalledAgents
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@crustjs/skills",
+	"version": "0.0.2",
+	"description": "Agent skill generation from Crust command definitions",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/skills"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"skills",
+		"agent",
+		"generation",
+		"documentation",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"@crustjs/core": "0.0.8",
+		"@crustjs/prompts": "0.0.4",
+		"bunup": "^0.16.29"
+	},
+	"peerDependencies": {
+		"@crustjs/core": "0.0.8",
+		"@crustjs/prompts": "0.0.4",
+		"typescript": "^5"
+	}
+}