askill-cli 0.1.3 → 0.1.4

package/README.md

@@ -12,6 +12,9 @@ You are an AI agent helping a user with askill - a package manager for AI agent
 
 **Quick Commands:**
 ```bash
+# Install a published skill (@author/skill-name)
+askill add @johndoe/awesome-tool -y
+
 # Install a skill
 askill add owner/repo@skill-name -y
 
@@ -65,6 +68,9 @@ Every skill on [askill.sh](https://askill.sh) is automatically reviewed by AI ac
 # Install
 curl -fsSL https://askill.sh | sh
 
+# Install a published skill
+askill add @johndoe/awesome-tool
+
 # Install a skill
 askill add owner/repo@skill-name
 

package/dist/cli.mjs

@@ -4,7 +4,7 @@
 import { homedir } from "os";
 import { join } from "path";
 import { existsSync } from "fs";
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 var API_BASE_URL = "https://askill.sh/api/v1";
 var REGISTRY_URL = "https://askill.sh";
 var RESET = "\x1B[0m";
@@ -788,28 +788,29 @@ async function fetchVersionInfo() {
     return null;
   }
 }
-async function checkForUpdates(force = false) {
+async function getAvailableUpdate(force = false) {
   if (!force && !await shouldCheckUpdate()) {
-    return;
+    return null;
   }
   await saveUpdateCheckTime();
   const versionInfo = await fetchVersionInfo();
-  if (!versionInfo) return;
+  if (!versionInfo) return null;
   const current = VERSION;
-  const latest = versionInfo.latest;
-  if (semver.lt(current, latest)) {
-    console.log();
-    console.log(`${YELLOW}\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E${RESET}`);
-    console.log(`${YELLOW}\u2502${RESET}  Update available: ${DIM}${current}${RESET} \u2192 ${GREEN}${latest}${RESET}        ${YELLOW}\u2502${RESET}`);
-    console.log(`${YELLOW}\u2502${RESET}  Run ${CYAN}askill upgrade${RESET} to update             ${YELLOW}\u2502${RESET}`);
-    console.log(`${YELLOW}\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F${RESET}`);
-    console.log();
-  }
   if (semver.lt(current, versionInfo.minimum)) {
     console.log(`${RED}Your askill version is too old. Please update to continue.${RESET}`);
     console.log(`Minimum required: ${versionInfo.minimum}`);
     process.exit(1);
   }
+  if (!semver.lt(current, versionInfo.latest)) {
+    return null;
+  }
+  return {
+    current,
+    latest: versionInfo.latest,
+    minimum: versionInfo.minimum,
+    releaseNotes: versionInfo.releaseNotes,
+    releaseUrl: versionInfo.releaseUrl
+  };
 }
 async function selfUpdate() {
   console.log(`${CYAN}Checking for updates...${RESET}`);
@@ -1552,6 +1553,7 @@ ${BOLD}Commands:${RESET}
   upgrade                  Update askill CLI to latest version
 
 ${BOLD}Skill Source Formats:${RESET}
+  @author/skill-name                    Published skill from askill registry
   owner/repo                          All skills from a GitHub repo
   owner/repo@skill-name               Specific skill by name
   owner/repo/path/to/skill            Specific skill by path
@@ -1560,6 +1562,7 @@ ${BOLD}Skill Source Formats:${RESET}
   gh:owner/repo@skill-name            Explicit GitHub prefix (optional)
 
 ${BOLD}Install Options:${RESET}
+  (default)             Install to current project: .agents/skills/
   -g, --global          Install globally (user-level)
   -a, --agent <agents>  Install to specific agents
   -y, --yes             Skip confirmation prompts
@@ -1570,21 +1573,297 @@ ${BOLD}Install Options:${RESET}
 ${BOLD}Run Options:${RESET}
   askill run <skill>:<command>      Run a skill's command
 
+${BOLD}Search Options:${RESET}
+  --full-desc             Show full skill descriptions in find/search
+
 ${BOLD}Options:${RESET}
   --help, -h            Show this help message
   --version, -v         Show version number
 
+${BOLD}Per-command Help:${RESET}
+  askill <command> --help
+  askill help <command>
+
+${BOLD}For Agents:${RESET}
+  Official usage guide: ${CYAN}https://github.com/avibe-bot/askill/tree/main/skills/use-askill${RESET}
+
 ${BOLD}Examples:${RESET}
   ${DIM}$${RESET} askill add anthropic/courses@prompt-eng
   ${DIM}$${RESET} askill add anthropic/courses
   ${DIM}$${RESET} askill add ./my-skills/custom-skill
   ${DIM}$${RESET} askill find memory
+  ${DIM}$${RESET} askill find memory --full-desc
   ${DIM}$${RESET} askill list -g
   ${DIM}$${RESET} askill info gh:anthropic/courses@prompt-eng
 
 ${DIM}Browse more at${RESET} ${CYAN}https://askill.sh${RESET}
 `);
 }
+function createSpinner(plain) {
+  if (!plain) {
+    return p.spinner();
+  }
+  return {
+    start: () => {
+    },
+    stop: () => {
+    },
+    message: () => {
+    }
+  };
+}
+function normalizeCommand(command) {
+  switch (command) {
+    case "install":
+    case "i":
+      return "add";
+    case "search":
+    case "s":
+      return "find";
+    case "ls":
+      return "list";
+    case "rm":
+    case "uninstall":
+      return "remove";
+    case "show":
+      return "info";
+    default:
+      return command;
+  }
+}
+function showCommandHelp(commandInput) {
+  const command = normalizeCommand(commandInput);
+  const helps = {
+    add: `${BOLD}askill add${RESET}
+
+Usage:
+  askill add <source> [options]
+
+Description:
+  Install skills from published slugs, GitHub, or local directories.
+
+Sources:
+  @author/skill-name
+  gh:owner/repo@skill-name
+  gh:owner/repo/path/to/skill
+  owner/repo
+  ./local/path
+
+Scope:
+  default: current project (.agents/skills/)
+  -g, --global: user-level install
+
+Options:
+  -g, --global            Install globally
+  -a, --agent <agents...> Install to specific agents
+  -y, --yes               Skip confirmation prompts
+  --copy                  Copy files instead of symlink
+  -l, --list              Preview discovered skills only
+  --all                   Install all discovered skills
+
+Examples:
+  askill add @johndoe/awesome-tool -y
+  askill add gh:facebook/react@extract-errors
+  askill add owner/repo --all -a claude-code opencode -y
+
+Guide:
+  https://github.com/avibe-bot/askill/tree/main/skills/use-askill`,
+    remove: `${BOLD}askill remove${RESET}
+
+Usage:
+  askill remove <skill> [options]
+
+Description:
+  Remove an installed skill from detected agents.
+
+Options:
+  -g, --global            Remove global installation
+
+Examples:
+  askill remove memory
+  askill remove memory -g`,
+    list: `${BOLD}askill list${RESET}
+
+Usage:
+  askill list [options]
+
+Description:
+  List installed skills and where they are available.
+
+Options:
+  -g, --global            Show global skills only
+
+Examples:
+  askill list
+  askill list -g`,
+    find: `${BOLD}askill find${RESET}
+
+Usage:
+  askill find [query] [options]
+
+Description:
+  Search indexed and published skills on askill.sh.
+
+Options:
+  --full-desc             Show full descriptions
+
+Examples:
+  askill find memory
+  askill find code review --full-desc`,
+    info: `${BOLD}askill info${RESET}
+
+Usage:
+  askill info <slug>
+
+Description:
+  Show detailed metadata and installation info for one skill.
+
+Examples:
+  askill info @johndoe/awesome-tool
+  askill info gh:facebook/react@extract-errors`,
+    check: `${BOLD}askill check${RESET}
+
+Usage:
+  askill check [skill]
+
+Description:
+  Check installed skills for available updates without installing.
+
+Examples:
+  askill check
+  askill check memory`,
+    update: `${BOLD}askill update${RESET}
+
+Usage:
+  askill update [skill]
+
+Description:
+  Update one installed skill or all installed skills.
+
+Examples:
+  askill update
+  askill update memory`,
+    run: `${BOLD}askill run${RESET}
+
+Usage:
+  askill run <skill>:<command> [args...]
+
+Description:
+  Run a command declared in a skill's SKILL.md frontmatter.
+
+Examples:
+  askill run @anthropic/memory:save --key name --value "Alice"
+  askill run my-skill:_setup`,
+    validate: `${BOLD}askill validate${RESET}
+
+Usage:
+  askill validate [path]
+
+Description:
+  Validate SKILL.md frontmatter and command structure.
+
+Examples:
+  askill validate
+  askill validate ./my-skill/SKILL.md`,
+    init: `${BOLD}askill init${RESET}
+
+Usage:
+  askill init [dir] [options]
+
+Description:
+  Generate a new SKILL.md template interactively or non-interactively.
+
+Options:
+  -y, --yes               Use defaults without prompts
+
+Examples:
+  askill init
+  askill init ./my-skill -y`,
+    submit: `${BOLD}askill submit${RESET}
+
+Usage:
+  askill submit <github-url>
+
+Description:
+  Submit a GitHub repository or SKILL.md URL for indexing on askill.sh.
+
+Examples:
+  askill submit https://github.com/owner/repo
+  askill submit https://github.com/owner/repo/blob/main/skills/foo/SKILL.md`,
+    login: `${BOLD}askill login${RESET}
+
+Usage:
+  askill login [--token <ask_xxx>]
+
+Description:
+  Save and verify an askill API token for publishing.
+
+Examples:
+  askill login
+  askill login --token ask_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,
+    logout: `${BOLD}askill logout${RESET}
+
+Usage:
+  askill logout
+
+Description:
+  Clear saved local credentials.`,
+    whoami: `${BOLD}askill whoami${RESET}
+
+Usage:
+  askill whoami
+
+Description:
+  Show current authenticated account and masked token.`,
+    publish: `${BOLD}askill publish${RESET}
+
+Usage:
+  askill publish [path]
+  askill publish --github <blob-url-to-SKILL.md>
+
+Description:
+  Publish a skill under your author scope (@author/skill-name).
+
+Requirements:
+  - Logged in via askill login
+  - SKILL.md contains valid name and semver version
+
+Examples:
+  askill publish
+  askill publish ./skills/my-skill
+  askill publish --github https://github.com/owner/repo/blob/main/skills/my-skill/SKILL.md`,
+    upgrade: `${BOLD}askill upgrade${RESET}
+
+Usage:
+  askill upgrade
+
+Description:
+  Self-update askill CLI to the latest available version.`,
+    help: `${BOLD}askill help${RESET}
+
+Usage:
+  askill help
+  askill help <command>
+
+Description:
+  Show global help or detailed help for a specific command.`
+  };
+  const text2 = helps[command];
+  if (!text2) return false;
+  console.log();
+  console.log(text2);
+  console.log();
+  return true;
+}
+async function maybeAutoUpgradeOnStartup(commandInput) {
+  const command = normalizeCommand(commandInput);
+  const skipCommands = /* @__PURE__ */ new Set(["upgrade", "help", "version", "--version", "-v", "--help", "-h"]);
+  if (skipCommands.has(command)) return;
+  const available = await getAvailableUpdate(false).catch(() => null);
+  if (!available) return;
+  console.log(`${DIM}Auto-updating askill: ${available.current} -> ${available.latest}${RESET}`);
+  await selfUpdate();
+}
 function parseInstallOptions(args) {
   const options = {};
   let skillName = "";
@@ -1716,11 +1995,13 @@ async function resolveSkillsViaApi(parsed, spinner2, options) {
 }
 async function runInstall(args) {
   const { skillName, options } = parseInstallOptions(args);
+  const plainMode = Boolean(options.yes) || !process.stdout.isTTY;
   if (!skillName) {
     console.log(`${RED}Error: Missing skill identifier${RESET}`);
     console.log(`Usage: askill add <source>`);
     console.log(`
 Formats supported:`);
+    console.log(`  askill add @author/skill-name                 ${DIM}# published skill${RESET}`);
     console.log(`  askill add owner/repo                         ${DIM}# all skills from repo${RESET}`);
     console.log(`  askill add owner/repo@skill-name              ${DIM}# specific skill${RESET}`);
     console.log(`  askill add owner/repo/path/to/skill           ${DIM}# skill by path${RESET}`);
@@ -1728,9 +2009,11 @@ Formats supported:`);
     console.log(`  askill add ./local/path                       ${DIM}# local directory${RESET}`);
     process.exit(1);
   }
-  console.log();
-  p.intro(pc.bgCyan(pc.black(" askill install ")));
-  const spinner2 = p.spinner();
+  if (!plainMode) {
+    console.log();
+    p.intro(pc.bgCyan(pc.black(" askill install ")));
+  }
+  const spinner2 = createSpinner(plainMode);
   const { skills: discoveredSkills, parsed: sourceParsed, tempDir } = await resolveSkills(skillName, spinner2, options);
   const cleanup = async () => {
     if (tempDir) await cleanupTempDir(tempDir).catch(() => {
@@ -1739,7 +2022,11 @@ Formats supported:`);
   try {
     if (discoveredSkills.length === 0) {
       p.log.warning("No skills found");
-      p.outro(`Browse skills at ${pc.cyan("https://askill.sh")}`);
+      if (plainMode) {
+        console.log(`Browse skills at ${pc.cyan("https://askill.sh")}`);
+      } else {
+        p.outro(`Browse skills at ${pc.cyan("https://askill.sh")}`);
+      }
       return;
     }
     if (options.list) {
@@ -1756,7 +2043,11 @@ Formats supported:`);
         }
         console.log();
       }
-      p.outro(`Install with: ${pc.cyan(`askill add ${skillName} --all`)}`);
+      if (plainMode) {
+        console.log(`Install with: ${pc.cyan(`askill add ${skillName} --all`)}`);
+      } else {
+        p.outro(`Install with: ${pc.cyan(`askill add ${skillName} --all`)}`);
+      }
       return;
     }
     let skillsToInstall;
@@ -2011,12 +2302,16 @@ Formats supported:`);
       }
     }
     console.log();
-    p.outro(pc.green("Done!"));
+    if (plainMode) {
+      console.log(pc.green("Done!"));
+    } else {
+      p.outro(pc.green("Done!"));
+    }
   } finally {
     await cleanup();
   }
 }
-var SEARCH_DESCRIPTION_MAX_LENGTH = 180;
+var SEARCH_DESCRIPTION_MAX_LENGTH = 500;
 function toNumber(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return null;
@@ -2128,8 +2423,28 @@ function getAIScoreDimensions(skill) {
     return a.label.localeCompare(b.label);
   });
 }
+function normalizeInfoTarget(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  const withoutGh = trimmed.replace(/^gh:/i, "");
+  const askillSkillUrl = withoutGh.match(/^https?:\/\/askill\.sh\/skills\/(.+)$/i);
+  if (askillSkillUrl && askillSkillUrl[1]) {
+    return askillSkillUrl[1];
+  }
+  return withoutGh;
+}
+function parseSearchOptions(args) {
+  const fullDesc = args.includes("--full-desc");
+  const query = args.filter((arg) => arg !== "--full-desc").join(" ");
+  return {
+    fullDesc,
+    query
+  };
+}
 async function runSearch(args) {
-  const query = args.join(" ");
+  const { fullDesc, query } = parseSearchOptions(args);
   console.log();
   p.intro(pc.bgCyan(pc.black(" askill search ")));
   const spinner2 = p.spinner();
@@ -2152,7 +2467,11 @@ async function runSearch(args) {
       console.log(`  ${pc.cyan(displayName)} ${pc.dim(`by ${owner}`)}`);
       console.log(`  ${pc.dim("AI score:")} ${formatScore(aiScore)}`);
       if (description) {
-        console.log(`  ${pc.dim(description.slice(0, SEARCH_DESCRIPTION_MAX_LENGTH))}${description.length > SEARCH_DESCRIPTION_MAX_LENGTH ? "..." : ""}`);
+        if (fullDesc) {
+          console.log(`  ${pc.dim(description)}`);
+        } else {
+          console.log(`  ${pc.dim(description.slice(0, SEARCH_DESCRIPTION_MAX_LENGTH))}${description.length > SEARCH_DESCRIPTION_MAX_LENGTH ? "..." : ""}`);
+        }
       }
       const installCmd = skill.owner && skill.repo ? `gh:${skill.owner}/${skill.repo}@${displayName}` : `gh:${displayName}`;
       console.log(`  ${pc.dim("askill add")} ${installCmd}`);
@@ -2236,12 +2555,13 @@ async function runRemove(args) {
   p.outro(pc.green(`Removed ${skillName} from ${agentsWithSkill.length} agent(s)`));
 }
 async function runInfo(args) {
-  const skillName = args[0];
-  if (!skillName) {
+  const inputTarget = args[0];
+  if (!inputTarget) {
     console.log(`${RED}Error: Missing skill name${RESET}`);
     console.log(`Usage: askill info <skill-name>`);
     process.exit(1);
   }
+  const skillName = normalizeInfoTarget(inputTarget);
   console.log();
   p.intro(pc.bgCyan(pc.black(" askill info ")));
   const spinner2 = p.spinner();
@@ -3078,8 +3398,16 @@ async function runPublish(args) {
     p.log.error("SKILL.md must include frontmatter name");
     process.exit(1);
   }
-  if (!version || !/^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/.test(version)) {
-    p.log.error("SKILL.md must include a valid semver version");
+  if (!version) {
+    p.log.error('SKILL.md is missing frontmatter field "version".');
+    p.log.info("Add a semver version, for example: version: 0.1.0");
+    p.log.info("Valid examples: 1.0.0, 1.2.3-beta.1, 2.0.0+build.5");
+    process.exit(1);
+  }
+  if (!/^\d+\.\d+\.\d+(?:-[\w.]+)?(?:\+[\w.]+)?$/.test(version)) {
+    p.log.error(`Invalid semver version in SKILL.md: "${version}"`);
+    p.log.info("Expected format: MAJOR.MINOR.PATCH with optional prerelease/build");
+    p.log.info("Examples: 1.0.0, 1.1.0-beta.1, 2.0.0+build.7");
     process.exit(1);
   }
   console.log();
@@ -3113,14 +3441,16 @@ function toRawGitHubUrl(url) {
 }
 async function main() {
   const args = process.argv.slice(2);
-  checkForUpdates().catch(() => {
-  });
   if (args.length === 0) {
     showBanner();
     return;
   }
   const command = args[0];
   const restArgs = args.slice(1);
+  if ((restArgs.includes("--help") || restArgs.includes("-h")) && showCommandHelp(command)) {
+    return;
+  }
+  await maybeAutoUpgradeOnStartup(command);
   switch (command) {
     case "install":
     case "i":
@@ -3181,6 +3511,9 @@ async function main() {
     case "--help":
     case "-h":
     case "help":
+      if (restArgs[0] && showCommandHelp(restArgs[0])) {
+        break;
+      }
       showHelp();
       break;
     case "--version":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askill-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "askill - The Agent Skill Package Manager",
   "type": "module",
   "bin": {