skillmds 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
 
+## 1.0.8
+
+- `skillmds` with no command in a terminal now opens the interactive CLI menu; it only starts the MCP server when launched over piped stdio (how MCP clients run it). Previously a bare `npx skillmds` in a terminal appeared to hang on the silent MCP server.
+
+## 1.0.7
+
+- Nicer CLI output: colored PASS/FAIL, quality-score bars, `ERROR`/`WARN`/`INFO` badges, and a summary with average score.
+- Running `skillmd` (or `skillmds`) with no command on a terminal now opens a guided interactive menu (lint, scan, search, init, list). Piped/CI still prints help.
+- Progress spinner while scanning.
+
 ## 1.0.6
 
 - Bundle the banner image in the package and serve it via jsDelivr so it renders on the npm page (the previous absolute URL was unreachable).

package/bin/skillmd-mcp.mjs

@@ -211,16 +211,21 @@ async function startMcpServer() {
   console.error("skillmd MCP server running (stdio)");
 }
 
-// This binary is invoked two ways:
-//   - `skillmds`                  → start the MCP server (stdio; how MCP clients launch it)
+// This binary is invoked three ways:
 //   - `skillmds lint .` etc.      → run the CLI (so `npx skillmds <cmd>` works without -p)
+//   - `skillmds` in a terminal    → run the CLI (opens the interactive menu)
+//   - `skillmds` over piped stdio → start the MCP server (how MCP clients launch it)
+// MCP clients always connect stdin as a pipe (never a TTY), so an interactive
+// stdin is a reliable signal that a human is present.
 const CLI_COMMANDS = new Set([
   "lint", "check", "scan", "rules", "init", "search", "add", "list", "ls",
   "remove", "rm", "update", "publish", "submit", "login", "logout", "help",
   "--help", "-h", "--version", "-V",
 ]);
 const first = process.argv[2];
-if (first && CLI_COMMANDS.has(first)) {
+const isCliCommand = first && CLI_COMMANDS.has(first);
+const humanInTerminal = !first && process.stdin.isTTY;
+if (isCliCommand || humanInTerminal) {
   await import("../dist/cli.js"); // the CLI parses process.argv itself
 } else {
   await startMcpServer();

package/dist/cli.js

@@ -7,6 +7,8 @@ import { Command } from "commander";
 import { writeFileSync } from "fs";
 import { homedir } from "os";
 import { resolve } from "path";
+import pc2 from "picocolors";
+import * as p from "@clack/prompts";
 
 // ../../packages/core/src/parse.ts
 import { parse as parseYaml } from "yaml";
@@ -46,9 +48,9 @@ var RULES = [
 ];
 function scanSecurity(body) {
   const findings = [];
-  body.split(/\r?\n/).forEach((text2, i) => {
+  body.split(/\r?\n/).forEach((text3, i) => {
     for (const [flag, re] of RULES) {
-      if (re.test(text2)) findings.push({ flag, line: i + 1, snippet: text2.trim().slice(0, 120) });
+      if (re.test(text3)) findings.push({ flag, line: i + 1, snippet: text3.trim().slice(0, 120) });
     }
   });
   const flags = [...new Set(findings.map((f) => f.flag))];
@@ -354,20 +356,54 @@ function normalizeGiget(arg) {
 
 // ../cli/src/ui.ts
 import pc from "picocolors";
-var decorate = (text2, kind) => {
+var decorate = (text3, kind) => {
   switch (kind) {
     case "error":
-      return pc.red(text2);
+      return pc.red(text3);
     case "warn":
-      return pc.yellow(text2);
+      return pc.yellow(text3);
     case "info":
-      return pc.cyan(text2);
+      return pc.cyan(text3);
     case "ok":
-      return pc.green(text2);
+      return pc.green(text3);
     case "dim":
-      return pc.dim(text2);
+      return pc.dim(text3);
   }
 };
+var badge = {
+  error: pc.bgRed(pc.white(" ERROR ")),
+  warn: pc.bgYellow(pc.black(" WARN  ")),
+  info: pc.bgCyan(pc.black(" INFO  "))
+};
+function scoreBar(score) {
+  const filled = Math.max(0, Math.min(10, Math.round(score / 10)));
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(10 - filled);
+  const color = score >= 80 ? pc.green : score >= 50 ? pc.yellow : pc.red;
+  return `${color(bar)} ${pc.bold(String(score))}${pc.dim("/100")}`;
+}
+function renderReport(results) {
+  const out = [];
+  for (const { file, result } of results) {
+    const status = result.ok ? pc.green("\u25CF") + pc.bold(" PASS") : pc.red("\u25CF") + pc.bold(" FAIL");
+    out.push("");
+    out.push(`${status}  ${pc.bold(file)}`);
+    out.push(`        ${scoreBar(result.score)}`);
+    for (const d of result.diagnostics) {
+      const loc = d.line !== void 0 ? pc.dim(`:${d.line}`) : "";
+      out.push(`   ${badge[d.severity]} ${pc.dim(d.id)}${loc}  ${d.message}`);
+    }
+    const flags = result.security.flags.filter((f) => f !== "docs_only");
+    if (flags.length) out.push(`   ${pc.magenta("\u2691 security")}  ${pc.dim(flags.join(", "))}`);
+  }
+  const failed = results.filter((r) => !r.result.ok).length;
+  const passed = results.length - failed;
+  const avg = results.length ? Math.round(results.reduce((s, r) => s + r.result.score, 0) / results.length) : 0;
+  out.push("");
+  out.push(pc.dim("\u2500".repeat(44)));
+  const tally = failed === 0 ? pc.green(`\u2713 ${passed} passed`) : `${pc.green(`${passed} passed`)}  ${pc.red(`\u2717 ${failed} failed`)}`;
+  out.push(`${tally}    ${pc.dim("avg")} ${scoreBar(avg)}`);
+  return out.join("\n");
+}
 function exitCodeFor(results, policy = {}) {
   for (const { result } of results) {
     const hasError = result.diagnostics.some((d) => d.severity === "error");
@@ -413,14 +449,33 @@ async function runLint(target, flags) {
       output = toGithub(results);
       break;
     default:
-      output = toText(results, { decorate });
+      output = renderReport(results);
   }
   return { results, output, exitCode };
 }
 function lintCommand() {
   return new Command("lint").alias("check").description("Validate SKILL.md file(s) against the spec and report a quality score").argument("[target]", "local path or GitHub source", ".").option("--format <fmt>", "text | json | sarif | github", "text").option("--strict", "treat warnings as errors").option("--fail-on-warning", "exit non-zero when warnings exist").option("--fix", "apply safe automatic fixes (e.g. add missing license)").action(async (target, opts) => {
+    const ui = Boolean(process.stdout.isTTY) && opts.format === "text";
     if (resolve(target) === homedir()) {
-      process.stderr.write("Warning: scanning your entire home directory. Pass a narrower path, e.g. skillmd lint ./my-skill\n");
+      process.stderr.write(pc2.yellow(`Warning: scanning your entire home directory. Pass a narrower path, e.g. skillmd lint ./my-skill
+`));
+    }
+    if (ui) {
+      p.intro(pc2.bgCyan(pc2.black(" skillmd lint ")));
+      const s = p.spinner();
+      s.start(`Scanning ${target}`);
+      try {
+        const run2 = await runLint(target, opts);
+        s.stop(`Scanned ${run2.results.length} skill${run2.results.length === 1 ? "" : "s"}`);
+        console.log(run2.output);
+        p.outro(run2.exitCode === 0 ? pc2.green("All good") : pc2.red("Problems found"));
+        process.exitCode = run2.exitCode;
+      } catch (err) {
+        s.stop(pc2.red("No skills found"));
+        p.outro(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+      return;
     }
     process.stderr.write(`Looking for SKILL.md under ${target} \u2026
 `);
@@ -432,7 +487,7 @@ function lintCommand() {
 
 // ../cli/src/commands/scan.ts
 import { Command as Command2 } from "commander";
-import pc2 from "picocolors";
+import pc3 from "picocolors";
 async function runScan(target, flags) {
   const resolved = await resolveSource(target);
   const deny = new Set(flags.deny ?? []);
@@ -451,11 +506,11 @@ async function runScan(target, flags) {
     const lines = [];
     for (const e of entries) {
       const flagStr = e.security.flags.join(", ");
-      const head = e.denied.length ? pc2.red(`DENY ${e.file}`) : pc2.green(`OK   ${e.file}`);
-      lines.push(`${head}  ${pc2.dim(flagStr)}`);
+      const head = e.denied.length ? pc3.red(`DENY ${e.file}`) : pc3.green(`OK   ${e.file}`);
+      lines.push(`${head}  ${pc3.dim(flagStr)}`);
       for (const f of e.security.findings) {
-        const mark = deny.has(f.flag) ? pc2.red(f.flag) : pc2.yellow(f.flag);
-        lines.push(`  ${mark}  :${f.line}  ${pc2.dim(f.snippet)}`);
+        const mark = deny.has(f.flag) ? pc3.red(f.flag) : pc3.yellow(f.flag);
+        lines.push(`  ${mark}  :${f.line}  ${pc3.dim(f.snippet)}`);
       }
     }
     output = lines.join("\n");
@@ -472,7 +527,7 @@ function scanCommand() {
 
 // ../cli/src/commands/rules.ts
 import { Command as Command3 } from "commander";
-import pc3 from "picocolors";
+import pc4 from "picocolors";
 function rulesCommand() {
   return new Command3("rules").description("List lint rules, or show detail for one rule id").argument("[id]", "a rule id, e.g. SK010").option("--json", "machine-readable output").action((id, opts) => {
     const list = id ? RULES2.filter((r) => r.id.toLowerCase() === id.toLowerCase()) : RULES2;
@@ -485,8 +540,10 @@ function rulesCommand() {
       console.log(JSON.stringify(list.map((r) => ({ id: r.id, severity: r.severity, description: r.description })), null, 2));
       return;
     }
-    const color = (sev) => (sev === "error" ? pc3.red : sev === "warn" ? pc3.yellow : pc3.cyan)(sev.padEnd(5));
-    for (const r of list) console.log(`${pc3.bold(r.id)}  ${color(r.severity)}  ${r.description}`);
+    const badge2 = (sev) => sev === "error" ? pc4.bgRed(pc4.white(" error ")) : sev === "warn" ? pc4.bgYellow(pc4.black(" warn  ")) : pc4.bgCyan(pc4.black(" info  "));
+    console.log(pc4.bold("\nLint rules\n"));
+    for (const r of list) console.log(`  ${pc4.bold(r.id)}  ${badge2(r.severity)}  ${r.description}`);
+    console.log("");
   });
 }
 
@@ -494,7 +551,7 @@ function rulesCommand() {
 import { Command as Command4 } from "commander";
 import { mkdirSync, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
 import { join as join2 } from "path";
-import * as p from "@clack/prompts";
+import * as p2 from "@clack/prompts";
 function skillTemplate(name, description, license) {
   const desc = description.trim() || `A skill that helps agents with ${name}.`;
   return `---
@@ -534,9 +591,9 @@ function initCommand() {
   return new Command4("init").description("Scaffold a new SKILL.md from a template").argument("[name]", "skill name").option("--name <name>", "skill name (non-interactive)").option("--description <text>", "skill description").option("--license <license>", "license identifier", "MIT").option("-y, --yes", "skip prompts").action(async (nameArg, opts) => {
     let name = nameArg ?? opts.name;
     if (!name && !opts.yes) {
-      const answer = await p.text({ message: "Skill name?", placeholder: "my-skill" });
-      if (p.isCancel(answer)) {
-        p.cancel("Cancelled.");
+      const answer = await p2.text({ message: "Skill name?", placeholder: "my-skill" });
+      if (p2.isCancel(answer)) {
+        p2.cancel("Cancelled.");
         return;
       }
       name = answer;
@@ -553,7 +610,7 @@ function initCommand() {
 
 // ../cli/src/commands/search.ts
 import { Command as Command5 } from "commander";
-import pc4 from "picocolors";
+import pc5 from "picocolors";
 
 // ../cli/src/config.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
@@ -618,10 +675,10 @@ async function runSearch(query, flags) {
   const items = r.items ?? [];
   if (flags.json) return { items, output: JSON.stringify(items, null, 2) };
   const lines = items.map((s) => {
-    const check = s.verified ? pc4.green("\u2713") : " ";
-    const rating = s.avg_rating ? pc4.dim(`\u2605${s.avg_rating.toFixed(1)} (${s.rating_count ?? 0})`) : "";
-    return `${check} ${pc4.bold(s.slug)} ${rating}
-    ${pc4.dim(s.description)}`;
+    const check = s.verified ? pc5.green("\u2713") : " ";
+    const rating = s.avg_rating ? pc5.dim(`\u2605${s.avg_rating.toFixed(1)} (${s.rating_count ?? 0})`) : "";
+    return `${check} ${pc5.bold(s.slug)} ${rating}
+    ${pc5.dim(s.description)}`;
   });
   return { items, output: lines.join("\n") || "No skills found." };
 }
@@ -636,7 +693,7 @@ function searchCommand() {
 // ../cli/src/commands/add.ts
 import { Command as Command6 } from "commander";
 import { existsSync as existsSync4 } from "fs";
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 
 // ../cli/src/agents.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, rmSync, symlinkSync, existsSync as existsSync3, readdirSync as readdirSync2, statSync as statSync2, readFileSync as readFileSync3 } from "fs";
@@ -737,24 +794,24 @@ async function runAdd(arg, flags, deps = defaultDeps) {
     const deniedFlags = result.security.flags.filter((f) => deny.has(f));
     if (!flags.skipLint && !result.ok) {
       blocked.push({ name: c.name, reason: `lint errors: ${result.diagnostics.filter((d) => d.severity === "error").map((d) => d.id).join(", ")}` });
-      lines.push(pc5.red(`\u2717 ${c.name} blocked \u2014 failed lint (use --skip-lint to override)`));
+      lines.push(pc6.red(`\u2717 ${c.name} blocked \u2014 failed lint (use --skip-lint to override)`));
       continue;
     }
     if (deniedFlags.length) {
       blocked.push({ name: c.name, reason: `denied security flags: ${deniedFlags.join(", ")}` });
-      lines.push(pc5.red(`\u2717 ${c.name} blocked \u2014 ${deniedFlags.join(", ")}`));
+      lines.push(pc6.red(`\u2717 ${c.name} blocked \u2014 ${deniedFlags.join(", ")}`));
       continue;
     }
     if (c.registrySlug && c.verified === false && !flags.allowUnverified) {
       blocked.push({ name: c.name, reason: "unverified registry skill (use --allow-unverified)" });
-      lines.push(pc5.yellow(`\u2717 ${c.name} blocked \u2014 unverified (use --allow-unverified)`));
+      lines.push(pc6.yellow(`\u2717 ${c.name} blocked \u2014 unverified (use --allow-unverified)`));
       continue;
     }
     for (const agentId of targets) {
       const dir = agentDir(agentId, scope);
       const out = writeSkill(c.name, [{ path: "SKILL.md", contents: c.raw }], dir, { mode: "copy" });
       written.push({ name: c.name, dir: out });
-      lines.push(pc5.green(`\u2713 ${c.name} \u2192 ${out}`));
+      lines.push(pc6.green(`\u2713 ${c.name} \u2192 ${out}`));
     }
     if (c.registrySlug) deps.fireInstall(c.registrySlug, flags);
   }
@@ -772,7 +829,7 @@ function addCommand() {
 
 // ../cli/src/commands/list.ts
 import { Command as Command7 } from "commander";
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 function listCommand() {
   return new Command7("list").alias("ls").description("List installed skills across detected agents").option("-g, --global", "only global skills").option("--json", "machine-readable output").action((opts) => {
     const scope = { global: opts.global };
@@ -787,8 +844,8 @@ function listCommand() {
     }
     for (const s of skills) {
       const parsed = parseSkillMd(s.raw);
-      const desc = "error" in parsed ? pc6.red("(invalid SKILL.md)") : pc6.dim(parsed.description.slice(0, 80));
-      console.log(`${pc6.bold(s.name)} ${pc6.dim(`[${s.agent}/${s.scope}]`)}
+      const desc = "error" in parsed ? pc7.red("(invalid SKILL.md)") : pc7.dim(parsed.description.slice(0, 80));
+      console.log(`${pc7.bold(s.name)} ${pc7.dim(`[${s.agent}/${s.scope}]`)}
     ${desc}`);
     }
   });
@@ -797,7 +854,7 @@ function listCommand() {
 // ../cli/src/commands/remove.ts
 import { Command as Command8 } from "commander";
 import { rmSync as rmSync2 } from "fs";
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 function runRemove(names, scope = {}) {
   const installed = installedSkills(scope);
   const targets = installed.filter((s) => names.includes(s.name));
@@ -806,10 +863,10 @@ function runRemove(names, scope = {}) {
   for (const t of targets) {
     rmSync2(t.path, { recursive: true, force: true });
     removed.push(t.path);
-    lines.push(pc7.green(`\u2713 removed ${t.name} (${t.agent})`));
+    lines.push(pc8.green(`\u2713 removed ${t.name} (${t.agent})`));
   }
   for (const n of names) {
-    if (!targets.some((t) => t.name === n)) lines.push(pc7.yellow(`- ${n} not installed`));
+    if (!targets.some((t) => t.name === n)) lines.push(pc8.yellow(`- ${n} not installed`));
   }
   return { removed, output: lines.join("\n") };
 }
@@ -824,7 +881,7 @@ function removeCommand() {
 import { Command as Command9 } from "commander";
 import { writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 async function runUpdate(names, flags, scope = {}) {
   const { api } = createClient(flags);
   const installed = installedSkills(scope).filter((s) => names.length === 0 || names.includes(s.name));
@@ -833,7 +890,7 @@ async function runUpdate(names, flags, scope = {}) {
   for (const s of installed) {
     const slug = await findRegistrySlug(api, s);
     if (!slug) {
-      lines.push(pc8.dim(`- ${s.name} skipped (no registry match)`));
+      lines.push(pc9.dim(`- ${s.name} skipped (no registry match)`));
       continue;
     }
     try {
@@ -841,19 +898,19 @@ async function runUpdate(names, flags, scope = {}) {
       const skill = await api(`/api/skills/${owner}/${name}`);
       const next = reconstructSkillMd(skill);
       if (next.trim() === s.raw.trim()) {
-        lines.push(pc8.dim(`- ${s.name} already up to date`));
+        lines.push(pc9.dim(`- ${s.name} already up to date`));
         continue;
       }
       const result = lint(next, { slug: s.name });
       if (!result.ok) {
-        lines.push(pc8.red(`\u2717 ${s.name} update failed lint \u2014 skipped`));
+        lines.push(pc9.red(`\u2717 ${s.name} update failed lint \u2014 skipped`));
         continue;
       }
       writeFileSync5(join5(s.path, "SKILL.md"), next, "utf8");
       updated.push(s.name);
-      lines.push(pc8.green(`\u2713 updated ${s.name}`));
+      lines.push(pc9.green(`\u2713 updated ${s.name}`));
     } catch {
-      lines.push(pc8.red(`\u2717 ${s.name} update error`));
+      lines.push(pc9.red(`\u2717 ${s.name} update error`));
     }
   }
   return { updated, output: lines.join("\n") || "Nothing to update." };
@@ -873,7 +930,7 @@ function updateCommand() {
 
 // ../cli/src/commands/publish.ts
 import { Command as Command10 } from "commander";
-import pc9 from "picocolors";
+import pc10 from "picocolors";
 var defaultDeps2 = {
   resolve: resolveSource,
   async submit(payload, flags) {
@@ -896,20 +953,20 @@ async function runPublish(target, flags, deps = defaultDeps2) {
   const report = toText([{ file: src.path, result }], { decorate });
   if (!result.ok) {
     return { result, published: false, exitCode: 1, output: `${report}
-${pc9.red("\u2717 Refusing to publish: fix the errors above.")}` };
+${pc10.red("\u2717 Refusing to publish: fix the errors above.")}` };
   }
   const hasWarn = result.diagnostics.some((d) => d.severity === "warn");
   if (hasWarn && !flags.force) {
     return { result, published: false, exitCode: 1, output: `${report}
-${pc9.yellow("\u2717 Warnings present. Re-run with --force to publish anyway.")}` };
+${pc10.yellow("\u2717 Warnings present. Re-run with --force to publish anyway.")}` };
   }
   if (flags.dryRun) {
     return { result, published: false, exitCode: 0, output: `${report}
-${pc9.green("\u2713 Dry run: would publish.")}` };
+${pc10.green("\u2713 Dry run: would publish.")}` };
   }
   const res = await deps.submit({ content: src.raw, type: flags.type ?? "single" }, flags);
   return { result, published: true, slug: res.slug, exitCode: 0, output: `${report}
-${pc9.green(`\u2713 Published ${res.slug ?? src.slug} (status: ${res.status ?? "pending"})`)}` };
+${pc10.green(`\u2713 Published ${res.slug ?? src.slug} (status: ${res.status ?? "pending"})`)}` };
 }
 function publishCommand() {
   return new Command10("publish").alias("submit").description("Publish a skill to the registry (refuses to publish on lint errors)").argument("[target]", "local path to the skill", ".").option("--type <type>", "single | pack", "single").option("--force", "publish despite warnings (never bypasses errors)").option("--dry-run", "lint only; do not publish").action(async (target, opts, cmd) => {
@@ -922,14 +979,14 @@ function publishCommand() {
 
 // ../cli/src/commands/login.ts
 import { Command as Command11 } from "commander";
-import * as p2 from "@clack/prompts";
+import * as p3 from "@clack/prompts";
 function loginCommand() {
   return new Command11("login").description("Store a SkillMD personal access token for publishing").option("--token <token>", "token to store (otherwise prompt)").option("--api <url>", "registry API base to store").action(async (opts) => {
     let token = opts.token;
     if (!token) {
-      const answer = await p2.password({ message: "Paste your SkillMD token (from your account page)" });
-      if (p2.isCancel(answer)) {
-        p2.cancel("Cancelled.");
+      const answer = await p3.password({ message: "Paste your SkillMD token (from your account page)" });
+      if (p3.isCancel(answer)) {
+        p3.cancel("Cancelled.");
         return;
       }
       token = answer;
@@ -955,6 +1012,118 @@ function logoutCommand() {
   });
 }
 
+// ../cli/src/commands/interactive.ts
+import * as p4 from "@clack/prompts";
+import pc11 from "picocolors";
+function bail(v) {
+  if (p4.isCancel(v)) {
+    p4.cancel("Cancelled.");
+    return true;
+  }
+  return false;
+}
+async function runInteractive() {
+  p4.intro(pc11.bgCyan(pc11.black(" skillmd ")));
+  const action = await p4.select({
+    message: "What would you like to do?",
+    options: [
+      { value: "lint", label: "Lint a skill", hint: "validate a SKILL.md" },
+      { value: "scan", label: "Security scan", hint: "scripts, network, secrets" },
+      { value: "search", label: "Search the registry" },
+      { value: "init", label: "Create a new skill" },
+      { value: "list", label: "List installed skills" },
+      { value: "help", label: "Show all commands" }
+    ]
+  });
+  if (bail(action)) return;
+  switch (action) {
+    case "lint":
+    case "scan": {
+      const path = await p4.text({ message: "Path to a skill or folder", placeholder: ".", defaultValue: "." });
+      if (bail(path)) return;
+      const target = String(path || ".");
+      const s = p4.spinner();
+      s.start(action === "lint" ? "Linting" : "Scanning");
+      try {
+        const run = action === "lint" ? await runLint(target, { format: "text" }) : await runScan(target, { format: "text" });
+        s.stop("Done");
+        console.log(run.output);
+        process.exitCode = run.exitCode;
+      } catch (err) {
+        s.stop(pc11.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "search": {
+      const query = await p4.text({ message: "Search the registry for" });
+      if (bail(query)) return;
+      const verified = await p4.confirm({ message: "Verified skills only?", initialValue: false });
+      if (bail(verified)) return;
+      const s = p4.spinner();
+      s.start("Searching");
+      try {
+        const run = await runSearch(String(query), { verified: Boolean(verified), limit: "20" });
+        s.stop(`${run.items.length} result${run.items.length === 1 ? "" : "s"}`);
+        console.log(run.output);
+      } catch (err) {
+        s.stop(pc11.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "init": {
+      const name = await p4.text({ message: "Skill name", placeholder: "my-skill" });
+      if (bail(name)) return;
+      const description = await p4.text({ message: "One-line description", placeholder: "What this skill helps an agent do" });
+      if (bail(description)) return;
+      try {
+        const file = initSkill(String(name), { description: String(description || "") });
+        p4.log.success(`Created ${pc11.bold(file)}`);
+      } catch (err) {
+        p4.log.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "list": {
+      const global = await p4.confirm({ message: "Include global skills?", initialValue: true });
+      if (bail(global)) return;
+      const skills = installedSkills({ global: Boolean(global) });
+      if (skills.length === 0) {
+        p4.log.info("No installed skills found.");
+      } else {
+        p4.log.message(
+          skills.map((sk) => {
+            const parsed = parseSkillMd(sk.raw);
+            const desc = "error" in parsed ? pc11.red("(invalid)") : pc11.dim(parsed.description.slice(0, 70));
+            return `${pc11.bold(sk.name)} ${pc11.dim(`[${sk.agent}]`)}
+  ${desc}`;
+          }).join("\n")
+        );
+      }
+      break;
+    }
+    case "help": {
+      p4.note(
+        [
+          `${pc11.bold("lint")} [path]      validate SKILL.md + quality score`,
+          `${pc11.bold("scan")} [path]      security scan`,
+          `${pc11.bold("search")} <query>   search the registry`,
+          `${pc11.bold("add")} <source>     install a skill (lints first)`,
+          `${pc11.bold("init")} [name]      scaffold a new skill`,
+          `${pc11.bold("list / remove / update")}   manage installed skills`,
+          `${pc11.bold("publish")} [path]   publish (fails on lint errors)`,
+          `${pc11.bold("rules / login")}`
+        ].join("\n"),
+        "Commands (run: skillmd <command>)"
+      );
+      break;
+    }
+  }
+  p4.outro(pc11.dim("skillmd.com"));
+}
+
 // ../cli/src/index.ts
 var version = "0.0.0";
 try {
@@ -975,6 +1144,10 @@ program.addCommand(publishCommand());
 program.addCommand(loginCommand());
 program.addCommand(logoutCommand());
 if (process.argv.slice(2).length === 0) {
+  if (process.stdout.isTTY) {
+    await runInteractive();
+    process.exit(process.exitCode ?? 0);
+  }
   program.outputHelp();
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillmds",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "SkillMD for agents: the `skillmds` MCP server + the `skillmd` CLI (lint, scan, search, install, publish Agent Skills) from skillmd.com.",
   "type": "module",
   "bin": {