@crustjs/skills 0.0.2 → 0.0.3

package/README.md

@@ -149,10 +149,10 @@ for (const file of files) {
 
 ## 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
@@ -162,7 +162,6 @@ skills/my-cli/
       migrate.md      # Nested subcommand
       seed.md
   manifest.json       # Machine-readable bundle metadata
-  README.md           # Install instructions for consumers
 ```
 
 ### File Details
@@ -173,7 +172,6 @@ skills/my-cli/
 | `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
 
@@ -182,13 +180,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

@@ -12,10 +12,18 @@ 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 manifest.json metadata. For example, `name: "my-cli"` produces output
+	* under `use-my-cli/`.
+	*/
 	name: string;
 	/** Human-readable description of what the CLI does */
 	description: string;
@@ -29,6 +37,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 +49,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",
 *   },
@@ -146,7 +158,7 @@ interface StatusResult {
 * are not yet present.
 *
 * **Interactive command**: set `command: true` to register a `skill` subcommand
-* on the root command for manual install/uninstall/status management.
+* that presents a single multiselect prompt for toggling agent installations.
 */
 interface SkillPluginOptions {
 	/** Skill version string — compared against the installed manifest */
@@ -170,6 +182,13 @@ 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
@@ -202,6 +221,22 @@ interface SkillPluginOptions {
 */
 declare function detectInstalledAgents(home?: string): Promise<AgentTarget[]>;
 /**
+* Resolves the canonical skill name by applying the `use-` prefix.
+*
+* All generated output (directory names, manifest 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:
@@ -265,9 +300,10 @@ import { CrustPlugin } from "@crustjs/core";
 * 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.
+* 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.
 *
 * @param options - Plugin configuration with version and scope
 * @returns A `CrustPlugin` to register in a command's `plugins` array
@@ -291,4 +327,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, generateSkill, detectInstalledAgents, UninstallStatus, UninstallResult, UninstallOptions, StatusResult, StatusOptions, SkillPluginOptions, SkillMeta, Scope, InstallStatus, GenerateResult, GenerateOptions, AgentTarget, AgentResult };

package/dist/index.js

@@ -474,16 +474,23 @@ async function checkVersion(dir, newVersion) {
 }
 
 // src/generate.ts
+function resolveSkillName(name) {
+  return name.startsWith("use-") ? name : `use-${name}`;
+}
 async function generateSkill(options) {
   const { command, meta, agents, scope = "global", clean = true } = options;
+  const resolvedMeta = {
+    ...meta,
+    name: resolveSkillName(meta.name)
+  };
   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 { status, installedVersion } = await checkVersion(outputDir, resolvedMeta.version);
     if (status === "up-to-date") {
       results.push({
         agent,
@@ -510,9 +517,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 +533,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,
@@ -586,7 +595,7 @@ async function writeFiles(baseDir, files) {
 }
 // src/plugin.ts
 import { defineCommand } from "@crustjs/core";
-import { confirm, multiselect, select, spinner } from "@crustjs/prompts";
+import { multiselect, spinner } from "@crustjs/prompts";
 function deriveSkillMeta(command, version) {
   return {
     name: command.meta.name,
@@ -652,147 +661,88 @@ function buildSkillCommand(rootCmd, options) {
   return defineCommand({
     meta: {
       name: "skill",
-      description: "Manage agent skills (install, uninstall, status)"
+      description: "Manage agent skill installations"
     },
-    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 }) {
+    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) {
+        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}`);
+        }
+      }
+      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,
   generateSkill,
   detectInstalledAgents
 };

package/package.json

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