@senso-ai/shipables 0.1.0 → 0.1.1

package/dist/index.js

@@ -101,6 +101,72 @@ var init_config = __esm({
   }
 });
 
+// src/lib/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  CliError: () => CliError,
+  EXIT_AUTH: () => EXIT_AUTH,
+  EXIT_CONFLICT: () => EXIT_CONFLICT,
+  EXIT_ERROR: () => EXIT_ERROR,
+  EXIT_NETWORK: () => EXIT_NETWORK,
+  EXIT_NOT_FOUND: () => EXIT_NOT_FOUND,
+  EXIT_SUCCESS: () => EXIT_SUCCESS,
+  EXIT_USAGE: () => EXIT_USAGE,
+  EXIT_VALIDATION: () => EXIT_VALIDATION,
+  authError: () => authError,
+  conflictError: () => conflictError,
+  networkError: () => networkError,
+  notFoundError: () => notFoundError,
+  usageError: () => usageError,
+  validationError: () => validationError
+});
+function authError(message, fix) {
+  return new CliError(message, "AUTH_REQUIRED", EXIT_AUTH, fix || "Run `shipables login` to authenticate.");
+}
+function notFoundError(message, fix) {
+  return new CliError(message, "NOT_FOUND", EXIT_NOT_FOUND, fix);
+}
+function networkError(message, fix) {
+  return new CliError(
+    message,
+    "NETWORK_ERROR",
+    EXIT_NETWORK,
+    fix || "Check your internet connection or registry URL with: shipables config get registry"
+  );
+}
+function validationError(message, fix) {
+  return new CliError(message, "VALIDATION_ERROR", EXIT_VALIDATION, fix);
+}
+function usageError(message, fix) {
+  return new CliError(message, "USAGE_ERROR", EXIT_USAGE, fix);
+}
+function conflictError(message, fix) {
+  return new CliError(message, "CONFLICT", EXIT_CONFLICT, fix);
+}
+var EXIT_SUCCESS, EXIT_ERROR, EXIT_USAGE, EXIT_AUTH, EXIT_NOT_FOUND, EXIT_NETWORK, EXIT_VALIDATION, EXIT_CONFLICT, CliError;
+var init_errors = __esm({
+  "src/lib/errors.ts"() {
+    "use strict";
+    EXIT_SUCCESS = 0;
+    EXIT_ERROR = 1;
+    EXIT_USAGE = 2;
+    EXIT_AUTH = 3;
+    EXIT_NOT_FOUND = 4;
+    EXIT_NETWORK = 5;
+    EXIT_VALIDATION = 6;
+    EXIT_CONFLICT = 7;
+    CliError = class extends Error {
+      constructor(message, code, exitCode, fix) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.fix = fix;
+        this.name = "CliError";
+      }
+    };
+  }
+});
+
 // src/registry/client.ts
 import { createReadStream } from "fs";
 import { readFile as readFile2 } from "fs/promises";
@@ -122,6 +188,7 @@ var init_client = __esm({
   "src/registry/client.ts"() {
     "use strict";
     init_config();
+    init_errors();
     cachedVersion = null;
     RegistryClient = class {
       registryUrl = null;
@@ -165,7 +232,7 @@ var init_client = __esm({
           return await fetch(url, init);
         } catch (err) {
           if (err instanceof TypeError && err.message === "fetch failed") {
-            throw new Error(
+            throw networkError(
               `Could not connect to registry at ${base}. Check your internet connection or registry URL.`
             );
           }
@@ -186,7 +253,9 @@ var init_client = __esm({
           headers: await this.getHeaders()
         });
         if (!resp.ok) {
-          throw new Error(`Search failed: ${resp.status} ${resp.statusText}`);
+          throw networkError(
+            `Search for '${params.q || ""}' failed (HTTP ${resp.status}). Verify your registry URL with: shipables config get registry`
+          );
         }
         return await resp.json();
       }
@@ -198,10 +267,13 @@ var init_client = __esm({
         });
         if (!resp.ok) {
           if (resp.status === 404) {
-            throw new Error(`Skill not found: ${fullName}`);
+            throw notFoundError(
+              `Skill '${fullName}' not found in the registry.`,
+              `Search for available skills with: shipables search <query>`
+            );
           }
-          throw new Error(
-            `Failed to get skill detail: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to get skill detail for '${fullName}' (HTTP ${resp.status}).`
           );
         }
         return await resp.json();
@@ -215,10 +287,13 @@ var init_client = __esm({
         );
         if (!resp.ok) {
           if (resp.status === 404) {
-            throw new Error(`Version not found: ${fullName}@${version}`);
+            throw notFoundError(
+              `Version '${fullName}@${version}' not found.`,
+              `List available versions with: shipables info ${fullName}`
+            );
           }
-          throw new Error(
-            `Failed to get version: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to get version '${fullName}@${version}' (HTTP ${resp.status}).`
           );
         }
         return await resp.json();
@@ -231,8 +306,9 @@ var init_client = __esm({
           { headers: await this.getHeaders() }
         );
         if (!resp.ok) {
-          throw new Error(
-            `Failed to download tarball: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to download tarball '${filename}' (HTTP ${resp.status}).`,
+            `Re-run the install command. If the error persists, the package may have been removed.`
           );
         }
         const integrity = resp.headers.get("X-Integrity") || "";
@@ -243,8 +319,9 @@ var init_client = __esm({
         const base = await this.getBaseUrl();
         const headers = await this.getHeaders(true);
         if (!headers["Authorization"]) {
-          throw new Error(
-            "Not authenticated. Run `shipables login` first."
+          throw authError(
+            "Not authenticated. You must be logged in to publish.",
+            "Run `shipables login` to authenticate, then re-run `shipables publish`."
           );
         }
         const fileStream = createReadStream(tarballPath);
@@ -265,13 +342,25 @@ var init_client = __esm({
         });
         if (!resp.ok) {
           const body = await resp.text();
-          let message = `Publish failed: ${resp.status} ${resp.statusText}`;
+          let message = `Publish failed (HTTP ${resp.status}).`;
+          let details = "";
           try {
             const err = JSON.parse(body);
             if (err.error?.message) message = err.error.message;
+            if (err.error?.details) details = JSON.stringify(err.error.details);
           } catch {
           }
-          throw new Error(message);
+          if (resp.status === 401) {
+            throw authError(message, "Run `shipables login` to re-authenticate, then re-run `shipables publish`.");
+          }
+          if (resp.status === 409) {
+            const { conflictError: conflictError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+            throw conflictError2(
+              message + (details ? ` Details: ${details}` : ""),
+              "Bump the version in shipables.json and re-run `shipables publish`."
+            );
+          }
+          throw new Error(message + (details ? ` Details: ${details}` : ""));
         }
         return await resp.json();
       }
@@ -287,15 +376,21 @@ var init_client = __esm({
         );
         if (!resp.ok) {
           if (resp.status === 404) {
-            throw new Error(`Version not found: ${fullName}@${version}`);
+            throw notFoundError(
+              `Version '${fullName}@${version}' not found.`,
+              `Check available versions with: shipables info ${fullName}`
+            );
           }
           const body = await resp.text();
-          let message = `Unpublish failed: ${resp.status} ${resp.statusText}`;
+          let message = `Unpublish failed (HTTP ${resp.status}).`;
           try {
             const err = JSON.parse(body);
             if (err.error?.message) message = err.error.message;
           } catch {
           }
+          if (resp.status === 401) {
+            throw authError(message, "Run `shipables login` to re-authenticate.");
+          }
           throw new Error(message);
         }
       }
@@ -308,10 +403,13 @@ var init_client = __esm({
         );
         if (!resp.ok) {
           if (resp.status === 404) {
-            throw new Error(`Skill not found: ${fullName}`);
+            throw notFoundError(
+              `Skill '${fullName}' not found.`,
+              `Search for available skills with: shipables search <query>`
+            );
           }
-          throw new Error(
-            `Failed to get download stats: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to get download stats for '${fullName}' (HTTP ${resp.status}).`
           );
         }
         return await resp.json();
@@ -324,10 +422,13 @@ var init_client = __esm({
         );
         if (!resp.ok) {
           if (resp.status === 404) {
-            throw new Error(`User not found: ${username}`);
+            throw notFoundError(
+              `User '${username}' not found.`,
+              `Check the username and try again.`
+            );
           }
-          throw new Error(
-            `Failed to get user profile: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to get user profile for '${username}' (HTTP ${resp.status}).`
           );
         }
         return await resp.json();
@@ -339,8 +440,8 @@ var init_client = __esm({
           { headers: await this.getHeaders() }
         );
         if (!resp.ok) {
-          throw new Error(
-            `Failed to get user skills: ${resp.status} ${resp.statusText}`
+          throw networkError(
+            `Failed to get skills for user '${username}' (HTTP ${resp.status}).`
           );
         }
         return await resp.json();
@@ -352,9 +453,12 @@ var init_client = __esm({
         });
         if (!resp.ok) {
           if (resp.status === 401) {
-            throw new Error("Not authenticated. Run `shipables login` first.");
+            throw authError(
+              "Not authenticated or session expired.",
+              "Run `shipables login` to re-authenticate."
+            );
           }
-          throw new Error(`Failed to get profile: ${resp.status}`);
+          throw networkError(`Failed to get profile (HTTP ${resp.status}).`);
         }
         return await resp.json();
       }
@@ -825,27 +929,49 @@ var init_config2 = __esm({
 
 // src/lib/output.ts
 import chalk from "chalk";
+import ora from "ora";
+function isInteractive() {
+  return process.stdin.isTTY === true && !process.env.CI;
+}
+function setJsonMode(enabled) {
+  jsonMode = enabled;
+}
+function getJsonMode() {
+  return jsonMode;
+}
 function success(message) {
+  if (jsonMode) return;
   console.log(chalk.green("  \u2713 ") + message);
 }
 function error(message) {
+  if (jsonMode) return;
+  console.error(chalk.red("  \u2717 ") + message);
+}
+function errorWithFix(message, fix) {
+  if (jsonMode) return;
   console.error(chalk.red("  \u2717 ") + message);
+  console.error(chalk.dim("    Fix: ") + fix);
 }
 function warn(message) {
+  if (jsonMode) return;
   console.log(chalk.yellow("  \u26A0 ") + message);
 }
 function info(message) {
+  if (jsonMode) return;
   console.log(chalk.cyan("  ") + message);
 }
 function blank() {
+  if (jsonMode) return;
   console.log();
 }
 function header(message) {
+  if (jsonMode) return;
   console.log();
   console.log(chalk.bold("  " + message));
   console.log();
 }
 function table(headers, rows, columnWidths) {
+  if (jsonMode) return;
   const widths = columnWidths || headers.map(
     (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] || "").length))
   );
@@ -864,9 +990,47 @@ function formatBytes(bytes) {
 function formatNumber(n) {
   return n.toLocaleString("en-US");
 }
+function spinner(text) {
+  if (process.stdin.isTTY && !process.env.CI && !jsonMode) {
+    return ora(text).start();
+  }
+  if (!jsonMode) {
+    console.error(`  \u2026 ${text}`);
+  }
+  return {
+    succeed(msg) {
+      if (!jsonMode && msg) console.error(`  \u2713 ${msg}`);
+      return this;
+    },
+    fail(msg) {
+      if (!jsonMode && msg) console.error(`  \u2717 ${msg}`);
+      return this;
+    },
+    stop() {
+      return this;
+    },
+    start(msg) {
+      if (!jsonMode && msg) console.error(`  \u2026 ${msg}`);
+      return this;
+    },
+    warn(msg) {
+      if (!jsonMode && msg) console.error(`  \u26A0 ${msg}`);
+      return this;
+    },
+    info(msg) {
+      if (!jsonMode && msg) console.error(`  \u2139 ${msg}`);
+      return this;
+    },
+    text,
+    isSpinning: false
+  };
+}
+var jsonMode;
 var init_output = __esm({
   "src/lib/output.ts"() {
     "use strict";
+    init_errors();
+    jsonMode = false;
   }
 });
 
@@ -879,7 +1043,6 @@ import { cp, mkdir as mkdir3 } from "fs/promises";
 import { join as join5, resolve } from "path";
 import { Command } from "commander";
 import chalk2 from "chalk";
-import ora from "ora";
 import { checkbox } from "@inquirer/prompts";
 import { input, password } from "@inquirer/prompts";
 import { writeFile as writeFile4 } from "fs/promises";
@@ -909,13 +1072,24 @@ function getBareName(fullName) {
   return fullName;
 }
 function createInstallCommand() {
-  return new Command("install").argument("<skill>", "Skill name, optionally with version (e.g., neo4j, neo4j@1.2.0)").option("--claude", "Install for Claude Code").option("--cursor", "Install for Cursor").option("--codex", "Install for Codex CLI").option("--copilot", "Install for VS Code / Copilot").option("--gemini", "Install for Gemini CLI").option("--cline", "Install for Cline").option("--all", "Install for all detected agents").option("-g, --global", "Install to user-level skills directory").option("-y, --yes", "Skip confirmation prompts").option("--no-mcp", "Skip MCP server configuration").option("--registry <url>", "Use a custom registry URL").description("Install a skill from the registry").action(async (skillArg, options) => {
+  return new Command("install").argument("<skill>", "Skill name, optionally with version (e.g., Chippers255/ai-commits, Chippers255/ai-commits@1.0.0)").option("--claude", "Install for Claude Code").option("--cursor", "Install for Cursor").option("--codex", "Install for Codex CLI").option("--copilot", "Install for VS Code / Copilot").option("--gemini", "Install for Gemini CLI").option("--cline", "Install for Cline").option("--all", "Install for all detected agents").option("-g, --global", "Install to user-level skills directory").option("-y, --yes", "Skip confirmation prompts").option("--no-mcp", "Skip MCP server configuration").option("--env <values...>", "Set MCP environment variables (e.g., --env API_KEY=xxx DB_HOST=localhost)").option("--registry <url>", "Use a custom registry URL").description(
+    "Install a skill from the registry into the current project. Downloads the skill package, extracts it to agent-specific directories, and configures MCP servers if the skill declares them."
+  ).addHelpText("after", `
+Examples:
+  shipables install neo4j --claude           Install latest version for Claude Code
+  shipables install neo4j@1.2.0 --all       Install specific version for all agents
+  shipables install @myorg/tool --cursor -y  Install scoped skill, skip prompts
+  shipables install neo4j --claude --no-mcp  Install without MCP configuration
+  shipables install neo4j --claude --env API_KEY=xxx  Pass MCP env vars
+`).action(async (skillArg, options) => {
     try {
       await runInstall(skillArg, options);
     } catch (err) {
-      error(
-        err instanceof Error ? err.message : String(err)
-      );
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
+      error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
@@ -924,21 +1098,30 @@ async function runInstall(skillArg, options) {
   const { name: skillName, version: requestedVersion } = parseSkillArg(skillArg);
   const bareName = getBareName(skillName);
   const scope = options.global ? "global" : "project";
-  const spinner = ora(`Resolving ${skillName}@${requestedVersion}...`).start();
+  const envMap = {};
+  if (options.env) {
+    for (const pair of options.env) {
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx > 0) {
+        envMap[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+      }
+    }
+  }
+  const resolveSpinner = spinner(`Resolving ${skillName}@${requestedVersion}...`);
   let versionDetail;
   try {
     versionDetail = await registry.getVersionDetail(skillName, requestedVersion);
-    spinner.succeed(
+    resolveSpinner.succeed(
       `Resolved ${skillName}@${requestedVersion} \u2192 ${chalk2.bold(versionDetail.version)}`
     );
   } catch (err) {
-    spinner.fail(`Failed to resolve ${skillName}@${requestedVersion}`);
+    resolveSpinner.fail(`Failed to resolve ${skillName}@${requestedVersion}`);
     throw err;
   }
   const filename = `${bareName}-${versionDetail.version}.tgz`;
-  const downloadSpinner = ora(
+  const downloadSpinner = spinner(
     `Downloading ${filename} (${formatSize(versionDetail.size_bytes)})...`
-  ).start();
+  );
   let tarballData;
   let serverIntegrity;
   try {
@@ -951,7 +1134,7 @@ async function runInstall(skillArg, options) {
     throw err;
   }
   if (serverIntegrity && versionDetail.tarball_sha512) {
-    const integritySpinner = ora("Verifying integrity...").start();
+    const integritySpinner = spinner("Verifying integrity...");
     if (verifyIntegrity(tarballData, versionDetail.tarball_sha512)) {
       integritySpinner.succeed("Integrity verified");
     } else {
@@ -1002,7 +1185,7 @@ async function runInstall(skillArg, options) {
     const envSchemas = manifest.config?.env || [];
     if (envSchemas.length > 0) {
       for (const envVar of envSchemas) {
-        const value = await promptEnvVar(envVar, options.yes);
+        const value = await promptEnvVar(envVar, options.yes, envMap);
         envValues[envVar.name] = value;
       }
       blank();
@@ -1062,6 +1245,11 @@ async function selectAgents(options) {
     return detected.length > 0 ? detected : ALL_ADAPTERS;
   }
   if (detected.length === 0) {
+    if (!isInteractive()) {
+      throw usageError(
+        "No agents detected and no agent flags specified. Use --claude, --cursor, --codex, --copilot, --gemini, --cline, or --all."
+      );
+    }
     console.log(
       chalk2.yellow(
         "\n  No agents auto-detected. Select which agents to install for:\n"
@@ -1079,6 +1267,9 @@ async function selectAgents(options) {
   if (detected.length === 1) {
     return detected;
   }
+  if (!isInteractive()) {
+    return detected;
+  }
   const selected = await checkbox({
     message: "Multiple agents detected. Select which to install for:",
     choices: detected.map((a) => ({
@@ -1089,7 +1280,10 @@ async function selectAgents(options) {
   });
   return selected.map((name) => getAdapter(name)).filter(Boolean);
 }
-async function promptEnvVar(envVar, autoYes) {
+async function promptEnvVar(envVar, autoYes, envMap) {
+  if (envMap && envVar.name in envMap) {
+    return envMap[envVar.name];
+  }
   const label = [
     envVar.name,
     envVar.required ? "(required" : "(optional",
@@ -1099,6 +1293,13 @@ async function promptEnvVar(envVar, autoYes) {
   if (autoYes && envVar.default) {
     return envVar.default;
   }
+  if (!isInteractive()) {
+    if (envVar.default) {
+      return envVar.default;
+    }
+    warn(`No value provided for ${envVar.name} \u2014 using empty string. Pass --env ${envVar.name}=<value> to set it.`);
+    return "";
+  }
   if (envVar.secret) {
     return await password({
       message: `    Enter value for ${envVar.name}:`
@@ -1140,6 +1341,8 @@ var init_install = __esm({
     init_config();
     init_config2();
     init_output();
+    init_output();
+    init_errors();
   }
 });
 
@@ -1151,15 +1354,28 @@ import { Command as Command15 } from "commander";
 init_config();
 init_adapters();
 init_output();
+init_errors();
 import { rm } from "fs/promises";
 import { resolve as resolve2 } from "path";
 import { Command as Command2 } from "commander";
 import chalk3 from "chalk";
 function createUninstallCommand() {
-  return new Command2("uninstall").argument("<skill>", "Skill name to uninstall").option("--claude", "Uninstall from Claude Code").option("--cursor", "Uninstall from Cursor").option("--codex", "Uninstall from Codex CLI").option("--copilot", "Uninstall from VS Code / Copilot").option("--gemini", "Uninstall from Gemini CLI").option("--cline", "Uninstall from Cline").option("-g, --global", "Uninstall from global skills directory").description("Remove a skill and its configuration").action(async (skillName, options) => {
+  return new Command2("uninstall").argument("<skill>", "Skill name to uninstall").option("--claude", "Uninstall from Claude Code only").option("--cursor", "Uninstall from Cursor only").option("--codex", "Uninstall from Codex CLI only").option("--copilot", "Uninstall from VS Code / Copilot only").option("--gemini", "Uninstall from Gemini CLI only").option("--cline", "Uninstall from Cline only").option("-g, --global", "Uninstall from global skills directory").description(
+    "Remove a skill and its MCP configuration. Removes skill files and MCP server entries for all agents, or specific agents if flags are provided."
+  ).addHelpText("after", `
+Examples:
+  shipables uninstall Chippers255/ai-commits               Remove from all agents
+  shipables uninstall Chippers255/ai-commits --claude      Remove from Claude Code only
+  shipables uninstall Chippers255/ai-commits -g            Remove globally installed skill
+  shipables uninstall @org/tool --cursor  Remove scoped skill from Cursor
+`).action(async (skillName, options) => {
     try {
       await runUninstall(skillName, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -1169,8 +1385,9 @@ async function runUninstall(skillName, options) {
   const projectPath = options.global ? "__global__" : process.cwd();
   const record = await getInstallation(projectPath, skillName);
   if (!record) {
-    throw new Error(
-      `${skillName} is not installed${options.global ? " globally" : " in this project"}`
+    throw notFoundError(
+      `'${skillName}' is not installed${options.global ? " globally" : " in this project"}.`,
+      `List installed skills with: shipables list${options.global ? " --global" : ""}`
     );
   }
   const flagMap = {
@@ -1184,8 +1401,9 @@ async function runUninstall(skillName, options) {
   const hasFlags = Object.values(flagMap).some(Boolean);
   const targetAgents = hasFlags ? record.agents.filter((a) => flagMap[a]) : record.agents;
   if (targetAgents.length === 0) {
-    throw new Error(
-      `${skillName} is not installed for the specified agent(s)`
+    throw notFoundError(
+      `'${skillName}' is not installed for the specified agent(s).`,
+      `Currently installed for: ${record.agents.join(", ")}`
     );
   }
   for (const agentName of targetAgents) {
@@ -1235,40 +1453,56 @@ async function runUninstall(skillName, options) {
   success(
     `Uninstalled ${chalk3.bold(skillName)} from ${targetAgents.map((a) => getAdapter(a)?.displayName || a).join(", ")}`
   );
+  info("Verify with: shipables list");
   blank();
 }
 
 // src/commands/search.ts
 init_client();
 init_output();
+init_output();
+init_errors();
 import { Command as Command3 } from "commander";
-import ora2 from "ora";
 function createSearchCommand() {
-  return new Command3("search").argument("<query>", "Search query").option("--agent <name>", "Filter by agent compatibility").option("--category <slug>", "Filter by category").option("--limit <n>", "Max results", "10").option("--json", "Output as JSON").description("Search the registry for skills").action(async (query, options) => {
+  return new Command3("search").argument("<query>", "Search query").option("--agent <name>", "Filter by agent compatibility (claude, cursor, codex, copilot, gemini, cline)").option("--category <slug>", "Filter by category").option("--limit <n>", "Max results", "10").option("--json", "Output as JSON").description(
+    "Search the registry for skills. Returns skill name, version, weekly downloads, and description. Use --json for structured output."
+  ).addHelpText("after", `
+Examples:
+  shipables search "database"                 Search for database-related skills
+  shipables search "auth" --agent claude      Search skills compatible with Claude
+  shipables search "testing" --category qa    Search within a category
+  shipables search "deploy" --json            Get results as JSON
+  shipables search "api" --limit 20           Get more results
+`).action(async (query, options) => {
     try {
       await runSearch(query, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
 async function runSearch(query, options) {
-  const spinner = ora2("Searching...").start();
+  const searchSpinner = spinner("Searching...");
   const result = await registry.search({
     q: query,
     agent: options.agent,
     category: options.category,
     limit: parseInt(options.limit || "10", 10)
   });
-  spinner.stop();
-  if (options.json) {
+  searchSpinner.stop();
+  if (options.json || getJsonMode()) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
   if (result.skills.length === 0) {
     blank();
-    info("No skills found matching your query.");
+    info(`No skills found matching "${query}".`);
+    info("Try a broader query or browse categories at https://shipables.dev");
     blank();
     return;
   }
@@ -1287,6 +1521,10 @@ async function runSearch(query, options) {
   info(
     `${result.pagination.total} result${result.pagination.total === 1 ? "" : "s"} found`
   );
+  if (result.skills.length > 0) {
+    info(`Get details: shipables info ${result.skills[0].full_name}`);
+    info(`Install:     shipables install ${result.skills[0].full_name} --<agent>`);
+  }
   blank();
 }
 function truncate(s, max) {
@@ -1297,24 +1535,36 @@ function truncate(s, max) {
 // src/commands/info.ts
 init_client();
 init_output();
+init_output();
+init_errors();
 import { Command as Command4 } from "commander";
 import chalk4 from "chalk";
-import ora3 from "ora";
 function createInfoCommand() {
-  return new Command4("info").argument("<skill>", "Skill name").option("--json", "Output as JSON").description("Show detailed information about a skill").action(async (skillName, options) => {
+  return new Command4("info").argument("<skill>", "Skill name (e.g., Chippers255/ai-commits, @org/my-skill)").option("--json", "Output as JSON").description(
+    "Show detailed information about a skill including versions, MCP servers, categories, and download counts."
+  ).addHelpText("after", `
+Examples:
+  shipables info Chippers255/ai-commits          Show details for a skill
+  shipables info @org/my-skill                    Show details for a scoped skill
+  shipables info Chippers255/ai-commits --json    Get details as JSON
+`).action(async (skillName, options) => {
     try {
       await runInfo(skillName, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
 async function runInfo(skillName, options) {
-  const spinner = ora3(`Fetching info for ${skillName}...`).start();
+  const infoSpinner = spinner(`Fetching info for ${skillName}...`);
   const detail = await registry.getSkillDetail(skillName);
-  spinner.stop();
-  if (options.json) {
+  infoSpinner.stop();
+  if (options.json || getJsonMode()) {
     console.log(JSON.stringify(detail, null, 2));
     return;
   }
@@ -1350,7 +1600,7 @@ async function runInfo(skillName, options) {
   }
   if (detail.config?.env && detail.config.env.length > 0) {
     blank();
-    info("Config:");
+    info("Required environment variables:");
     for (const envVar of detail.config.env) {
       const flags = [
         envVar.required ? "required" : "optional",
@@ -1376,17 +1626,26 @@ async function runInfo(skillName, options) {
     }
   }
   blank();
-  info(`Install: ${chalk4.cyan(`npx shipables install ${detail.full_name}`)}`);
+  info(`Install: shipables install ${detail.full_name}`);
+  info(`Install for specific agent: shipables install ${detail.full_name} --claude`);
   blank();
 }
 
 // src/commands/list.ts
 init_config();
 init_output();
+init_output();
 import { Command as Command5 } from "commander";
-import chalk5 from "chalk";
 function createListCommand() {
-  return new Command5("list").alias("ls").option("--json", "Output as JSON").option("-g, --global", "Show globally installed skills").description("List installed skills").action(async (options) => {
+  return new Command5("list").alias("ls").option("--json", "Output as JSON").option("-g, --global", "Show globally installed skills").description(
+    "List installed skills in the current project (or globally with -g). Shows skill name, version, and which agents it's installed for."
+  ).addHelpText("after", `
+Examples:
+  shipables list            List skills in current project
+  shipables list --global   List globally installed skills
+  shipables list --json     Get installed skills as JSON
+  shipables ls              Alias for list
+`).action(async (options) => {
     try {
       await runList(options);
     } catch (err) {
@@ -1399,7 +1658,7 @@ async function runList(options) {
   const projectPath = options.global ? "__global__" : process.cwd();
   const installations = await getProjectInstallations(projectPath);
   const entries = Object.entries(installations);
-  if (options.json) {
+  if (options.json || getJsonMode()) {
     console.log(JSON.stringify(installations, null, 2));
     return;
   }
@@ -1408,9 +1667,8 @@ async function runList(options) {
     info(
       options.global ? "No skills installed globally." : "No skills installed in this project."
     );
-    info(
-      chalk5.dim("Install one with: npx shipables install <skill>")
-    );
+    info("Install one with: shipables install <skill>");
+    info("Search for skills: shipables search <query>");
     blank();
     return;
   }
@@ -1427,6 +1685,7 @@ async function runList(options) {
   );
   blank();
   info(`${entries.length} skill${entries.length === 1 ? "" : "s"} installed`);
+  info("Check for updates: shipables update");
   blank();
 }
 
@@ -1434,12 +1693,22 @@ async function runList(options) {
 init_config();
 init_client();
 init_output();
+init_output();
+init_errors();
 import { Command as Command6 } from "commander";
-import chalk6 from "chalk";
-import ora4 from "ora";
+import chalk5 from "chalk";
 import { confirm } from "@inquirer/prompts";
 function createUpdateCommand() {
-  return new Command6("update").argument("[skill]", "Skill to update (omit to update all)").option("--dry-run", "Show what would be updated without making changes").option("-g, --global", "Update globally installed skills").option("--self", "Update the shipables CLI itself").description("Update installed skills to latest version").action(async (skill, options) => {
+  return new Command6("update").argument("[skill]", "Skill to update (omit to update all)").option("--dry-run", "Show what would be updated without making changes").option("-g, --global", "Update globally installed skills").option("-y, --yes", "Skip confirmation prompt").option("--self", "Update the shipables CLI itself").description(
+    "Update installed skills to latest version. If no skill is specified, checks all installed skills for updates. Use --yes to skip the confirmation prompt."
+  ).addHelpText("after", `
+Examples:
+  shipables update                  Check and update all installed skills
+  shipables update Chippers255/ai-commits  Update a specific skill
+  shipables update --dry-run        Show available updates without installing
+  shipables update --yes            Update all without confirmation
+  shipables update --self           Update the shipables CLI itself
+`).action(async (skill, options) => {
     try {
       if (options.self) {
         await runSelfUpdate();
@@ -1447,6 +1716,10 @@ function createUpdateCommand() {
       }
       await runUpdate(skill, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -1456,7 +1729,7 @@ async function runSelfUpdate() {
   blank();
   info("To update the shipables CLI, run:");
   blank();
-  console.log(chalk6.cyan("  npm update -g shipables"));
+  console.log(chalk5.cyan("  npm update -g @senso-ai/shipables"));
   blank();
   info("Or if you installed with npx, it automatically uses the latest version.");
   blank();
@@ -1468,14 +1741,18 @@ async function runUpdate(skill, options) {
   if (entries.length === 0) {
     blank();
     info("No skills installed to update.");
+    info("Install a skill with: shipables install <skill>");
     blank();
     return;
   }
   const toCheck = skill ? entries.filter(([name]) => name === skill) : entries;
   if (toCheck.length === 0) {
-    throw new Error(`${skill} is not installed`);
+    throw notFoundError(
+      `'${skill}' is not installed${options.global ? " globally" : " in this project"}.`,
+      `List installed skills with: shipables list${options.global ? " --global" : ""}`
+    );
   }
-  const spinner = ora4("Checking for updates...").start();
+  const checkSpinner = spinner("Checking for updates...");
   const updates = [];
   for (const [name, record] of toCheck) {
     try {
@@ -1497,7 +1774,7 @@ async function runUpdate(skill, options) {
       });
     }
   }
-  spinner.stop();
+  checkSpinner.stop();
   blank();
   table(
     ["SKILL", "CURRENT", "LATEST", "STATUS"],
@@ -1505,33 +1782,36 @@ async function runUpdate(skill, options) {
       u.name,
       u.currentVersion,
       u.latestVersion,
-      u.hasUpdate ? chalk6.yellow("update available") : chalk6.green("up to date")
+      u.hasUpdate ? chalk5.yellow("update available") : chalk5.green("up to date")
     ]),
     [25, 10, 10, 20]
   );
   const updatable = updates.filter((u) => u.hasUpdate);
   if (updatable.length === 0) {
     blank();
-    success("All skills are up to date");
+    success("All skills are up to date.");
     blank();
     return;
   }
   if (options.dryRun) {
     blank();
     info(
-      `${updatable.length} skill${updatable.length === 1 ? "" : "s"} would be updated`
+      `${updatable.length} skill${updatable.length === 1 ? "" : "s"} would be updated.`
     );
+    info("Run without --dry-run to apply updates.");
     blank();
     return;
   }
-  blank();
-  const shouldUpdate = await confirm({
-    message: `Update ${updatable.length} skill${updatable.length === 1 ? "" : "s"}?`,
-    default: true
-  });
-  if (!shouldUpdate) {
-    info("Update cancelled.");
-    return;
+  if (!options.yes && isInteractive()) {
+    blank();
+    const shouldUpdate = await confirm({
+      message: `Update ${updatable.length} skill${updatable.length === 1 ? "" : "s"}?`,
+      default: true
+    });
+    if (!shouldUpdate) {
+      info("Update cancelled.");
+      return;
+    }
   }
   const { createInstallCommand: createInstallCommand2 } = await Promise.resolve().then(() => (init_install(), install_exports));
   for (const u of updatable) {
@@ -1559,8 +1839,9 @@ async function runUpdate(skill, options) {
   }
   blank();
   success(
-    `${updatable.length} skill${updatable.length === 1 ? "" : "s"} updated`
+    `${updatable.length} skill${updatable.length === 1 ? "" : "s"} updated.`
   );
+  info("Run `shipables doctor` to verify installations.");
   blank();
 }
 
@@ -1568,8 +1849,7 @@ async function runUpdate(skill, options) {
 import { access as access2, readFile as readFile7, stat as stat3 } from "fs/promises";
 import { join as join6 } from "path";
 import { Command as Command7 } from "commander";
-import chalk7 from "chalk";
-import ora5 from "ora";
+import chalk6 from "chalk";
 import { confirm as confirm2, select } from "@inquirer/prompts";
 
 // src/skill/parser.ts
@@ -1670,15 +1950,30 @@ init_hash();
 init_client();
 init_config();
 init_output();
+init_output();
+init_errors();
 function createPublishCommand() {
   return new Command7("publish").option("--dry-run", "Pack and validate without uploading").option("--tag <tag>", "Dist-tag (e.g., beta, next)", "latest").option(
     "--access <level>",
     "Access level for scoped packages",
     "public"
-  ).description("Publish the skill in the current directory").action(async (options) => {
+  ).option("-y, --yes", "Skip confirmation prompt").option("--scope <scope>", "Publish scope: personal username or @org name (e.g., --scope @myorg)").description(
+    "Pack and publish the skill in the current directory to the registry. Requires SKILL.md and shipables.json. You must be logged in (shipables login). Use --yes and --scope for non-interactive publishing."
+  ).addHelpText("after", `
+Examples:
+  shipables publish                         Interactive publish
+  shipables publish --dry-run               Validate and pack without uploading
+  shipables publish --yes                   Publish without confirmation prompt
+  shipables publish --yes --scope @myorg    Publish under an org, no prompts
+  shipables publish --yes --scope personal  Publish under your personal account
+`).action(async (options) => {
     try {
       await runPublish(options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -1691,15 +1986,17 @@ async function runPublish(options) {
   try {
     await access2(skillMdPath);
   } catch {
-    throw new Error(
-      "No SKILL.md found in the current directory. Run `shipables init` to create one."
+    throw validationError(
+      "No SKILL.md found in the current directory.",
+      "Run `shipables init` to create one, or `shipables init --name <name> --description <desc>` for non-interactive scaffolding."
     );
   }
   try {
     await access2(manifestPath);
   } catch {
-    throw new Error(
-      "No shipables.json found in the current directory. Run `shipables init` to create one."
+    throw validationError(
+      "No shipables.json found in the current directory.",
+      "Run `shipables init` to create one, or `shipables init --name <name> --description <desc>` for non-interactive scaffolding."
     );
   }
   header("Validating:");
@@ -1713,7 +2010,10 @@ async function runPublish(options) {
     for (const err of manifestErrors) {
       error(err);
     }
-    throw new Error("shipables.json validation failed");
+    throw validationError(
+      "shipables.json validation failed.",
+      "Fix the errors listed above in shipables.json, then re-run: shipables publish"
+    );
   }
   success(
     `shipables.json \u2014 version: ${manifest.version}, schema valid`
@@ -1722,16 +2022,17 @@ async function runPublish(options) {
   const version = manifest.version;
   const token = await getToken();
   if (!token && !options.dryRun) {
-    throw new Error(
-      "Not authenticated. Run `shipables login` first."
+    throw authError(
+      "Not authenticated. You must be logged in to publish.",
+      "Run `shipables login` to authenticate, then re-run `shipables publish`."
     );
   }
   let fullName = skillBareName;
   if (!options.dryRun && token) {
-    fullName = await resolvePublishScope(skillBareName);
+    fullName = await resolvePublishScope(skillBareName, options.scope);
   }
   blank();
-  console.log(`  Publishing ${chalk7.bold(`${fullName}@${version}`)}...`);
+  console.log(`  Publishing ${chalk6.bold(`${fullName}@${version}`)}...`);
   let ignorePatterns = [];
   try {
     const ignoreRaw = await readFile7(join6(cwd, ".shipablesignore"), "utf-8");
@@ -1740,7 +2041,7 @@ async function runPublish(options) {
   }
   const tarballName = `${skillBareName}-${version}.tgz`;
   const tarballPath = join6(cwd, tarballName);
-  const packSpinner = ora5("Packing tarball...").start();
+  const packSpinner = spinner("Packing tarball...");
   await createTarball(cwd, tarballPath, ignorePatterns);
   const tarballStat = await stat3(tarballPath);
   const hash = await sha512File(tarballPath);
@@ -1754,34 +2055,39 @@ async function runPublish(options) {
     console.log(`    ${file}`);
   }
   if (files.length > 20) {
-    console.log(chalk7.dim(`    ... and ${files.length - 20} more files`));
+    console.log(chalk6.dim(`    ... and ${files.length - 20} more files`));
   }
   if (options.dryRun) {
     blank();
-    success("Dry run complete \u2014 tarball created but not uploaded");
+    success(`Dry run complete \u2014 ${tarballName} (${formatBytes(tarballStat.size)}) packed but not uploaded.`);
+    info(`Validated: SKILL.md (name: ${skillBareName}), shipables.json (version: ${version})`);
     const { unlink } = await import("fs/promises");
     await unlink(tarballPath);
     blank();
     return;
   }
-  blank();
-  const shouldPublish = await confirm2({
-    message: `Publish ${fullName}@${version} to the shipables registry?`,
-    default: true
-  });
-  if (!shouldPublish) {
-    const { unlink } = await import("fs/promises");
-    await unlink(tarballPath);
-    info("Publish cancelled.");
-    return;
+  if (!options.yes && isInteractive()) {
+    blank();
+    const shouldPublish = await confirm2({
+      message: `Publish ${fullName}@${version} to the shipables registry?`,
+      default: true
+    });
+    if (!shouldPublish) {
+      const { unlink } = await import("fs/promises");
+      await unlink(tarballPath);
+      info("Publish cancelled.");
+      return;
+    }
   }
-  const uploadSpinner = ora5("Publishing...").start();
+  const uploadSpinner = spinner("Publishing...");
   try {
     const result = await registry.publishWithName(fullName, tarballPath);
-    uploadSpinner.succeed(`Published ${chalk7.bold(`${fullName}@${version}`)}`);
+    uploadSpinner.succeed(`Published ${chalk6.bold(`${fullName}@${version}`)}`);
+    blank();
     if (result.url) {
-      info(result.url);
+      info(`View: ${result.url}`);
     }
+    info(`Install with: npx shipables install ${fullName}`);
   } catch (err) {
     uploadSpinner.fail("Publish failed");
     throw err;
@@ -1794,7 +2100,7 @@ async function runPublish(options) {
   }
   blank();
 }
-async function resolvePublishScope(bareName) {
+async function resolvePublishScope(bareName, scopeFlag) {
   let me;
   try {
     me = await registry.getMe();
@@ -1805,6 +2111,17 @@ async function resolvePublishScope(bareName) {
   const publishableOrgs = orgs.filter(
     (o) => o.role === "owner" || o.role === "admin"
   );
+  if (scopeFlag) {
+    if (scopeFlag === "personal" || scopeFlag === me.username) {
+      return `${me.username}/${bareName}`;
+    }
+    const orgName = scopeFlag.replace(/^@/, "");
+    const org = publishableOrgs.find((o) => o.name === orgName);
+    if (org) {
+      return `@${org.name}/${bareName}`;
+    }
+    return `@${orgName}/${bareName}`;
+  }
   if (publishableOrgs.length === 0) {
     return `${me.username}/${bareName}`;
   }
@@ -1821,6 +2138,10 @@ async function resolvePublishScope(bareName) {
   if (choices.length === 1) {
     return choices[0].value;
   }
+  if (!isInteractive()) {
+    info(`Auto-selected publish scope: ${choices[0].value}. Use --scope to specify a different scope.`);
+    return choices[0].value;
+  }
   const selected = await select({
     message: "Publish as:",
     choices
@@ -1859,15 +2180,27 @@ async function listAllFiles(dir, ignorePatterns, prefix = "") {
 init_client();
 init_config();
 init_output();
+init_output();
+init_errors();
 import { Command as Command8 } from "commander";
-import chalk8 from "chalk";
-import ora6 from "ora";
+import chalk7 from "chalk";
 import { confirm as confirm3 } from "@inquirer/prompts";
 function createUnpublishCommand() {
-  return new Command8("unpublish").argument("<skill>", "Skill name with version (e.g., my-skill@1.0.0)").option("-f, --force", "Skip confirmation prompt").description("Yank a published version (within 72 hours of publish)").action(async (skillArg, options) => {
+  return new Command8("unpublish").argument("<skill>", "Skill name with version (e.g., my-skill@1.0.0)").option("-f, --force", "Skip confirmation prompt").description(
+    "Yank a published version from the registry (within 72 hours of publish). Yanked versions cannot be re-published with the same version number. Use --force to skip the confirmation prompt."
+  ).addHelpText("after", `
+Examples:
+  shipables unpublish my-skill@1.0.0          Interactive confirmation
+  shipables unpublish my-skill@1.0.0 --force  Skip confirmation
+  shipables unpublish @org/tool@2.1.0 -f      Unpublish a scoped skill
+`).action(async (skillArg, options) => {
     try {
       await runUnpublish(skillArg, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -1876,21 +2209,25 @@ function createUnpublishCommand() {
 async function runUnpublish(skillArg, options) {
   const token = await getToken();
   if (!token) {
-    throw new Error("Not authenticated. Run `shipables login` first.");
+    throw authError(
+      "Not authenticated. You must be logged in to unpublish.",
+      "Run `shipables login` to authenticate."
+    );
   }
   const { name, version } = parseSkillVersion(skillArg);
   if (!version) {
-    throw new Error(
-      "You must specify a version to unpublish (e.g., my-skill@1.0.0). Unpublishing an entire package is not supported."
+    throw usageError(
+      "You must specify a version to unpublish (e.g., my-skill@1.0.0). Unpublishing an entire package is not supported.",
+      "Use the format: shipables unpublish <skill>@<version>"
     );
   }
   blank();
   warn(
-    `This will yank ${chalk8.bold(`${name}@${version}`)} from the registry.`
+    `This will yank ${chalk7.bold(`${name}@${version}`)} from the registry.`
   );
   warn("Yanked versions cannot be re-published with the same version number.");
   blank();
-  if (!options.force) {
+  if (!options.force && isInteractive()) {
     const shouldProceed = await confirm3({
       message: `Are you sure you want to unpublish ${name}@${version}?`,
       default: false
@@ -1900,12 +2237,12 @@ async function runUnpublish(skillArg, options) {
       return;
     }
   }
-  const spinner = ora6(`Unpublishing ${name}@${version}...`).start();
+  const unpubSpinner = spinner(`Unpublishing ${name}@${version}...`);
   try {
     await registry.unpublishVersion(name, version);
-    spinner.succeed(`Unpublished ${chalk8.bold(`${name}@${version}`)}`);
+    unpubSpinner.succeed(`Unpublished ${chalk7.bold(`${name}@${version}`)}`);
   } catch (err) {
-    spinner.fail("Unpublish failed");
+    unpubSpinner.fail("Unpublish failed");
     throw err;
   }
   blank();
@@ -1931,10 +2268,12 @@ function parseSkillVersion(arg) {
 
 // src/commands/init.ts
 init_output();
+init_errors();
+init_output();
 import { mkdir as mkdir4, writeFile as writeFile5, access as access3 } from "fs/promises";
 import { join as join7 } from "path";
 import { Command as Command9 } from "commander";
-import chalk9 from "chalk";
+import chalk8 from "chalk";
 import { input as input2, confirm as confirm4, checkbox as checkbox2 } from "@inquirer/prompts";
 var CATEGORIES = [
   "databases",
@@ -1954,16 +2293,54 @@ var CATEGORIES = [
   "other"
 ];
 function createInitCommand() {
-  return new Command9("init").description("Scaffold a new skill in the current directory").action(async () => {
+  return new Command9("init").description(
+    "Scaffold a new skill in the current directory. Creates SKILL.md, shipables.json, README.md, and .shipablesignore. Use flags (--name, --description) for non-interactive mode."
+  ).option("--name <name>", "Skill name (lowercase, hyphens, max 64 chars)").option("--description <desc>", "Description of the skill").option("--author <name>", "Author name").option("--author-github <gh>", "Author GitHub username").option("--license <license>", "License identifier (default: MIT)").option("--category <cat...>", "Categories (repeatable)").option("--mcp-package <pkg>", "MCP server npm package name").option("--scripts", "Include example scripts/ directory").option("--no-scripts", "Do not include example scripts/ directory").option("--references", "Include example references/ directory").option("--no-references", "Do not include example references/ directory").option("-y, --yes", "Accept defaults for optional fields").addHelpText(
+    "after",
+    `
+Examples:
+  shipables init                                      Interactive mode
+  shipables init --name my-skill --description "..."  Non-interactive with required fields
+  shipables init --name my-skill --description "..." --mcp-package @org/server --category databases`
+  ).action(async (opts) => {
     try {
-      await runInit();
+      await runInit(opts);
     } catch (err) {
+      if (err instanceof CliError) {
+        error(err.message);
+        if (err.fix) {
+          info(`Fix: ${err.fix}`);
+        }
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
-async function runInit() {
+function validateName(val) {
+  if (!val) return "Name is required";
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(val))
+    return "Must be lowercase letters, numbers, and hyphens only";
+  if (val.length > 64) return "Max 64 characters";
+  return true;
+}
+function validateDescription(val) {
+  if (!val) return "Description is required";
+  if (val.length > 1024) return "Max 1024 characters";
+  return true;
+}
+function validateCategories(cats) {
+  for (const c of cats) {
+    if (!CATEGORIES.includes(c)) {
+      throw usageError(
+        `Invalid category: "${c}"`,
+        `Valid categories: ${CATEGORIES.join(", ")}`
+      );
+    }
+  }
+}
+async function runInit(opts) {
   header("Create a new Shipables skill");
   const cwd = process.cwd();
   try {
@@ -1974,86 +2351,164 @@ async function runInit() {
       throw err;
     }
   }
+  const interactive = isInteractive();
+  const hasRequiredFlags = opts.name !== void 0 && opts.description !== void 0;
+  if (!interactive && !hasRequiredFlags) {
+    throw usageError(
+      "Non-interactive environment detected. --name and --description are required.",
+      "Provide required flags: shipables init --name <name> --description <desc>"
+    );
+  }
+  if (hasRequiredFlags) {
+    const nameResult = validateName(opts.name);
+    if (nameResult !== true) {
+      throw usageError(nameResult);
+    }
+    const descResult = validateDescription(opts.description);
+    if (descResult !== true) {
+      throw usageError(descResult);
+    }
+    const name2 = opts.name;
+    const description2 = opts.description;
+    const authorName2 = opts.author ?? process.env.USER ?? "your-name";
+    const authorGithub2 = opts.authorGithub ?? authorName2;
+    const license2 = opts.license ?? "MIT";
+    const categories2 = opts.category ?? [];
+    if (categories2.length > 0) {
+      validateCategories(categories2);
+    }
+    const includeMcp2 = opts.mcpPackage !== void 0;
+    const mcpPackage2 = opts.mcpPackage ?? "";
+    const includeScripts2 = opts.scripts ?? false;
+    const includeReferences2 = opts.references ?? false;
+    await generateFiles({
+      name: name2,
+      description: description2,
+      authorName: authorName2,
+      authorGithub: authorGithub2,
+      license: license2,
+      categories: categories2,
+      includeMcp: includeMcp2,
+      mcpPackage: mcpPackage2,
+      mcpEnvVars: [],
+      includeScripts: includeScripts2,
+      includeReferences: includeReferences2,
+      skillDir: cwd
+    });
+    return;
+  }
   const name = await input2({
     message: "Skill name (lowercase, hyphens, max 64 chars):",
-    validate: (val) => {
-      if (!val) return "Name is required";
-      if (!/^[a-z0-9][a-z0-9-]*$/.test(val))
-        return "Must be lowercase letters, numbers, and hyphens only";
-      if (val.length > 64) return "Max 64 characters";
-      return true;
-    }
+    default: opts.name,
+    validate: (val) => validateName(val)
   });
   const description = await input2({
     message: "Description (what the skill does and when to use it):",
-    validate: (val) => {
-      if (!val) return "Description is required";
-      if (val.length > 1024) return "Max 1024 characters";
-      return true;
-    }
+    default: opts.description,
+    validate: (val) => validateDescription(val)
   });
-  const authorName = await input2({
+  const authorName = opts.yes ? opts.author ?? process.env.USER ?? "your-name" : await input2({
     message: "Author name:",
-    default: process.env.USER || "your-name"
+    default: opts.author ?? process.env.USER ?? "your-name"
   });
-  const authorGithub = await input2({
+  const authorGithub = opts.yes ? opts.authorGithub ?? authorName : await input2({
     message: "Author GitHub username:",
-    default: authorName
+    default: opts.authorGithub ?? authorName
   });
-  const license = await input2({
+  const license = opts.yes ? opts.license ?? "MIT" : await input2({
     message: "License:",
-    default: "MIT"
+    default: opts.license ?? "MIT"
   });
-  const categories = await checkbox2({
+  const categories = opts.yes ? opts.category ?? [] : opts.category !== void 0 ? opts.category : await checkbox2({
     message: "Categories (select with space):",
     choices: CATEGORIES.map((c) => ({ name: c, value: c }))
   });
-  const includeMcp = await confirm4({
-    message: "Include MCP server configuration?",
-    default: false
-  });
+  if (categories.length > 0) {
+    validateCategories(categories);
+  }
+  let includeMcp;
   let mcpPackage = "";
   let mcpEnvVars = [];
-  if (includeMcp) {
-    mcpPackage = await input2({
-      message: "MCP server npm package name:",
-      validate: (val) => val ? true : "Package name is required"
+  if (opts.mcpPackage !== void 0) {
+    includeMcp = true;
+    mcpPackage = opts.mcpPackage;
+  } else if (opts.yes) {
+    includeMcp = false;
+  } else {
+    includeMcp = await confirm4({
+      message: "Include MCP server configuration?",
+      default: false
     });
-    let addMore = true;
-    while (addMore) {
-      const envName = await input2({
-        message: "Environment variable name (or empty to finish):"
-      });
-      if (!envName) break;
-      const envDesc = await input2({
-        message: `Description for ${envName}:`
-      });
-      const envRequired = await confirm4({
-        message: `Is ${envName} required?`,
-        default: true
-      });
-      const envSecret = await confirm4({
-        message: `Is ${envName} a secret?`,
-        default: false
-      });
-      mcpEnvVars.push({
-        name: envName,
-        description: envDesc,
-        required: envRequired,
-        secret: envSecret
+    if (includeMcp) {
+      mcpPackage = await input2({
+        message: "MCP server npm package name:",
+        validate: (val) => val ? true : "Package name is required"
       });
+      let addMore = true;
+      while (addMore) {
+        const envName = await input2({
+          message: "Environment variable name (or empty to finish):"
+        });
+        if (!envName) break;
+        const envDesc = await input2({
+          message: `Description for ${envName}:`
+        });
+        const envRequired = await confirm4({
+          message: `Is ${envName} required?`,
+          default: true
+        });
+        const envSecret = await confirm4({
+          message: `Is ${envName} a secret?`,
+          default: false
+        });
+        mcpEnvVars.push({
+          name: envName,
+          description: envDesc,
+          required: envRequired,
+          secret: envSecret
+        });
+      }
     }
   }
-  const includeScripts = await confirm4({
+  const includeScripts = opts.scripts !== void 0 ? opts.scripts : opts.yes ? false : await confirm4({
     message: "Include example scripts/ directory?",
     default: false
   });
-  const includeReferences = await confirm4({
+  const includeReferences = opts.references !== void 0 ? opts.references : opts.yes ? false : await confirm4({
     message: "Include example references/ directory?",
     default: false
   });
+  await generateFiles({
+    name,
+    description,
+    authorName,
+    authorGithub,
+    license,
+    categories,
+    includeMcp,
+    mcpPackage,
+    mcpEnvVars,
+    includeScripts,
+    includeReferences,
+    skillDir: cwd
+  });
+}
+async function generateFiles(opts) {
+  const {
+    name,
+    description,
+    authorName,
+    authorGithub,
+    license,
+    categories,
+    includeMcp,
+    mcpPackage,
+    mcpEnvVars,
+    includeScripts,
+    includeReferences,
+    skillDir
+  } = opts;
   header("Creating files:");
-  const skillDir = cwd;
   const skillMd = generateSkillMd(
     name,
     description,
@@ -2118,12 +2573,12 @@ Detailed reference documentation goes here.
     success("references/example.md");
   }
   blank();
-  success(`Skill ${chalk9.bold(name)} initialized!`);
+  success(`Skill ${chalk8.bold(name)} initialized!`);
   blank();
   info("Next steps:");
-  info(`  1. Edit ${chalk9.cyan("SKILL.md")} with your agent instructions`);
-  info(`  2. Edit ${chalk9.cyan("shipables.json")} with your metadata`);
-  info(`  3. Run ${chalk9.cyan("shipables publish")} to publish`);
+  info(`  1. Edit ${chalk8.cyan("SKILL.md")} with your agent instructions`);
+  info(`  2. Edit ${chalk8.cyan("shipables.json")} with your metadata`);
+  info(`  3. Run ${chalk8.cyan("shipables publish")} to publish`);
   blank();
 }
 function generateSkillMd(name, description, license, author, includeReferences, includeMcp, mcpPackage) {
@@ -2214,31 +2669,73 @@ function titleCase(s) {
 // src/commands/login.ts
 init_config();
 init_output();
+init_output();
+init_errors();
 import { createServer } from "http";
 import { Command as Command10 } from "commander";
-import chalk10 from "chalk";
-import ora7 from "ora";
+import chalk9 from "chalk";
 function createLoginCommand() {
-  return new Command10("login").description("Authenticate with the Shipables registry via GitHub").action(async () => {
+  return new Command10("login").description(
+    "Authenticate with the Shipables registry. Uses GitHub OAuth by default. For CI or AI agents, use --token with a pre-generated API token."
+  ).option(
+    "--token <token>",
+    "Authenticate with an API token (for CI/AI agents). Generate at https://shipables.dev/settings/tokens"
+  ).addHelpText(
+    "after",
+    "\nExamples:\n  shipables login                      Interactive GitHub OAuth\n  shipables login --token cbl_xxxxx    Non-interactive token auth (CI/AI agents)\n"
+  ).action(async (options) => {
     try {
-      await runLogin();
+      await runLogin(options);
     } catch (err) {
+      if (err instanceof CliError) {
+        error(err.message);
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
 function createLogoutCommand() {
-  return new Command10("logout").description("Remove stored credentials").action(async () => {
+  return new Command10("logout").description("Remove stored credentials from ~/.shipables/config.json").action(async () => {
     try {
       await runLogout();
     } catch (err) {
+      if (err instanceof CliError) {
+        error(err.message);
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
-async function runLogin() {
+async function runLogin(options) {
+  if (options.token) {
+    const registryUrl2 = await getRegistry();
+    const config = await loadConfig();
+    config.token = options.token;
+    try {
+      const resp = await fetch(`${registryUrl2}/api/v1/auth/me`, {
+        headers: {
+          Authorization: `Bearer ${options.token}`,
+          "User-Agent": "shipables-cli"
+        }
+      });
+      if (resp.ok) {
+        const me = await resp.json();
+        config.username = me.username;
+      }
+    } catch {
+    }
+    await saveConfig(config);
+    blank();
+    success(`Logged in as ${chalk9.bold(config.username || "unknown")}`);
+    info(chalk9.dim("Token stored in ~/.shipables/config.json"));
+    info("You can now publish skills with: shipables publish");
+    blank();
+    return;
+  }
   const registryUrl = await getRegistry();
   const { port, tokenPromise, server } = await startCallbackServer();
   const callbackUrl = `http://localhost:${port}/callback`;
@@ -2246,13 +2743,13 @@ async function runLogin() {
   blank();
   info("Open this URL in your browser to sign in with GitHub:");
   blank();
-  info(chalk10.cyan(loginUrl));
+  info(chalk9.cyan(loginUrl));
   blank();
   await tryOpenBrowser(loginUrl);
-  const spinner = ora7("Waiting for authentication...").start();
+  const spin = spinner("Waiting for authentication...");
   try {
     const token = await tokenPromise;
-    spinner.stop();
+    spin.stop();
     const config = await loadConfig();
     config.token = token;
     try {
@@ -2271,14 +2768,14 @@ async function runLogin() {
     await saveConfig(config);
     blank();
     success(
-      `Logged in as ${chalk10.bold(config.username || "unknown")}`
+      `Logged in as ${chalk9.bold(config.username || "unknown")}`
     );
     info(
-      chalk10.dim("Token stored in ~/.shipables/config.json")
+      chalk9.dim("Token stored in ~/.shipables/config.json")
     );
     blank();
   } catch (err) {
-    spinner.fail("Authentication failed");
+    spin.fail("Authentication failed");
     throw err;
   } finally {
     server.close();
@@ -2360,13 +2857,26 @@ init_config();
 init_adapters();
 init_client();
 init_output();
+init_output();
+init_errors();
 import { Command as Command11 } from "commander";
-import chalk11 from "chalk";
+import chalk10 from "chalk";
 function createDoctorCommand() {
-  return new Command11("doctor").description("Check health of installed skills and agent configurations").option("-g, --global", "Check globally installed skills").action(async (options) => {
+  return new Command11("doctor").description(
+    "Check health of installed skills and agent configurations. Validates skill directories exist, MCP configs are present, and checks for updates."
+  ).option("-g, --global", "Check globally installed skills").option("--json", "Output results as JSON").addHelpText("after", `
+Examples:
+  shipables doctor            Check all skills in current project
+  shipables doctor --global   Check globally installed skills
+  shipables doctor --json     Get results as JSON
+`).action(async (options) => {
     try {
       await runDoctor(options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -2377,19 +2887,26 @@ async function runDoctor(options) {
   const installations = await getProjectInstallations(projectPath);
   const entries = Object.entries(installations);
   if (entries.length === 0) {
+    if (options.json || getJsonMode()) {
+      console.log(JSON.stringify({ ok: true, skills: [], issues: 0, updates: 0 }, null, 2));
+      return;
+    }
     blank();
     info("No skills installed to check.");
+    info("Install a skill with: shipables install <skill>");
     blank();
     return;
   }
   header("Checking installed skills...");
   let totalIssues = 0;
   let totalUpdates = 0;
+  const jsonResults = [];
   for (const [skillName, record] of entries) {
     const agentList = record.agents.join(", ");
     console.log(
-      `  ${chalk11.bold(`${skillName}@${record.version}`)} (${agentList}):`
+      `  ${chalk10.bold(`${skillName}@${record.version}`)} (${agentList}):`
     );
+    const skillChecks = [];
     for (const agentName of record.agents) {
       const adapter = getAdapter(agentName);
       if (!adapter) continue;
@@ -2398,6 +2915,7 @@ async function runDoctor(options) {
       if (skillDir) {
         const result = await adapter.validate(skillName, skillDir, mcpConfig);
         for (const check of result.checks) {
+          skillChecks.push({ agent: agentName, ...check });
           if (check.status === "pass") {
             success(check.label);
           } else if (check.status === "fail") {
@@ -2409,9 +2927,11 @@ async function runDoctor(options) {
         }
       }
     }
+    let updateAvailable = null;
     try {
       const detail = await registry.getSkillDetail(skillName);
       if (detail.latest_version !== record.version) {
+        updateAvailable = detail.latest_version;
         warn(
           `Update available: ${record.version} \u2192 ${detail.latest_version}`
         );
@@ -2419,10 +2939,21 @@ async function runDoctor(options) {
       }
     } catch {
     }
+    jsonResults.push({
+      name: skillName,
+      version: record.version,
+      agents: record.agents,
+      checks: skillChecks,
+      update_available: updateAvailable
+    });
     blank();
   }
+  if (options.json || getJsonMode()) {
+    console.log(JSON.stringify({ ok: totalIssues === 0, skills: jsonResults, issues: totalIssues, updates: totalUpdates }, null, 2));
+    return;
+  }
   if (totalIssues === 0 && totalUpdates === 0) {
-    success("All checks passed");
+    success("All checks passed.");
   } else {
     const parts = [];
     if (totalIssues > 0) {
@@ -2434,6 +2965,12 @@ async function runDoctor(options) {
       );
     }
     info(`Summary: ${parts.join(", ")}`);
+    if (totalIssues > 0) {
+      info("Fix issues by re-installing: shipables install <skill> --<agent>");
+    }
+    if (totalUpdates > 0) {
+      info("Apply updates with: shipables update");
+    }
   }
   blank();
 }
@@ -2441,15 +2978,29 @@ async function runDoctor(options) {
 // src/commands/config.ts
 init_config();
 init_output();
+init_errors();
 import { Command as Command12 } from "commander";
-import chalk12 from "chalk";
+import chalk11 from "chalk";
 var VALID_KEYS = ["registry", "defaultAgents", "scope"];
 function createConfigCommand() {
-  const cmd = new Command12("config").description("Manage CLI configuration");
-  cmd.command("set <key> <value>").description("Set a config value").action(async (key, value) => {
+  const cmd = new Command12("config").description(
+    "Manage CLI configuration. Config is stored in ~/.shipables/config.json. Valid keys: registry, defaultAgents, scope."
+  ).addHelpText("after", `
+Examples:
+  shipables config list                          Show all config values
+  shipables config get registry                  Get the registry URL
+  shipables config set registry https://...      Set a custom registry URL
+  shipables config set defaultAgents claude,cursor  Set default agents
+  shipables config delete scope                  Remove a config value
+`);
+  cmd.command("set <key> <value>").description("Set a config value (valid keys: registry, defaultAgents, scope)").action(async (key, value) => {
     try {
       await runConfigSet(key, value);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -2458,11 +3009,15 @@ function createConfigCommand() {
     try {
       await runConfigGet(key);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
-  cmd.command("list").description("Show all config").action(async () => {
+  cmd.command("list").description("Show all config values").action(async () => {
     try {
       await runConfigList();
     } catch (err) {
@@ -2474,6 +3029,10 @@ function createConfigCommand() {
     try {
       await runConfigDelete(key);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -2482,8 +3041,9 @@ function createConfigCommand() {
 }
 function validateKey(key) {
   if (!VALID_KEYS.includes(key)) {
-    throw new Error(
-      `Invalid config key: ${key}. Valid keys: ${VALID_KEYS.join(", ")}`
+    throw usageError(
+      `Invalid config key: '${key}'.`,
+      `Valid keys: ${VALID_KEYS.join(", ")}. Example: shipables config set registry https://api.shipables.dev`
     );
   }
   return key;
@@ -2516,15 +3076,15 @@ async function runConfigList() {
   blank();
   for (const key of VALID_KEYS) {
     const value = config[key];
-    const display = value === void 0 ? chalk12.dim("(not set)") : typeof value === "object" ? JSON.stringify(value) : String(value);
-    console.log(`  ${chalk12.bold(key)}: ${display}`);
+    const display = value === void 0 ? chalk11.dim("(not set)") : typeof value === "object" ? JSON.stringify(value) : String(value);
+    console.log(`  ${chalk11.bold(key)}: ${display}`);
   }
   if (config.username) {
     console.log(
-      `  ${chalk12.bold("auth")}: logged in as ${chalk12.green(config.username)}`
+      `  ${chalk11.bold("auth")}: logged in as ${chalk11.green(config.username)}`
     );
   } else {
-    console.log(`  ${chalk12.bold("auth")}: ${chalk12.dim("not logged in")}`);
+    console.log(`  ${chalk11.bold("auth")}: ${chalk11.dim("not logged in")}`);
   }
   blank();
 }
@@ -2539,30 +3099,42 @@ async function runConfigDelete(key) {
 // src/commands/stats.ts
 init_client();
 init_output();
+init_output();
+init_errors();
 import { Command as Command13 } from "commander";
-import chalk13 from "chalk";
-import ora8 from "ora";
+import chalk12 from "chalk";
 function createStatsCommand() {
-  return new Command13("stats").argument("<skill>", "Skill name").option("--period <period>", "Time period: week, month, year", "month").option("--json", "Output as JSON").description("Show download statistics for a skill").action(async (skillName, options) => {
+  return new Command13("stats").argument("<skill>", "Skill name (e.g., Chippers255/ai-commits, @org/my-skill)").option("--period <period>", "Time period: week, month, year", "month").option("--json", "Output as JSON").description(
+    "Show download statistics for a skill with a daily breakdown chart."
+  ).addHelpText("after", `
+Examples:
+  shipables stats Chippers255/ai-commits                Show monthly download stats
+  shipables stats Chippers255/ai-commits --period week  Show weekly stats
+  shipables stats @org/tool --json     Get stats as JSON
+`).action(async (skillName, options) => {
     try {
       await runStats(skillName, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
   });
 }
 async function runStats(skillName, options) {
-  const spinner = ora8(`Fetching download stats for ${skillName}...`).start();
+  const statsSpinner = spinner(`Fetching download stats for ${skillName}...`);
   const stats = await registry.getDownloadStats(skillName, options.period);
-  spinner.stop();
-  if (options.json) {
+  statsSpinner.stop();
+  if (options.json || getJsonMode()) {
     console.log(JSON.stringify(stats, null, 2));
     return;
   }
   blank();
   console.log(
-    `  ${chalk13.bold(stats.skill)} \u2014 ${stats.period} downloads: ${chalk13.bold(formatNumber(stats.total))}`
+    `  ${chalk12.bold(stats.skill)} \u2014 ${stats.period} downloads: ${chalk12.bold(formatNumber(stats.total))}`
   );
   blank();
   if (stats.daily.length > 0) {
@@ -2572,7 +3144,7 @@ async function runStats(skillName, options) {
       const bar = "\u2588".repeat(Math.round(day.count / maxCount * barWidth));
       const date = day.date.slice(5);
       const count = String(day.count).padStart(6);
-      console.log(`  ${chalk13.dim(date)}  ${count}  ${chalk13.cyan(bar)}`);
+      console.log(`  ${chalk12.dim(date)}  ${count}  ${chalk12.cyan(bar)}`);
     }
   }
   blank();
@@ -2582,14 +3154,26 @@ async function runStats(skillName, options) {
 init_client();
 init_config();
 init_output();
+init_output();
+init_errors();
 import { Command as Command14 } from "commander";
-import chalk14 from "chalk";
-import ora9 from "ora";
+import chalk13 from "chalk";
 function createProfileCommand() {
-  return new Command14("profile").argument("[username]", "Username to look up (defaults to current user)").option("--json", "Output as JSON").description("Show user profile and published skills").action(async (username, options) => {
+  return new Command14("profile").argument("[username]", "Username to look up (defaults to current user)").option("--json", "Output as JSON").description(
+    "Show user profile and published skills. Defaults to the currently logged-in user if no username is provided."
+  ).addHelpText("after", `
+Examples:
+  shipables profile              Show your profile
+  shipables profile johndoe      Show another user's profile
+  shipables profile --json       Get your profile as JSON
+`).action(async (username, options) => {
     try {
       await runProfile(username, options);
     } catch (err) {
+      if (err instanceof CliError) {
+        errorWithFix(err.message, err.fix || "");
+        process.exit(err.exitCode);
+      }
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
@@ -2603,29 +3187,30 @@ async function runProfile(username, options) {
     } else {
       const token = await getToken();
       if (!token) {
-        throw new Error(
-          "No username provided and not logged in. Run `shipables login` or provide a username."
+        throw authError(
+          "No username provided and not logged in.",
+          "Run `shipables login` first, or provide a username: shipables profile <username>"
         );
       }
       const me = await registry.getMe();
       username = me.username;
     }
   }
-  const spinner = ora9(`Fetching profile for ${username}...`).start();
+  const profileSpinner = spinner(`Fetching profile for ${username}...`);
   const [profile, skillsResult] = await Promise.all([
     registry.getUserProfile(username),
     registry.getUserSkills(username)
   ]);
-  spinner.stop();
-  if (options.json) {
+  profileSpinner.stop();
+  if (options.json || getJsonMode()) {
     console.log(JSON.stringify({ profile, skills: skillsResult.skills }, null, 2));
     return;
   }
   blank();
   const displayName = profile.display_name || profile.username;
-  console.log(`  ${chalk14.bold(displayName)}`);
+  console.log(`  ${chalk13.bold(displayName)}`);
   if (profile.display_name && profile.display_name !== profile.username) {
-    console.log(`  ${chalk14.dim(`@${profile.username}`)}`);
+    console.log(`  ${chalk13.dim(`@${profile.username}`)}`);
   }
   blank();
   info(`Skills published: ${profile.skills_count}`);
@@ -2651,8 +3236,32 @@ function truncate2(s, max) {
 }
 
 // src/index.ts
+init_output();
 var program = new Command15();
-program.name("shipables").description("CLI for installing, managing, and publishing AI agent skills").version("0.1.0");
+program.name("shipables").description(
+  "CLI for installing, managing, and publishing AI agent skills. Works with Claude Code, Cursor, Codex, Copilot, Gemini, and Cline. Skills follow the Agent Skills open standard (https://agentskills.io)."
+).version("0.1.0").option("--json", "Output structured JSON (supported by most commands)").on("option:json", () => {
+  setJsonMode(true);
+}).addHelpText("after", `
+Examples:
+  shipables search "database"                Search for database-related skills
+  shipables install Chippers255/ai-commits --claude  Install a skill for Claude Code
+  shipables install @org/tool --all                  Install a scoped skill for all agents
+  shipables list                             List skills installed in current project
+  shipables info Chippers255/ai-commits --json  Get skill details as JSON
+  shipables init --name my-skill --description "A skill for X"
+                                             Scaffold a new skill (non-interactive)
+  shipables publish --yes --scope @myorg     Publish without prompts
+  shipables login --token cbl_xxxxx          Non-interactive auth for CI/AI agents
+
+Non-interactive usage (CI/AI agents):
+  Most commands work non-interactively. Use flags instead of prompts:
+  - install: --claude/--cursor/--all for agents, --env KEY=VAL for MCP vars
+  - init: --name and --description skip all prompts
+  - publish: --yes skips confirmation, --scope sets org
+  - login: --token skips browser OAuth
+  - All commands: --json for structured output
+`);
 program.addCommand(createInstallCommand());
 program.addCommand(createUninstallCommand());
 program.addCommand(createSearchCommand());