ht-skills 0.2.12 → 0.2.14

package/README.md

@@ -12,9 +12,9 @@ npx ht-skills add --skill repo-bug-analyze
 
 ```text
 ht-skills login [--registry <url>]
-ht-skills publish [skillDir] [--registry <url>] [--access public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+ht-skills publish [skillDir] [--registry <url>] [--path-slug <path>] [--skip-user-dir] [--access public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
 ht-skills search <query> [--registry <url>] [--limit <n>]
-ht-skills submit <skillDir> [--registry <url>] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+ht-skills submit <skillDir> [--registry <url>] [--path-slug <path>] [--skip-user-dir] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
 ht-skills install <slug[@version]> [more-skills...] [--registry <url>] [--target <dir>] [--tool codex|claude|vscode]
 ht-skills add [registry] --skill <slug[@version]>,<slug[@version]> [--tool codex|claude|vscode]
 ```
@@ -22,3 +22,7 @@ ht-skills add [registry] --skill <slug[@version]>,<slug[@version]> [--tool codex
 `login` prints a dedicated `/cli-login` URL, waits for Enter, opens the browser, and stores the approved registry token under `~/.ht-skills/config.json`.
 
 `publish` zips the target skill directory, uploads it through the marketplace package inspection flow, and then submits the generated preview token for review. The default access is `public`; use `--access private` to keep the skill private before review.
+
+`--path-slug` lets you publish under a nested registry path (for example `gcs/abc`) while keeping the skill manifest slug (for example `abc`) unchanged for local install naming.
+
+`--skip-user-dir` requests publishing to the top-level path (without the default username prefix). The server only accepts this for admin users.

package/lib/cli.js

@@ -50,8 +50,8 @@ function printHelp() {
   console.log(`Usage:
   ht-skills search <query> [--registry <url>] [--limit <n>]
   ht-skills login [--registry <url>]
-  ht-skills publish [skillDir] [--registry <url>] [--access public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
-  ht-skills submit <skillDir> [--registry <url>] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+  ht-skills publish [skillDir] [--registry <url>] [--path-slug <path>] [--skip-user-dir] [--access public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+  ht-skills submit <skillDir> [--registry <url>] [--path-slug <path>] [--skip-user-dir] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
   ht-skills install <slug[@version]> [more-skills...] [--registry <url>] [--target <dir>] [--tool codex|claude|vscode]
   ht-skills add [registry] --skill <slug[@version]>,<slug[@version]> [--tool codex|claude|vscode]
 
@@ -59,6 +59,8 @@ Examples:
   ht-skills search openai
   ht-skills login
   ht-skills publish .
+  ht-skills publish . --path-slug gcs/abc
+  ht-skills publish . --skip-user-dir
   ht-skills publish . --access private
   ht-skills submit ./examples/hello-skill
   ht-skills install hello-skill@1.0.0 --tool codex
@@ -98,6 +100,14 @@ function getRegistryUrl(flags) {
   return String(flags.registry || process.env.SKILLS_REGISTRY_URL || DEFAULT_REGISTRY_URL).replace(/\/$/, "");
 }
 
+function isBooleanFlagEnabled(value) {
+  if (value === true) return true;
+  if (value === false || value == null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return false;
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
 async function requestJson(url, options = {}) {
   const res = await fetch(url, options);
   const text = await res.text();
@@ -441,6 +451,15 @@ function parseSpec(spec) {
   return { slug, version: version || null };
 }
 
+function encodeSkillPathForUrl(pathValue) {
+  return String(pathValue || "")
+    .split("/")
+    .map((segment) => segment.trim())
+    .filter(Boolean)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
 function normalizeSkillSpecs(rawSpecs, { source = "install" } = {}) {
   const values = Array.isArray(rawSpecs) ? rawSpecs : [rawSpecs];
   const result = [];
@@ -952,7 +971,14 @@ function printFallbackSearchIntro({ registry, query, limit }, log = console.log)
   log("");
 }
 
-function printFallbackPublishIntro({ registry, skillDir, archiveName, visibility }, log = console.log) {
+function printFallbackPublishIntro({
+  registry,
+  skillDir,
+  archiveName,
+  visibility,
+  pathSlug = null,
+  skipUserDir = false,
+}, log = console.log) {
   log("");
   log(renderGradientBanner());
   log("");
@@ -962,6 +988,12 @@ function printFallbackPublishIntro({ registry, skillDir, archiveName, visibility
   log(`Directory: ${skillDir}`);
   log(`Archive: ${archiveName}`);
   log(`Access: ${visibility}`);
+  if (pathSlug) {
+    log(`Path Slug: ${pathSlug}`);
+  }
+  if (skipUserDir) {
+    log("Skip User Dir: true");
+  }
   log("");
 }
 
@@ -1218,12 +1250,12 @@ async function resolveInteractiveToolIds(flags, deps, specs) {
   }
 
   const skillLabel = specs.length === 1
-    ? `${metadata?.manifest?.name || primarySpec.slug} (${primarySpec.slug}@${version})`
+    ? `${metadata?.manifest?.name || primarySpec.slug} (${(metadata?.manifest?.slug || primarySpec.slug)}@${version})`
     : `${specs.length} skills`;
   const skillDescription = specs.length === 1
     ? (metadata?.manifest?.description || "")
     : specs.join(", ");
-  const targetSlug = specs.length === 1 ? primarySpec.slug : "<skill-slug>";
+  const targetSlug = specs.length === 1 ? (metadata?.manifest?.slug || primarySpec.slug) : "<skill-slug>";
   const availableTargets = getAvailableInstallTargets(targetSlug, { homeDir });
 
   if (availableTargets.length > 0 && ui) {
@@ -1238,9 +1270,9 @@ async function resolveInteractiveToolIds(flags, deps, specs) {
   } else if (availableTargets.length > 0) {
     printFallbackIntro({
       registry,
-      slug: specs.length === 1 ? primarySpec.slug : `${specs.length} skills`,
+      slug: specs.length === 1 ? (metadata?.manifest?.slug || primarySpec.slug) : `${specs.length} skills`,
       version: specs.length === 1 ? version : "mixed",
-      skillName: specs.length === 1 ? (metadata?.manifest?.name || primarySpec.slug) : `${specs.length} skills`,
+      skillName: specs.length === 1 ? (metadata?.manifest?.name || metadata?.manifest?.slug || primarySpec.slug) : `${specs.length} skills`,
       skillDescription,
       installTargets: availableTargets,
     }, log);
@@ -1313,7 +1345,6 @@ async function installOne(flags, deps = {}) {
   }
 
   let toolIds = selectedToolIds.length > 0 ? selectedToolIds : normalizeToolIds(flags.tool);
-  const renderInstallLine = deps.renderInstallLine || ((target) => `installed ${parsed.slug}@${version} -> ${target.target}`);
   let metadata = null;
 
   try {
@@ -1333,15 +1364,17 @@ async function installOne(flags, deps = {}) {
   }
 
   const skillName = metadata?.manifest?.name || parsed.slug;
+  const installSlug = metadata?.manifest?.slug || parsed.slug;
   const skillDescription = metadata?.manifest?.description || "";
+  const renderInstallLine = deps.renderInstallLine || ((target) => `installed ${installSlug}@${version} -> ${target.target}`);
 
   if (toolIds.length === 0 && !flags.target && isInteractive) {
-    const availableTargets = getAvailableInstallTargets(parsed.slug, { homeDir });
+    const availableTargets = getAvailableInstallTargets(installSlug, { homeDir });
     if (availableTargets.length > 0 && ui) {
       ui.note(
         [
           `${colorize("Source", "muted")}: ${registry}`,
-          `${colorize("Skill", "muted")}: ${colorize(skillName, "accent")} ${colorize(`(${parsed.slug}@${version})`, "muted")}`,
+          `${colorize("Skill", "muted")}: ${colorize(skillName, "accent")} ${colorize(`(${installSlug}@${version})`, "muted")}`,
           skillDescription ? `${colorize("Summary", "muted")}: ${skillDescription}` : "",
         ].filter(Boolean).join("\n"),
         "Install plan",
@@ -1349,7 +1382,7 @@ async function installOne(flags, deps = {}) {
     } else if (availableTargets.length > 0) {
       printFallbackIntro({
         registry,
-        slug: parsed.slug,
+        slug: installSlug,
         version,
         skillName,
         skillDescription,
@@ -1379,7 +1412,7 @@ async function installOne(flags, deps = {}) {
   const installTargets = resolveInstallTargets({
     toolIds,
     target: flags.target,
-    slug: parsed.slug,
+    slug: installSlug,
     version,
     homeDir,
   });
@@ -1387,7 +1420,7 @@ async function installOne(flags, deps = {}) {
   if (!ui) {
     printFallbackIntro({
       registry,
-      slug: parsed.slug,
+      slug: installSlug,
       version,
       skillName,
       skillDescription,
@@ -1428,7 +1461,8 @@ async function installOne(flags, deps = {}) {
       metadataPath,
       `${JSON.stringify(
         {
-          slug: parsed.slug,
+          slug: installSlug,
+          requestedSlug: parsed.slug,
           version,
           installedAt: new Date().toISOString(),
           registry,
@@ -1453,9 +1487,9 @@ async function installOne(flags, deps = {}) {
   if (installTargets.length > 0) {
     if (ui) {
       ui.note(formatTargetsNote(installTargets, colorize), "Installed to");
-      ui.outro(`Installed ${ui.pc.cyan(parsed.slug)} to ${installTargets.length} target${installTargets.length === 1 ? "" : "s"}.`);
+      ui.outro(`Installed ${ui.pc.cyan(installSlug)} to ${installTargets.length} target${installTargets.length === 1 ? "" : "s"}.`);
     } else {
-      log(`Installed ${parsed.slug} to ${formatCount(installTargets.length, "target")}`);
+      log(`Installed ${installSlug} to ${formatCount(installTargets.length, "target")}`);
     }
   }
 
@@ -1557,6 +1591,11 @@ async function cmdPublish(flags, deps = {}) {
   const log = deps.log || ((message) => console.log(message));
   const registry = getRegistryUrl(flags);
   const skillDir = path.resolve(flags._[0] || ".");
+  const pathSlug = String(flags["path-slug"] || "").trim() || null;
+  const skipUserDir = isBooleanFlagEnabled(flags["skip-user-dir"]);
+  if (pathSlug && skipUserDir) {
+    throw new Error("--path-slug and --skip-user-dir cannot be used together");
+  }
   const visibility = String(flags.access || flags.visibility || "public").trim().toLowerCase() || "public";
   const archiveName = `${path.basename(skillDir) || "skill"}.zip`;
   const isInteractive = isInteractiveSession(deps);
@@ -1610,12 +1649,14 @@ async function cmdPublish(flags, deps = {}) {
         `${colorize("Directory", "muted")}: ${skillDir}`,
         `${colorize("Archive", "muted")}: ${archiveName}`,
         `${colorize("Access", "muted")}: ${visibility}`,
+        pathSlug ? `${colorize("Path Slug", "muted")}: ${pathSlug}` : "",
+        skipUserDir ? `${colorize("Skip User Dir", "muted")}: true` : "",
       ].join("\n"),
       "Publish",
     );
     renderPublishFlow();
   } else {
-    printFallbackPublishIntro({ registry, skillDir, archiveName, visibility }, log);
+    printFallbackPublishIntro({ registry, skillDir, archiveName, visibility, pathSlug, skipUserDir }, log);
   }
 
   setFlowMessage(`Checking login for ${registry}`);
@@ -1761,6 +1802,12 @@ async function cmdPublish(flags, deps = {}) {
     preview_token: preview.preview_token,
     visibility,
   };
+  if (pathSlug) {
+    body.path_slug = pathSlug;
+  }
+  if (skipUserDir) {
+    body.skip_user_dir = true;
+  }
   if (flags["shared-with"]) {
     body.shared_with = String(flags["shared-with"])
       .split(",")
@@ -1805,16 +1852,19 @@ async function cmdPublish(flags, deps = {}) {
     preview_token: preview.preview_token,
     archive_name: archiveName,
   };
-  const skillSlug = String(
-    result.publication?.slug
+  const skillPath = String(
+    result.publication?.pathSlug
+    || result.publication?.slug
     || result.publication?.manifest?.slug
     || preview.manifest?.slug
     || "",
   ).trim();
-  const skillUrl = skillSlug ? `${registry}/skills/${encodeURIComponent(skillSlug)}` : null;
+  const encodedSkillPath = encodeSkillPathForUrl(skillPath);
+  const skillUrl = encodedSkillPath ? `${registry}/skills/${encodedSkillPath}` : null;
   summaryPayload.skill_url = skillUrl;
 
   if (ui) {
+    flowRenderer?.clear();
     ui.note(
       [
         `${colorize("Status", "muted")}: ${result.status || "pending"}`,
@@ -1825,7 +1875,6 @@ async function cmdPublish(flags, deps = {}) {
       ].join("\n"),
       "Published",
     );
-    setFlowMessage(`Submitted ${archiveName} for review`);
     ui.outro(skillUrl
       ? `Submitted ${ui.pc.cyan(archiveName)} for review. Skill URL: ${skillUrl}`
       : `Submitted ${ui.pc.cyan(archiveName)} for review.`);
@@ -1865,6 +1914,17 @@ async function cmdSubmit(flags, deps = {}) {
     files,
     submitter: String(flags.submitter || process.env.USERNAME || os.userInfo().username || "anonymous"),
   };
+  const pathSlug = String(flags["path-slug"] || "").trim();
+  const skipUserDir = isBooleanFlagEnabled(flags["skip-user-dir"]);
+  if (pathSlug && skipUserDir) {
+    throw new Error("--path-slug and --skip-user-dir cannot be used together");
+  }
+  if (pathSlug) {
+    body.path_slug = pathSlug;
+  }
+  if (skipUserDir) {
+    body.skip_user_dir = true;
+  }
 
   if (flags.visibility) {
     body.visibility = String(flags.visibility);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ht-skills",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "CLI for installing and submitting skills from HT Skills Marketplace.",
   "type": "commonjs",
   "bin": {