@skillkit/cli 1.8.1 → 1.10.0

package/dist/index.js

@@ -1,5 +1,11 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -1215,7 +1221,7 @@ init_onboarding();
 import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
 import { dirname } from "path";
 import { Command as Command3, Option as Option3 } from "clipanion";
-import { loadConfig as loadConfig2, findAllSkills as findAllSkills2 } from "@skillkit/core";
+import { findAllSkills as findAllSkills2 } from "@skillkit/core";
 import { getAdapter as getAdapter2, detectAgent as detectAgent2, getAllAdapters } from "@skillkit/agents";
 var SyncCommand = class extends Command3 {
   static paths = [["sync"], ["s"]];
@@ -1255,8 +1261,7 @@ var SyncCommand = class extends Command3 {
         agentType = this.agent;
       } else if (isInteractive) {
         s.start("Detecting agent...");
-        const config2 = loadConfig2();
-        const detected = config2.agent || await detectAgent2();
+        const detected = await detectAgent2();
         s.stop(`Detected: ${formatAgent(detected)}`);
         const allAgents = getAllAdapters().map((a) => a.type);
         const agentResult = await select2({
@@ -1274,8 +1279,7 @@ var SyncCommand = class extends Command3 {
         }
         agentType = agentResult;
       } else {
-        const config2 = loadConfig2();
-        agentType = config2.agent || await detectAgent2();
+        agentType = await detectAgent2();
       }
       const adapter = getAdapter2(agentType);
       const outputPath = this.output || getAgentConfigPath(agentType);
@@ -1650,10 +1654,13 @@ init_helpers();
 init_onboarding();
 import { existsSync as existsSync5, mkdirSync as mkdirSync3, cpSync, rmSync as rmSync2, symlinkSync } from "fs";
 import { join as join3 } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { Command as Command7, Option as Option7 } from "clipanion";
 import { detectProvider, isLocalPath, getProvider, evaluateSkillDirectory as evaluateSkillDirectory2 } from "@skillkit/core";
 import { isPathInside } from "@skillkit/core";
 import { getAdapter as getAdapter4, detectAgent as detectAgent4, getAllAdapters as getAllAdapters3 } from "@skillkit/agents";
+var execFileAsync = promisify(execFile);
 var InstallCommand = class extends Command7 {
   static paths = [["install"], ["i"], ["add"]];
   static usage = Command7.Usage({
@@ -1662,7 +1669,8 @@ var InstallCommand = class extends Command7 {
       ["Install from GitHub", "$0 install owner/repo"],
       ["Install from GitLab", "$0 install gitlab:owner/repo"],
       ["Install from Bitbucket", "$0 install bitbucket:owner/repo"],
-      ["Install specific skills (CI/CD)", "$0 install owner/repo --skills=pdf,xlsx"],
+      ["Install specific skill", "$0 install owner/repo --skill=pdf"],
+      ["Install multiple skills (CI/CD)", "$0 install owner/repo --skills=pdf,xlsx"],
       ["Install all skills non-interactively", "$0 install owner/repo --all"],
       ["Install from local path", "$0 install ./my-skills"],
       ["Install globally", "$0 install owner/repo --global"],
@@ -1671,7 +1679,7 @@ var InstallCommand = class extends Command7 {
     ]
   });
   source = Option7.String({ required: true });
-  skills = Option7.String("--skills,-s", {
+  skills = Option7.String("--skills,--skill,-s", {
     description: "Comma-separated list of skills to install (non-interactive)"
   });
   all = Option7.Boolean("--all,-a", false, {
@@ -1740,7 +1748,7 @@ var InstallCommand = class extends Command7 {
           }
           console.log("");
           console.log(colors.muted(`Total: ${discoveredSkills.length} skill(s)`));
-          console.log(colors.muted("To install: skillkit install <source> --skills=skill1,skill2"));
+          console.log(colors.muted("To install: skillkit install <source> --skill=name"));
         }
         const cleanupPath2 = result.tempRoot || result.path;
         if (!isLocalPath(this.source) && cleanupPath2 && existsSync5(cleanupPath2)) {
@@ -1880,6 +1888,19 @@ var InstallCommand = class extends Command7 {
               if (isSymlinkMode && primaryPath === null) {
                 primaryPath = targetPath;
               }
+              const packageJsonPath = join3(targetPath, "package.json");
+              if (existsSync5(packageJsonPath)) {
+                s.stop(`Installed ${skillName} to ${adapter.name}`);
+                s.start(`Installing npm dependencies for ${skillName}...`);
+                try {
+                  await execFileAsync("npm", ["install", "--production"], { cwd: targetPath });
+                  s.stop(`Installed dependencies for ${skillName}`);
+                } catch (npmErr) {
+                  s.stop(colors.warning(`Dependencies failed for ${skillName}`));
+                  console.log(colors.muted("Run manually: npm install in " + targetPath));
+                }
+                s.start(`Finishing ${skillName} installation...`);
+              }
             }
             const metadata = {
               name: skillName,
@@ -3338,6 +3359,7 @@ import { resolve as resolve4 } from "path";
 import {
   ContextManager as ContextManager2,
   RecommendationEngine,
+  ReasoningRecommendationEngine,
   buildSkillIndex,
   saveIndex,
   loadIndex as loadIndexFromCache,
@@ -3369,7 +3391,10 @@ var RecommendCommand = class extends Command15 {
       ["Show detailed reasons", "$0 recommend --verbose"],
       ["Update skill index", "$0 recommend --update"],
       ["Search for skills by task", '$0 recommend --task "authentication"'],
-      ["Search for skills (alias)", '$0 recommend --search "testing"']
+      ["Search for skills (alias)", '$0 recommend --search "testing"'],
+      ["Hybrid search (vector + keyword)", '$0 recommend --search "auth" --hybrid'],
+      ["Hybrid search with query expansion", '$0 recommend --search "auth" --hybrid --expand'],
+      ["Build hybrid search index", "$0 recommend --build-index"]
     ]
   });
   // Limit number of results
@@ -3416,11 +3441,45 @@ var RecommendCommand = class extends Command15 {
   quiet = Option14.Boolean("--quiet,-q", false, {
     description: "Minimal output"
   });
+  // Explain mode (reasoning-based recommendations)
+  explain = Option14.Boolean("--explain,-e", false, {
+    description: "Show detailed explanations for recommendations (uses reasoning engine)"
+  });
+  // Reasoning mode
+  reasoning = Option14.Boolean("--reasoning,-r", false, {
+    description: "Use LLM-based reasoning for recommendations"
+  });
+  // Show tree path
+  showPath = Option14.Boolean("--show-path", false, {
+    description: "Show category path for each recommendation"
+  });
+  // Hybrid search mode
+  hybrid = Option14.Boolean("--hybrid,-H", false, {
+    description: "Use hybrid search (vector + keyword)"
+  });
+  // Query expansion
+  expand = Option14.Boolean("--expand,-x", false, {
+    description: "Enable query expansion (requires --hybrid)"
+  });
+  // Reranking
+  rerank = Option14.Boolean("--rerank", false, {
+    description: "Enable LLM reranking (requires --hybrid)"
+  });
+  // Build index
+  buildIndex = Option14.Boolean("--build-index", false, {
+    description: "Build/rebuild the hybrid search embedding index"
+  });
   async execute() {
     const targetPath = resolve4(this.projectPath || process.cwd());
     if (this.update) {
       return await this.updateIndex();
     }
+    if (this.buildIndex) {
+      return await this.buildHybridIndex();
+    }
+    if ((this.expand || this.rerank) && !this.hybrid) {
+      warn("--expand and --rerank require --hybrid flag. These options will be ignored.");
+    }
     if (!this.quiet && !this.json) {
       header("Skill Recommendations");
     }
@@ -3437,10 +3496,16 @@ var RecommendCommand = class extends Command15 {
       this.showProjectProfile(profile);
       return 0;
     }
+    if (this.explain || this.reasoning || this.showPath) {
+      return await this.handleReasoningRecommendations(profile, index);
+    }
     const engine = new RecommendationEngine();
     engine.loadIndex(index);
     const searchQuery = this.search || this.task;
     if (searchQuery) {
+      if (this.hybrid) {
+        return await this.handleHybridSearch(engine, searchQuery);
+      }
       return this.handleSearch(engine, searchQuery);
     }
     const result = engine.recommend(profile, {
@@ -3457,6 +3522,53 @@ var RecommendCommand = class extends Command15 {
     this.displayRecommendations(result.recommendations, profile, result.totalSkillsScanned);
     return 0;
   }
+  async handleReasoningRecommendations(profile, index) {
+    const s = !this.quiet && !this.json ? spinner2() : null;
+    s?.start("Analyzing with reasoning engine...");
+    try {
+      const engine = new ReasoningRecommendationEngine();
+      engine.loadIndex(index);
+      await engine.initReasoning();
+      const result = await engine.recommendWithReasoning(profile, {
+        limit: this.limit ? parseInt(this.limit, 10) : 10,
+        minScore: this.minScore ? parseInt(this.minScore, 10) : 30,
+        categories: this.category,
+        excludeInstalled: !this.includeInstalled,
+        includeReasons: this.verbose,
+        reasoning: this.reasoning,
+        explainResults: this.explain,
+        useTree: true
+      });
+      s?.stop("Analysis complete");
+      if (this.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+      }
+      this.displayExplainedRecommendations(
+        result.recommendations,
+        profile,
+        result.totalSkillsScanned,
+        result.reasoningSummary
+      );
+      return 0;
+    } catch (err) {
+      s?.stop(colors.error("Reasoning analysis failed"));
+      console.log(colors.muted(err instanceof Error ? err.message : String(err)));
+      console.log(colors.muted("Falling back to standard recommendations..."));
+      console.log("");
+      const engine = new RecommendationEngine();
+      engine.loadIndex(index);
+      const result = engine.recommend(profile, {
+        limit: this.limit ? parseInt(this.limit, 10) : 10,
+        minScore: this.minScore ? parseInt(this.minScore, 10) : 30,
+        categories: this.category,
+        excludeInstalled: !this.includeInstalled,
+        includeReasons: this.verbose
+      });
+      this.displayRecommendations(result.recommendations, profile, result.totalSkillsScanned);
+      return 0;
+    }
+  }
   async getProjectProfile(projectPath) {
     const manager = new ContextManager2(projectPath);
     let context = manager.get();
@@ -3539,6 +3651,178 @@ var RecommendCommand = class extends Command15 {
     }
     console.log(colors.muted("Install with: skillkit install <source>"));
   }
+  displayExplainedRecommendations(recommendations, profile, totalScanned, reasoningSummary) {
+    this.showProjectProfile(profile);
+    if (reasoningSummary && !this.quiet) {
+      console.log(colors.dim("Reasoning: ") + colors.muted(reasoningSummary));
+      console.log("");
+    }
+    if (recommendations.length === 0) {
+      warn("No matching skills found.");
+      console.log(colors.muted("Try lowering the minimum score with --min-score"));
+      return;
+    }
+    console.log(colors.bold(`Explained Recommendations (${recommendations.length} of ${totalScanned} scanned):`));
+    console.log("");
+    for (const rec of recommendations) {
+      let scoreColor;
+      if (rec.score >= 70) {
+        scoreColor = colors.success;
+      } else if (rec.score >= 50) {
+        scoreColor = colors.warning;
+      } else {
+        scoreColor = colors.muted;
+      }
+      const scoreBar = progressBar(rec.score, 100, 10);
+      const qualityScore = rec.skill.quality ?? null;
+      const qualityDisplay = qualityScore !== null && qualityScore !== void 0 ? ` ${formatQualityBadge(qualityScore)}` : "";
+      console.log(`  ${scoreColor(`${rec.score}%`)} ${colors.dim(scoreBar)} ${colors.bold(rec.skill.name)}${qualityDisplay}`);
+      if (this.showPath && rec.treePath && rec.treePath.length > 0) {
+        console.log(`      ${colors.accent("Path:")} ${rec.treePath.join(" > ")}`);
+      }
+      if (rec.skill.description) {
+        console.log(`      ${colors.muted(truncate3(rec.skill.description, 70))}`);
+      }
+      if (rec.skill.source) {
+        console.log(`      ${colors.dim("Source:")} ${rec.skill.source}`);
+      }
+      if (this.explain && rec.explanation) {
+        console.log(colors.dim("      Why this skill:"));
+        if (rec.explanation.matchedBecause.length > 0) {
+          console.log(`        ${colors.success("\u251C\u2500")} Matched: ${rec.explanation.matchedBecause.join(", ")}`);
+        }
+        if (rec.explanation.relevantFor.length > 0) {
+          console.log(`        ${colors.accent("\u251C\u2500")} Relevant for: ${rec.explanation.relevantFor.join(", ")}`);
+        }
+        if (rec.explanation.confidence) {
+          const confidenceColor = rec.explanation.confidence === "high" ? colors.success : rec.explanation.confidence === "medium" ? colors.warning : colors.muted;
+          console.log(`        ${colors.dim("\u2514\u2500")} Confidence: ${confidenceColor(rec.explanation.confidence)}`);
+        }
+      }
+      if (this.verbose && rec.reasons.length > 0) {
+        console.log(colors.dim("      Score breakdown:"));
+        for (const reason of rec.reasons.filter((r) => r.weight > 0)) {
+          console.log(`        ${colors.muted(symbols.stepActive)} ${reason.description} (+${reason.weight})`);
+        }
+        if (qualityScore !== null && qualityScore !== void 0) {
+          const grade = getQualityGradeFromScore(qualityScore);
+          console.log(`        ${colors.muted(symbols.stepActive)} Quality: ${qualityScore}/100 (${grade})`);
+        }
+      }
+      if (rec.warnings.length > 0) {
+        for (const warning of rec.warnings) {
+          console.log(`      ${colors.warning(symbols.warning)} ${warning}`);
+        }
+      }
+      console.log("");
+    }
+    console.log(colors.muted("Install with: skillkit install <source>"));
+    console.log(colors.muted("More details: skillkit recommend --explain --verbose"));
+  }
+  async handleHybridSearch(engine, query) {
+    if (!this.quiet && !this.json) {
+      header(`Hybrid Search: "${query}"`);
+    }
+    const s = !this.quiet && !this.json ? spinner2() : null;
+    s?.start("Initializing hybrid search...");
+    try {
+      await engine.initHybridSearch();
+      s?.message("Searching...");
+      const results = await engine.hybridSearch({
+        query,
+        limit: this.limit ? parseInt(this.limit, 10) : 10,
+        hybrid: true,
+        enableExpansion: this.expand,
+        enableReranking: this.rerank,
+        filters: {
+          minScore: this.minScore ? parseInt(this.minScore, 10) : void 0
+        }
+      });
+      s?.stop(`Found ${results.length} results`);
+      if (this.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return 0;
+      }
+      if (results.length === 0) {
+        warn(`No skills found matching "${query}"`);
+        return 0;
+      }
+      console.log("");
+      console.log(colors.bold(`Hybrid search results for "${query}" (${results.length} found):`));
+      if (this.expand && results[0]?.expandedTerms?.length) {
+        console.log(colors.muted(`  Expanded: ${results[0].expandedTerms.join(", ")}`));
+      }
+      console.log("");
+      for (const result of results) {
+        let relevanceColor;
+        if (result.relevance >= 70) {
+          relevanceColor = colors.success;
+        } else if (result.relevance >= 50) {
+          relevanceColor = colors.warning;
+        } else {
+          relevanceColor = colors.muted;
+        }
+        const relevanceBar = progressBar(result.relevance, 100, 10);
+        console.log(`  ${relevanceColor(`${result.relevance}%`)} ${colors.dim(relevanceBar)} ${colors.bold(result.skill.name)}`);
+        if (result.skill.description) {
+          console.log(`      ${colors.muted(truncate3(result.skill.description, 70))}`);
+        }
+        if (this.verbose) {
+          const scores = [];
+          if (typeof result.vectorSimilarity === "number") {
+            scores.push(`vector: ${(result.vectorSimilarity * 100).toFixed(0)}%`);
+          }
+          if (typeof result.keywordScore === "number") {
+            scores.push(`keyword: ${result.keywordScore.toFixed(0)}%`);
+          }
+          if (typeof result.rrfScore === "number") {
+            scores.push(`rrf: ${result.rrfScore.toFixed(3)}`);
+          }
+          if (scores.length > 0) {
+            console.log(`      ${colors.dim("Scores:")} ${scores.join(" | ")}`);
+          }
+        }
+        if (result.matchedTerms.length > 0) {
+          console.log(`      ${colors.dim("Matched:")} ${result.matchedTerms.join(", ")}`);
+        }
+        console.log("");
+      }
+      return 0;
+    } catch (err) {
+      s?.stop(colors.error("Hybrid search failed"));
+      console.log(colors.muted(err instanceof Error ? err.message : String(err)));
+      console.log(colors.muted("Falling back to standard search..."));
+      return this.handleSearch(engine, query);
+    }
+  }
+  async buildHybridIndex() {
+    if (!this.quiet) {
+      header("Build Hybrid Search Index");
+    }
+    const index = this.loadIndex();
+    if (!index || index.skills.length === 0) {
+      warn("No skill index found. Run --update first.");
+      return 1;
+    }
+    const s = spinner2();
+    s.start("Initializing...");
+    try {
+      const engine = new RecommendationEngine();
+      engine.loadIndex(index);
+      await engine.buildHybridIndex((progress) => {
+        const percentage = Math.round(progress.current / progress.total * 100);
+        s.message(`${progress.phase}: ${progress.message || ""} (${percentage}%)`);
+      });
+      s.stop(colors.success(`${symbols.success} Built hybrid index for ${index.skills.length} skills`));
+      console.log(colors.muted("  Index stored in: ~/.skillkit/search.db"));
+      console.log(colors.muted("  Use --hybrid flag for vector+keyword search\n"));
+      return 0;
+    } catch (err) {
+      s.stop(colors.error("Failed to build hybrid index"));
+      console.log(colors.muted(err instanceof Error ? err.message : String(err)));
+      return 1;
+    }
+  }
   handleSearch(engine, query) {
     if (!this.quiet && !this.json) {
       header(`Search: "${query}"`);
@@ -5506,12 +5790,12 @@ ${learning.title}
     }
     const outputPath = this.output || `.skillkit/exports/${skillName}/SKILL.md`;
     const { dirname: dirname7 } = await import("path");
-    const { existsSync: existsSync21, mkdirSync: mkdirSync9, writeFileSync: writeFileSync10 } = await import("fs");
+    const { existsSync: existsSync21, mkdirSync: mkdirSync10, writeFileSync: writeFileSync11 } = await import("fs");
     const outputDir = dirname7(outputPath);
     if (!existsSync21(outputDir)) {
-      mkdirSync9(outputDir, { recursive: true });
+      mkdirSync10(outputDir, { recursive: true });
     }
-    writeFileSync10(outputPath, skillContent, "utf-8");
+    writeFileSync11(outputPath, skillContent, "utf-8");
     console.log(chalk18.green(`\u2713 Exported learning as skill: ${skillName}`));
     console.log(chalk18.gray(`  Path: ${outputPath}`));
     return 0;
@@ -5527,8 +5811,8 @@ ${learning.title}
       return 1;
     }
     const { existsSync: existsSync21, readFileSync: readFileSync11 } = await import("fs");
-    const { resolve: resolve20 } = await import("path");
-    const fullPath = resolve20(inputPath);
+    const { resolve: resolve21 } = await import("path");
+    const fullPath = resolve21(inputPath);
     if (!existsSync21(fullPath)) {
       console.error(chalk18.red(`File not found: ${fullPath}`));
       return 1;
@@ -5786,7 +6070,7 @@ ${learning.title}
 // src/commands/settings.ts
 import { Command as Command27, Option as Option26 } from "clipanion";
 import chalk19 from "chalk";
-import { loadConfig as loadConfig3, saveConfig } from "@skillkit/core";
+import { loadConfig as loadConfig2, saveConfig } from "@skillkit/core";
 var VALID_AGENTS = [
   "claude-code",
   "cursor",
@@ -5846,7 +6130,7 @@ var SettingsCommand = class extends Command27 {
     description: "Reset all settings to defaults"
   });
   async execute() {
-    const config = loadConfig3(this.global);
+    const config = loadConfig2(this.global);
     if (this.reset) {
       const defaultConfig = {
         version: 1,
@@ -6608,14 +6892,14 @@ var TeamCommand = class extends Command29 {
     }
     const projectPath = process.cwd();
     const bundlePath = join12(projectPath, ".skillkit", "bundles", `${this.name}.json`);
-    const { existsSync: existsSync21, readFileSync: readFileSync11, writeFileSync: writeFileSync10 } = await import("fs");
+    const { existsSync: existsSync21, readFileSync: readFileSync11, writeFileSync: writeFileSync11 } = await import("fs");
     if (!existsSync21(bundlePath)) {
       this.context.stderr.write(chalk21.red(`Bundle "${this.name}" not found. Create it first with bundle-create.
 `));
       return 1;
     }
     const content = readFileSync11(bundlePath, "utf-8");
-    writeFileSync10(this.output, content, "utf-8");
+    writeFileSync11(this.output, content, "utf-8");
     this.context.stdout.write(chalk21.green(`\u2713 Bundle exported to: ${this.output}
 `));
     return 0;
@@ -6806,8 +7090,8 @@ var PluginCommand = class extends Command30 {
       if (!existsSync15(pluginsDir)) {
         mkdirSync7(pluginsDir, { recursive: true });
       }
-      const { statSync: statSync3 } = await import("fs");
-      const sourceStat = statSync3(resolvedSource);
+      const { statSync: statSync4 } = await import("fs");
+      const sourceStat = statSync4(resolvedSource);
       if (sourceStat.isDirectory()) {
         cpSync3(resolvedSource, targetDir, { recursive: true });
       } else {
@@ -9148,27 +9432,245 @@ Recent Errors (${stats.recentErrors.length}):`));
 };
 
 // src/commands/publish.ts
-import { existsSync as existsSync17, readFileSync as readFileSync9 } from "fs";
-import { join as join16, basename as basename4, dirname as dirname6 } from "path";
-import { execSync } from "child_process";
+import { existsSync as existsSync17, readFileSync as readFileSync9, mkdirSync as mkdirSync8, writeFileSync as writeFileSync8, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { join as join16, basename as basename4, dirname as dirname6, resolve as resolve18 } from "path";
 import chalk27 from "chalk";
 import { Command as Command37, Option as Option36 } from "clipanion";
+import { generateWellKnownIndex } from "@skillkit/core";
+function sanitizeSkillName(name) {
+  if (!name || typeof name !== "string") return null;
+  const base = basename4(name);
+  if (base !== name || name.includes("..") || name.includes("/") || name.includes("\\")) {
+    return null;
+  }
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    return null;
+  }
+  return name;
+}
 var PublishCommand = class extends Command37 {
   static paths = [["publish"]];
   static usage = Command37.Usage({
-    description: "Publish your skill to the SkillKit marketplace",
+    description: "Generate well-known skills structure for hosting",
+    details: `
+      This command generates the RFC 8615 well-known URI structure for hosting skills.
+
+      The output includes:
+      - .well-known/skills/index.json - Skill manifest for auto-discovery
+      - .well-known/skills/{skill-name}/SKILL.md - Individual skill files
+
+      Users can then install skills via: skillkit add https://your-domain.com
+    `,
+    examples: [
+      ["Generate from current directory", "$0 publish"],
+      ["Generate from specific path", "$0 publish ./my-skills"],
+      ["Generate to custom output directory", "$0 publish --output ./public"],
+      ["Preview without writing", "$0 publish --dry-run"]
+    ]
+  });
+  skillPath = Option36.String({ required: false, name: "path" });
+  output = Option36.String("--output,-o", {
+    description: "Output directory for well-known structure (default: current directory)"
+  });
+  dryRun = Option36.Boolean("--dry-run,-n", false, {
+    description: "Show what would be generated without writing files"
+  });
+  async execute() {
+    const basePath = this.skillPath || process.cwd();
+    const outputDir = this.output || basePath;
+    console.log(chalk27.cyan("Generating well-known skills structure...\n"));
+    const discoveredSkills = this.discoverSkills(basePath);
+    if (discoveredSkills.length === 0) {
+      console.error(chalk27.red("No skills found"));
+      console.error(chalk27.dim("Skills must contain a SKILL.md file with frontmatter"));
+      return 1;
+    }
+    console.log(chalk27.white(`Found ${discoveredSkills.length} skill(s):
+`));
+    const wellKnownSkills = [];
+    const validSkills = [];
+    for (const skill of discoveredSkills) {
+      const safeName = sanitizeSkillName(skill.name);
+      if (!safeName) {
+        console.log(chalk27.yellow(`  ${chalk27.yellow("\u26A0")} Skipping "${skill.name}" (invalid name - must be alphanumeric with hyphens/underscores)`));
+        continue;
+      }
+      const files = this.getSkillFiles(skill.path);
+      console.log(chalk27.dim(`  ${chalk27.green("\u25CF")} ${safeName}`));
+      console.log(chalk27.dim(`    Description: ${skill.description || "No description"}`));
+      console.log(chalk27.dim(`    Files: ${files.join(", ")}`));
+      validSkills.push({ name: skill.name, safeName, description: skill.description, path: skill.path });
+      wellKnownSkills.push({
+        name: safeName,
+        description: skill.description,
+        files
+      });
+    }
+    if (validSkills.length === 0) {
+      console.error(chalk27.red("\nNo valid skills to publish"));
+      return 1;
+    }
+    console.log("");
+    if (this.dryRun) {
+      console.log(chalk27.yellow("Dry run - not writing files\n"));
+      console.log(chalk27.white("Would generate:"));
+      console.log(chalk27.dim(`  ${outputDir}/.well-known/skills/index.json`));
+      for (const skill of wellKnownSkills) {
+        for (const file of skill.files) {
+          console.log(chalk27.dim(`  ${outputDir}/.well-known/skills/${skill.name}/${file}`));
+        }
+      }
+      console.log("");
+      console.log(chalk27.white("index.json preview:"));
+      console.log(JSON.stringify(generateWellKnownIndex(wellKnownSkills), null, 2));
+      return 0;
+    }
+    const wellKnownDir = join16(outputDir, ".well-known", "skills");
+    mkdirSync8(wellKnownDir, { recursive: true });
+    for (const skill of validSkills) {
+      const skillDir = join16(wellKnownDir, skill.safeName);
+      const resolvedSkillDir = resolve18(skillDir);
+      const resolvedWellKnownDir = resolve18(wellKnownDir);
+      if (!resolvedSkillDir.startsWith(resolvedWellKnownDir)) {
+        console.log(chalk27.yellow(`  Skipping "${skill.name}" (path traversal detected)`));
+        continue;
+      }
+      mkdirSync8(skillDir, { recursive: true });
+      const files = this.getSkillFiles(skill.path);
+      for (const file of files) {
+        const safeFile = basename4(file);
+        const sourcePath = join16(skill.path, file);
+        const destPath = join16(skillDir, safeFile);
+        const content = readFileSync9(sourcePath, "utf-8");
+        writeFileSync8(destPath, content);
+      }
+    }
+    const index = generateWellKnownIndex(wellKnownSkills);
+    writeFileSync8(join16(wellKnownDir, "index.json"), JSON.stringify(index, null, 2));
+    console.log(chalk27.green("Generated well-known structure:\n"));
+    console.log(chalk27.dim(`  ${wellKnownDir}/index.json`));
+    for (const skill of wellKnownSkills) {
+      console.log(chalk27.dim(`  ${wellKnownDir}/${skill.name}/`));
+    }
+    console.log("");
+    console.log(chalk27.cyan("Next steps:"));
+    console.log(chalk27.dim("  1. Deploy the .well-known directory to your web server"));
+    console.log(chalk27.dim("  2. Users can install via: skillkit add https://your-domain.com"));
+    console.log(chalk27.dim("  3. Skills auto-discovered from /.well-known/skills/index.json"));
+    return 0;
+  }
+  discoverSkills(basePath) {
+    const skills = [];
+    const skillMdPath = join16(basePath, "SKILL.md");
+    if (existsSync17(skillMdPath)) {
+      const content = readFileSync9(skillMdPath, "utf-8");
+      const frontmatter = this.parseFrontmatter(content);
+      skills.push({
+        name: frontmatter.name || basename4(basePath),
+        description: frontmatter.description,
+        path: basePath
+      });
+      return skills;
+    }
+    const searchDirs = [
+      basePath,
+      join16(basePath, "skills"),
+      join16(basePath, ".claude", "skills")
+    ];
+    for (const searchDir of searchDirs) {
+      if (!existsSync17(searchDir)) continue;
+      const entries = readdirSync3(searchDir);
+      for (const entry of entries) {
+        const entryPath = join16(searchDir, entry);
+        if (!statSync3(entryPath).isDirectory()) continue;
+        const entrySkillMd = join16(entryPath, "SKILL.md");
+        if (existsSync17(entrySkillMd)) {
+          const content = readFileSync9(entrySkillMd, "utf-8");
+          const frontmatter = this.parseFrontmatter(content);
+          skills.push({
+            name: frontmatter.name || entry,
+            description: frontmatter.description,
+            path: entryPath
+          });
+        }
+      }
+    }
+    return skills;
+  }
+  getSkillFiles(skillPath) {
+    const files = [];
+    const entries = readdirSync3(skillPath);
+    for (const entry of entries) {
+      const entryPath = join16(skillPath, entry);
+      if (statSync3(entryPath).isFile()) {
+        if (entry.startsWith(".") || entry === ".skillkit-metadata.json") continue;
+        files.push(entry);
+      }
+    }
+    if (!files.includes("SKILL.md")) {
+      files.unshift("SKILL.md");
+    }
+    return files;
+  }
+  parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) return {};
+    const frontmatter = {};
+    const lines = match[1].split(/\r?\n/);
+    let inTagsList = false;
+    for (const line of lines) {
+      if (inTagsList) {
+        const tagMatch = line.match(/^\s*-\s*(.+)$/);
+        if (tagMatch) {
+          frontmatter.tags ??= [];
+          frontmatter.tags.push(tagMatch[1].trim().replace(/^["']|["']$/g, ""));
+          continue;
+        }
+        if (line.trim() === "") continue;
+        inTagsList = false;
+      }
+      const colonIdx = line.indexOf(":");
+      if (colonIdx === -1) continue;
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      switch (key) {
+        case "name":
+          frontmatter.name = value.replace(/^["']|["']$/g, "");
+          break;
+        case "description":
+          frontmatter.description = value.replace(/^["']|["']$/g, "");
+          break;
+        case "version":
+          frontmatter.version = value.replace(/^["']|["']$/g, "");
+          break;
+        case "tags":
+          if (value.startsWith("[")) {
+            frontmatter.tags = value.slice(1, -1).split(",").map((t) => t.trim().replace(/^["']|["']$/g, "")).filter((t) => t.length > 0);
+          } else if (value === "") {
+            inTagsList = true;
+            frontmatter.tags = [];
+          }
+          break;
+      }
+    }
+    return frontmatter;
+  }
+};
+var PublishSubmitCommand = class extends Command37 {
+  static paths = [["publish", "submit"]];
+  static usage = Command37.Usage({
+    description: "Submit skill to SkillKit marketplace (requires review)",
     examples: [
-      ["Publish skill from current directory", "$0 publish"],
-      ["Publish skill from specific path", "$0 publish ./my-skill"],
-      ["Publish with custom name", "$0 publish --name my-awesome-skill"]
+      ["Submit skill from current directory", "$0 publish submit"],
+      ["Submit with custom name", "$0 publish submit --name my-skill"]
     ]
   });
   skillPath = Option36.String({ required: false, name: "path" });
   name = Option36.String("--name,-n", {
-    description: "Custom skill name (default: parsed from SKILL.md)"
+    description: "Custom skill name"
   });
   dryRun = Option36.Boolean("--dry-run", false, {
-    description: "Show what would be published without actually publishing"
+    description: "Show what would be submitted"
   });
   async execute() {
     const skillPath = this.skillPath || process.cwd();
@@ -9176,10 +9678,9 @@ var PublishCommand = class extends Command37 {
     if (!skillMdPath) {
       console.error(chalk27.red("No SKILL.md found"));
       console.error(chalk27.dim("Run this command from a directory containing SKILL.md"));
-      console.error(chalk27.dim("Or specify the path: skillkit publish ./path/to/skill"));
       return 1;
     }
-    console.log(chalk27.cyan("Publishing skill to SkillKit marketplace...\n"));
+    console.log(chalk27.cyan("Submitting skill to SkillKit marketplace...\n"));
     const content = readFileSync9(skillMdPath, "utf-8");
     const frontmatter = this.parseFrontmatter(content);
     const skillName = this.name || frontmatter.name || basename4(dirname6(skillMdPath));
@@ -9198,9 +9699,9 @@ var PublishCommand = class extends Command37 {
     const skillEntry = {
       id: `${repoInfo.owner}/${repoInfo.repo}/${skillSlug}`,
       name: this.formatName(skillName),
-      description: frontmatter.description || `Best practices and patterns for ${this.formatName(skillName)}`,
+      description: frontmatter.description || `Best practices for ${this.formatName(skillName)}`,
       source: `${repoInfo.owner}/${repoInfo.repo}`,
-      tags: frontmatter.tags || this.inferTags(skillName, frontmatter.description || "")
+      tags: frontmatter.tags || ["general"]
     };
     console.log(chalk27.white("Skill details:"));
     console.log(chalk27.dim(`  ID: ${skillEntry.id}`));
@@ -9210,8 +9711,7 @@ var PublishCommand = class extends Command37 {
     console.log(chalk27.dim(`  Tags: ${skillEntry.tags.join(", ")}`));
     console.log();
     if (this.dryRun) {
-      console.log(chalk27.yellow("Dry run - not publishing"));
-      console.log(chalk27.dim("JSON entry that would be added:"));
+      console.log(chalk27.yellow("Dry run - not submitting"));
       console.log(JSON.stringify(skillEntry, null, 2));
       return 0;
     }
@@ -9221,20 +9721,16 @@ var PublishCommand = class extends Command37 {
     const issueUrl = `https://github.com/rohitg00/skillkit/issues/new?title=${issueTitle}&body=${issueBodyEncoded}&labels=skill-submission,publish`;
     console.log(chalk27.green("Opening GitHub to submit your skill...\n"));
     try {
+      const { execSync } = await import("child_process");
       const openCmd = process.platform === "darwin" ? `open "${issueUrl}"` : process.platform === "win32" ? `cmd /c start "" "${issueUrl}"` : `xdg-open "${issueUrl}"`;
       execSync(openCmd, { stdio: "ignore" });
       console.log(chalk27.green("GitHub issue page opened!"));
-      console.log(chalk27.dim("Review and submit the issue to publish your skill."));
+      console.log(chalk27.dim("Review and submit the issue."));
     } catch {
       console.log(chalk27.yellow("Could not open browser automatically."));
       console.log(chalk27.dim("Please open this URL manually:\n"));
       console.log(chalk27.cyan(issueUrl));
     }
-    console.log();
-    console.log(chalk27.cyan("Next steps:"));
-    console.log(chalk27.dim("  1. Review the skill details in the GitHub issue"));
-    console.log(chalk27.dim("  2. Submit the issue"));
-    console.log(chalk27.dim("  3. A maintainer will review and add your skill"));
     return 0;
   }
   findSkillMd(basePath) {
@@ -9247,8 +9743,7 @@ var PublishCommand = class extends Command37 {
     }
     const locations = [
       join16(basePath, "skills", "SKILL.md"),
-      join16(basePath, ".claude", "skills", "SKILL.md"),
-      join16(basePath, ".cursor", "skills", "SKILL.md")
+      join16(basePath, ".claude", "skills", "SKILL.md")
     ];
     for (const loc of locations) {
       if (existsSync17(loc)) {
@@ -9262,18 +9757,7 @@ var PublishCommand = class extends Command37 {
     if (!match) return {};
     const frontmatter = {};
     const lines = match[1].split(/\r?\n/);
-    let inTagsList = false;
     for (const line of lines) {
-      if (inTagsList) {
-        const tagMatch = line.match(/^\s*-\s*(.+)$/);
-        if (tagMatch) {
-          frontmatter.tags ??= [];
-          frontmatter.tags.push(tagMatch[1].trim().replace(/^["']|["']$/g, ""));
-          continue;
-        }
-        if (line.trim() === "") continue;
-        inTagsList = false;
-      }
       const colonIdx = line.indexOf(":");
       if (colonIdx === -1) continue;
       const key = line.slice(0, colonIdx).trim();
@@ -9291,9 +9775,6 @@ var PublishCommand = class extends Command37 {
         case "tags":
           if (value.startsWith("[")) {
             frontmatter.tags = value.slice(1, -1).split(",").map((t) => t.trim().replace(/^["']|["']$/g, "")).filter((t) => t.length > 0);
-          } else if (value === "") {
-            inTagsList = true;
-            frontmatter.tags = [];
           }
           break;
       }
@@ -9305,6 +9786,7 @@ var PublishCommand = class extends Command37 {
   }
   getRepoInfo(dir) {
     try {
+      const { execSync } = __require("child_process");
       const remote = execSync("git remote get-url origin", {
         cwd: dir,
         encoding: "utf-8",
@@ -9321,27 +9803,6 @@ var PublishCommand = class extends Command37 {
   formatName(name) {
     return name.split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
   }
-  inferTags(name, description) {
-    const tags = [];
-    const text3 = `${name} ${description}`.toLowerCase();
-    const tagMap = {
-      react: ["react", "jsx", "tsx"],
-      typescript: ["typescript", "ts"],
-      nextjs: ["next", "nextjs"],
-      testing: ["test", "jest", "vitest"],
-      mobile: ["mobile", "react-native", "expo"],
-      backend: ["backend", "api", "server"],
-      database: ["database", "postgres", "mysql", "supabase"],
-      frontend: ["frontend", "ui", "design"],
-      devops: ["devops", "ci", "cd", "docker"]
-    };
-    for (const [tag, keywords] of Object.entries(tagMap)) {
-      if (keywords.some((k) => text3.includes(k))) {
-        tags.push(tag);
-      }
-    }
-    return tags.length > 0 ? tags : ["general"];
-  }
   createIssueBody(skill) {
     return `## Publish Skill Request
 
@@ -9364,15 +9825,15 @@ ${JSON.stringify(skill, null, 2)}
 - [ ] Tags are appropriate
 
 ---
-Submitted via \`skillkit publish\``;
+Submitted via \`skillkit publish submit\``;
   }
 };
 
 // src/commands/agent.ts
 import chalk28 from "chalk";
 import { Command as Command38, Option as Option37 } from "clipanion";
-import { existsSync as existsSync18, mkdirSync as mkdirSync8, writeFileSync as writeFileSync8 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync9, writeFileSync as writeFileSync9 } from "fs";
+import { join as join17, basename as basename5 } from "path";
 import { homedir as homedir3 } from "os";
 import {
   findAllAgents,
@@ -9381,7 +9842,10 @@ import {
   discoverAgentsFromPath,
   validateAgent,
   translateAgent,
-  getAgentTargetDirectory
+  getAgentTargetDirectory,
+  discoverSkills as discoverSkills2,
+  readSkillContent as readSkillContent2,
+  generateSubagentFromSkill
 } from "@skillkit/core";
 import {
   getBundledAgents,
@@ -9402,17 +9866,19 @@ var AgentCommand = class extends Command38 {
       that can be invoked with @mentions or the --agent flag.
 
       Sub-commands:
-        agent list      - List all installed agents
-        agent show      - Show agent details
-        agent create    - Create a new agent
-        agent translate - Translate agents between formats
-        agent sync      - Sync agents to target AI agent
-        agent validate  - Validate agent definitions
+        agent list       - List all installed agents
+        agent show       - Show agent details
+        agent create     - Create a new agent
+        agent from-skill - Convert a skill to a subagent
+        agent translate  - Translate agents between formats
+        agent sync       - Sync agents to target AI agent
+        agent validate   - Validate agent definitions
     `,
     examples: [
       ["List all agents", "$0 agent list"],
       ["Show agent details", "$0 agent show architect"],
       ["Create new agent", "$0 agent create security-reviewer"],
+      ["Convert skill to subagent", "$0 agent from-skill code-simplifier"],
       ["Translate to Cursor format", "$0 agent translate --to cursor"],
       ["Sync agents", "$0 agent sync --agent claude-code"]
     ]
@@ -9422,6 +9888,7 @@ var AgentCommand = class extends Command38 {
     console.log("  agent list              List all installed agents");
     console.log("  agent show <name>       Show agent details");
     console.log("  agent create <name>     Create a new agent");
+    console.log("  agent from-skill <name> Convert a skill to a subagent");
     console.log("  agent translate         Translate agents between formats");
     console.log("  agent sync              Sync agents to target AI agent");
     console.log("  agent validate [path]   Validate agent definitions");
@@ -9595,7 +10062,7 @@ var AgentCreateCommand = class extends Command38 {
       targetDir = join17(process.cwd(), ".claude", "agents");
     }
     if (!existsSync18(targetDir)) {
-      mkdirSync8(targetDir, { recursive: true });
+      mkdirSync9(targetDir, { recursive: true });
     }
     const agentPath = join17(targetDir, `${this.name}.md`);
     if (existsSync18(agentPath)) {
@@ -9604,7 +10071,7 @@ var AgentCreateCommand = class extends Command38 {
     }
     const description = this.description || `${this.name} agent`;
     const content = generateAgentTemplate(this.name, description, this.model);
-    writeFileSync8(agentPath, content);
+    writeFileSync9(agentPath, content);
     console.log(chalk28.green(`Created agent: ${agentPath}`));
     console.log();
     console.log(chalk28.dim("Edit the file to customize the agent system prompt."));
@@ -9713,9 +10180,9 @@ var AgentTranslateCommand = class extends Command38 {
           }
         } else {
           if (!existsSync18(outputDir)) {
-            mkdirSync8(outputDir, { recursive: true });
+            mkdirSync9(outputDir, { recursive: true });
           }
-          writeFileSync8(outputPath, result.content);
+          writeFileSync9(outputPath, result.content);
           console.log(chalk28.green(`\u2713 ${agent.name} \u2192 ${outputPath}`));
         }
         successCount++;
@@ -9759,13 +10226,13 @@ var AgentSyncCommand = class extends Command38 {
       const outputDir = getAgentTargetDirectory(process.cwd(), targetAgent);
       console.log(chalk28.blue(`\u2192 ${targetAgent} (${outputDir})`));
       if (!existsSync18(outputDir)) {
-        mkdirSync8(outputDir, { recursive: true });
+        mkdirSync9(outputDir, { recursive: true });
       }
       for (const agent of agents) {
         const result = translateAgent(agent, targetAgent);
         if (result.success) {
           const outputPath = join17(outputDir, result.filename);
-          writeFileSync8(outputPath, result.content);
+          writeFileSync9(outputPath, result.content);
           console.log(chalk28.green(`  \u2713 ${agent.name}`));
         } else {
           console.log(chalk28.red(`  \u2717 ${agent.name}`));
@@ -10039,9 +10506,148 @@ var AgentAvailableCommand = class extends Command38 {
     return 0;
   }
 };
+var AgentFromSkillCommand = class extends Command38 {
+  static paths = [["agent", "from-skill"]];
+  static usage = Command38.Usage({
+    description: "Convert a skill into a Claude Code subagent",
+    details: `
+      Converts a SkillKit skill into a Claude Code native subagent format.
+      The generated .md file can be used with @mentions in Claude Code.
+
+      By default, the subagent references the skill (skills: [skill-name]).
+      Use --inline to embed the full skill content in the system prompt.
+    `,
+    examples: [
+      ["Convert skill to subagent", "$0 agent from-skill code-simplifier"],
+      ["Create global subagent", "$0 agent from-skill code-simplifier --global"],
+      ["Embed skill content inline", "$0 agent from-skill code-simplifier --inline"],
+      ["Set model for subagent", "$0 agent from-skill code-simplifier --model opus"],
+      ["Preview without writing", "$0 agent from-skill code-simplifier --dry-run"]
+    ]
+  });
+  skillName = Option37.String({ required: true });
+  inline = Option37.Boolean("--inline,-i", false, {
+    description: "Embed full skill content in system prompt"
+  });
+  model = Option37.String("--model,-m", {
+    description: "Model to use (sonnet, opus, haiku, inherit)"
+  });
+  permission = Option37.String("--permission,-p", {
+    description: "Permission mode (default, plan, auto-edit, full-auto, bypassPermissions)"
+  });
+  global = Option37.Boolean("--global,-g", false, {
+    description: "Create in ~/.claude/agents/ instead of .claude/agents/"
+  });
+  output = Option37.String("--output,-o", {
+    description: "Custom output filename (without .md)"
+  });
+  dryRun = Option37.Boolean("--dry-run,-n", false, {
+    description: "Preview without writing files"
+  });
+  async execute() {
+    const skills = discoverSkills2(process.cwd());
+    const skill = skills.find((s) => s.name === this.skillName);
+    if (!skill) {
+      console.log(chalk28.red(`Skill not found: ${this.skillName}`));
+      console.log(chalk28.dim("Available skills:"));
+      for (const s of skills.slice(0, 10)) {
+        console.log(chalk28.dim(`  - ${s.name}`));
+      }
+      if (skills.length > 10) {
+        console.log(chalk28.dim(`  ... and ${skills.length - 10} more`));
+      }
+      return 1;
+    }
+    const skillContent = readSkillContent2(skill.path);
+    if (!skillContent) {
+      console.log(chalk28.red(`Could not read skill content: ${skill.path}`));
+      return 1;
+    }
+    const options = {
+      inline: this.inline
+    };
+    if (this.model) {
+      const validModels = ["sonnet", "opus", "haiku", "inherit"];
+      if (!validModels.includes(this.model)) {
+        console.log(chalk28.red(`Invalid model: ${this.model}`));
+        console.log(chalk28.dim(`Valid options: ${validModels.join(", ")}`));
+        return 1;
+      }
+      options.model = this.model;
+    }
+    if (this.permission) {
+      const validModes = ["default", "plan", "auto-edit", "full-auto", "bypassPermissions"];
+      if (!validModes.includes(this.permission)) {
+        console.log(chalk28.red(`Invalid permission mode: ${this.permission}`));
+        console.log(chalk28.dim(`Valid options: ${validModes.join(", ")}`));
+        return 1;
+      }
+      options.permissionMode = this.permission;
+    }
+    const content = generateSubagentFromSkill(skill, skillContent, options);
+    const targetDir = this.global ? join17(homedir3(), ".claude", "agents") : join17(process.cwd(), ".claude", "agents");
+    let filename;
+    if (this.output) {
+      const sanitized = sanitizeFilename(this.output);
+      if (!sanitized) {
+        console.log(chalk28.red(`Invalid output filename: ${this.output}`));
+        console.log(chalk28.dim("Filename must contain only alphanumeric characters, hyphens, and underscores"));
+        return 1;
+      }
+      filename = `${sanitized}.md`;
+    } else {
+      const sanitized = sanitizeFilename(skill.name);
+      if (!sanitized) {
+        console.log(chalk28.red(`Invalid skill name for filename: ${skill.name}`));
+        console.log(chalk28.dim("Skill name must contain only alphanumeric characters, hyphens, and underscores"));
+        return 1;
+      }
+      filename = `${sanitized}.md`;
+    }
+    const outputPath = join17(targetDir, filename);
+    if (this.dryRun) {
+      console.log(chalk28.cyan("Preview (dry run):\n"));
+      console.log(chalk28.dim(`Would write to: ${outputPath}`));
+      console.log(chalk28.dim("\u2500".repeat(50)));
+      console.log(content);
+      console.log(chalk28.dim("\u2500".repeat(50)));
+      return 0;
+    }
+    if (!existsSync18(targetDir)) {
+      mkdirSync9(targetDir, { recursive: true });
+    }
+    if (existsSync18(outputPath)) {
+      console.log(chalk28.yellow(`Overwriting existing file: ${outputPath}`));
+    }
+    writeFileSync9(outputPath, content);
+    console.log(chalk28.green(`Created subagent: ${outputPath}`));
+    console.log();
+    console.log(chalk28.dim(`Invoke with: @${skill.name}`));
+    if (!this.inline) {
+      console.log(chalk28.dim(`Skills referenced: ${skill.name}`));
+    } else {
+      console.log(chalk28.dim("Skill content embedded inline"));
+    }
+    return 0;
+  }
+};
 function formatCategoryName(category) {
   return category.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
+function sanitizeFilename(input) {
+  const base = basename5(input);
+  const stem = base.replace(/\.md$/i, "");
+  if (!stem || stem.startsWith(".") || stem.startsWith("-")) {
+    return null;
+  }
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(stem)) {
+    return null;
+  }
+  if (stem.length > 64) {
+    return null;
+  }
+  return stem;
+}
 
 // src/commands/check.ts
 init_helpers();
@@ -10129,9 +10735,9 @@ var CheckCommand = class extends Command39 {
           const sourceSkillMd = join18(localPath, "SKILL.md");
           const installedSkillMd = join18(skill.path, "SKILL.md");
           if (existsSync19(sourceSkillMd) && existsSync19(installedSkillMd)) {
-            const { statSync: statSync3 } = await import("fs");
-            const sourceTime = statSync3(sourceSkillMd).mtime;
-            const installedTime = statSync3(installedSkillMd).mtime;
+            const { statSync: statSync4 } = await import("fs");
+            const sourceTime = statSync4(sourceSkillMd).mtime;
+            const installedTime = statSync4(installedSkillMd).mtime;
             if (sourceTime > installedTime) {
               results.push({ name: skill.name, hasUpdate: true });
               updatesAvailable++;
@@ -10214,8 +10820,8 @@ import { Command as Command40, Option as Option39 } from "clipanion";
 var skills_default = {
   $schema: "./schema.json",
   version: 1,
-  updatedAt: "2026-01-26",
-  totalSkills: 15064,
+  updatedAt: "2026-02-02",
+  totalSkills: 15065,
   curatedCollections: 31,
   skills: [
     {
@@ -43325,6 +43931,23 @@ var skills_default = {
         "k8s"
       ]
     },
+    {
+      id: "rohitg00/beautiful-mermaid/beautiful-mermaid",
+      name: "Beautiful Mermaid",
+      description: "Render Mermaid diagrams as beautiful SVGs or ASCII art. 5 diagram types, 15 themes, Shiki integration, zero DOM dependencies.",
+      source: "rohitg00/beautiful-mermaid",
+      tags: [
+        "mermaid",
+        "diagrams",
+        "visualization",
+        "flowchart",
+        "sequence",
+        "uml",
+        "ascii",
+        "svg",
+        "themes"
+      ]
+    },
     {
       id: "itsmostafa/aws-agent-skills/cognito",
       name: "Cognito",
@@ -136210,7 +136833,7 @@ var ManifestGenerateCommand = class extends Command41 {
 
 // src/commands/primer.ts
 import { Command as Command42, Option as Option41 } from "clipanion";
-import { resolve as resolve18 } from "path";
+import { resolve as resolve19 } from "path";
 import chalk29 from "chalk";
 import {
   AgentType as AgentTypeSchema,
@@ -136278,7 +136901,7 @@ var PrimerCommand = class extends Command42 {
     description: "Number of commits to analyze for learning (default: 100)"
   });
   async execute() {
-    const projectPath = resolve18(this.directory || process.cwd());
+    const projectPath = resolve19(this.directory || process.cwd());
     if (this.analyzeOnly) {
       return this.runAnalysis(projectPath);
     }
@@ -136347,7 +136970,7 @@ var PrimerCommand = class extends Command42 {
       const result = generatePrimer(projectPath, {
         agents,
         allAgents: this.allAgents,
-        outputDir: this.output ? resolve18(this.output) : void 0,
+        outputDir: this.output ? resolve19(this.output) : void 0,
         dryRun: this.dryRun,
         verbose: this.verbose,
         includeExamples: this.includeExamples
@@ -137558,7 +138181,7 @@ Sent Messages (${messages.length})
 
 // src/commands/learn.ts
 import { Command as Command45, Option as Option44 } from "clipanion";
-import { resolve as resolve19 } from "path";
+import { resolve as resolve20 } from "path";
 import chalk32 from "chalk";
 import {
   analyzeGitHistory as analyzeGitHistory2,
@@ -137578,7 +138201,7 @@ import {
   getPatternStats,
   clusterPatterns
 } from "@skillkit/core";
-import { writeFileSync as writeFileSync9, readFileSync as readFileSync10, existsSync as existsSync20 } from "fs";
+import { writeFileSync as writeFileSync10, readFileSync as readFileSync10, existsSync as existsSync20 } from "fs";
 var LearnCommand = class extends Command45 {
   static paths = [["learn"]];
   static usage = Command45.Usage({
@@ -137615,7 +138238,7 @@ var LearnCommand = class extends Command45 {
     description: "Project directory to analyze (default: current directory)"
   });
   async execute() {
-    const projectPath = resolve19(this.directory || process.cwd());
+    const projectPath = resolve20(this.directory || process.cwd());
     if (this.show) {
       return this.showPatterns();
     }
@@ -137862,7 +138485,7 @@ var PatternExportCommand = class extends Command45 {
       content = exportPatternsAsJson(patterns);
     }
     if (this.output) {
-      writeFileSync9(this.output, content);
+      writeFileSync10(this.output, content);
       console.log(chalk32.green(`\u2713 Exported ${patterns.length} patterns to ${this.output}`));
     } else {
       console.log(content);
@@ -138584,6 +139207,208 @@ function formatCategoryName2(category) {
   return category.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 
+// src/commands/tree.ts
+init_onboarding();
+import { Command as Command49, Option as Option48 } from "clipanion";
+import { join as join19 } from "path";
+import { homedir as homedir4 } from "os";
+import {
+  loadIndex as loadIndexFromCache3,
+  generateSkillTree,
+  saveTree,
+  loadTree
+} from "@skillkit/core";
+var TREE_PATH = join19(homedir4(), ".skillkit", "skill-tree.json");
+var TreeCommand = class extends Command49 {
+  static paths = [["tree"]];
+  static usage = Command49.Usage({
+    description: "Browse skills in a hierarchical tree structure",
+    details: `
+      The tree command displays skills organized in a hierarchical taxonomy.
+      Navigate through categories like Development, Testing, DevOps, AI/ML, etc.
+
+      Features:
+      - Visual tree structure of all skills
+      - Filter by category path (e.g., "Frontend > React")
+      - Generate tree from skill index
+      - Export to markdown format
+    `,
+    examples: [
+      ["Show full tree", "$0 tree"],
+      ["Show specific category", "$0 tree Frontend"],
+      ["Show subcategory", '$0 tree "Frontend > React"'],
+      ["Limit depth", "$0 tree --depth 2"],
+      ["Generate/update tree", "$0 tree --generate"],
+      ["Export to markdown", "$0 tree --markdown"],
+      ["Show tree stats", "$0 tree --stats"]
+    ]
+  });
+  treePath = Option48.String({ required: false });
+  depth = Option48.String("--depth,-d", {
+    description: "Maximum depth to display"
+  });
+  generate = Option48.Boolean("--generate,-g", false, {
+    description: "Generate/update tree from skill index"
+  });
+  markdown = Option48.Boolean("--markdown,-m", false, {
+    description: "Output in markdown format"
+  });
+  stats = Option48.Boolean("--stats,-s", false, {
+    description: "Show tree statistics"
+  });
+  json = Option48.Boolean("--json,-j", false, {
+    description: "Output in JSON format"
+  });
+  quiet = Option48.Boolean("--quiet,-q", false, {
+    description: "Minimal output"
+  });
+  async execute() {
+    if (this.generate) {
+      return await this.generateTree();
+    }
+    const tree = this.loadOrGenerateTree();
+    if (!tree) {
+      warn('No skill tree found. Run "skillkit tree --generate" first.');
+      return 1;
+    }
+    if (this.stats) {
+      return this.showStats(tree);
+    }
+    if (this.json) {
+      console.log(JSON.stringify(tree, null, 2));
+      return 0;
+    }
+    if (this.markdown) {
+      const { treeToMarkdown } = await import("@skillkit/core");
+      console.log(treeToMarkdown(tree));
+      return 0;
+    }
+    return this.displayTree(tree);
+  }
+  async generateTree() {
+    if (!this.quiet) {
+      header("Generate Skill Tree");
+    }
+    const index = loadIndexFromCache3();
+    if (!index || index.skills.length === 0) {
+      warn('No skill index found. Run "skillkit recommend --update" first.');
+      return 1;
+    }
+    const s = spinner2();
+    s.start("Generating skill tree...");
+    try {
+      const tree = generateSkillTree(index.skills);
+      saveTree(tree, TREE_PATH);
+      s.stop(`Generated tree with ${tree.totalCategories} categories`);
+      console.log("");
+      console.log(colors.success(`${symbols.success} Tree generated successfully`));
+      console.log(colors.muted(`  Total skills: ${tree.totalSkills}`));
+      console.log(colors.muted(`  Categories: ${tree.totalCategories}`));
+      console.log(colors.muted(`  Max depth: ${tree.maxDepth}`));
+      console.log(colors.muted(`  Saved to: ${TREE_PATH}`));
+      console.log("");
+      return 0;
+    } catch (err) {
+      s.stop(colors.error("Failed to generate tree"));
+      console.log(colors.muted(err instanceof Error ? err.message : String(err)));
+      return 1;
+    }
+  }
+  loadOrGenerateTree() {
+    let tree = loadTree(TREE_PATH);
+    if (!tree) {
+      const index = loadIndexFromCache3();
+      if (index && index.skills.length > 0) {
+        tree = generateSkillTree(index.skills);
+        saveTree(tree, TREE_PATH);
+      }
+    }
+    return tree;
+  }
+  showStats(tree) {
+    if (!this.quiet) {
+      header("Skill Tree Statistics");
+    }
+    console.log("");
+    console.log(colors.bold("Overview:"));
+    console.log(`  Total Skills: ${colors.accent(String(tree.totalSkills))}`);
+    console.log(`  Categories: ${colors.accent(String(tree.totalCategories))}`);
+    console.log(`  Max Depth: ${colors.accent(String(tree.maxDepth))}`);
+    console.log(`  Generated: ${colors.muted(tree.generatedAt)}`);
+    console.log("");
+    console.log(colors.bold("Top-Level Categories:"));
+    for (const child of tree.rootNode.children) {
+      const percentage = tree.totalSkills > 0 ? (child.skillCount / tree.totalSkills * 100).toFixed(1) : "0.0";
+      console.log(
+        `  ${colors.accent(child.name.padEnd(15))} ${String(child.skillCount).padStart(6)} skills (${percentage}%)`
+      );
+      if (child.children.length > 0) {
+        const subcats = child.children.sort((a, b) => b.skillCount - a.skillCount).slice(0, 3).map((c) => `${c.name} (${c.skillCount})`).join(", ");
+        console.log(`    ${colors.muted(subcats)}`);
+      }
+    }
+    console.log("");
+    return 0;
+  }
+  displayTree(tree) {
+    if (!this.quiet) {
+      header("Skill Tree");
+      console.log(colors.muted(`${tree.totalSkills} skills in ${tree.totalCategories} categories`));
+      console.log("");
+    }
+    let targetNode = tree.rootNode;
+    if (this.treePath) {
+      const segments = this.treePath.split(">").map((s) => s.trim());
+      let current = tree.rootNode;
+      for (const segment of segments) {
+        const child = current.children.find(
+          (c) => c.name.toLowerCase() === segment.toLowerCase()
+        );
+        if (!child) {
+          warn(`Category not found: ${segment}`);
+          console.log(colors.muted(`Available categories: ${current.children.map((c) => c.name).join(", ")}`));
+          return 1;
+        }
+        current = child;
+      }
+      targetNode = current;
+    }
+    let maxDepth = this.depth ? parseInt(this.depth, 10) : 3;
+    if (Number.isNaN(maxDepth) || maxDepth < 0) {
+      warn("Invalid depth value. Using default depth of 3.");
+      maxDepth = 3;
+    }
+    this.renderNode(targetNode, "", true, 0, maxDepth);
+    console.log("");
+    console.log(colors.muted('Navigate: skillkit tree "Category > Subcategory"'));
+    console.log(colors.muted("Generate: skillkit tree --generate"));
+    return 0;
+  }
+  renderNode(node, prefix, isLast, depth, maxDepth) {
+    if (depth > maxDepth) return;
+    const connector = depth === 0 ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const icon = node.children.length > 0 ? "\u{1F4C1} " : "\u{1F4C4} ";
+    const skillInfo = node.skillCount > 0 ? colors.muted(` (${node.skillCount})`) : "";
+    const nameColor = depth === 0 ? colors.bold : depth === 1 ? colors.accent : colors.dim;
+    console.log(`${prefix}${connector}${icon}${nameColor(node.name)}${skillInfo}`);
+    if (depth === maxDepth && node.skills.length > 0 && node.skills.length <= 5) {
+      const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+      for (const skill of node.skills) {
+        console.log(`${childPrefix}  \u2022 ${colors.muted(skill)}`);
+      }
+    }
+    const newPrefix = prefix + (depth === 0 ? "" : isLast ? "    " : "\u2502   ");
+    if (depth < maxDepth) {
+      node.children.forEach((child, index) => {
+        const childIsLast = index === node.children.length - 1;
+        this.renderNode(child, newPrefix, childIsLast, depth + 1, maxDepth);
+      });
+    } else if (node.children.length > 0) {
+      console.log(`${newPrefix}    ${colors.muted(`... ${node.children.length} more subcategories`)}`);
+    }
+  }
+};
+
 // src/index.ts
 init_helpers();
 export {
@@ -138591,6 +139416,7 @@ export {
   AgentAvailableCommand,
   AgentCommand,
   AgentCreateCommand,
+  AgentFromSkillCommand,
   AgentInstallCommand,
   AgentListCommand,
   AgentShowCommand,
@@ -138651,6 +139477,7 @@ export {
   ProfileListCommand,
   ProfileRemoveCommand,
   PublishCommand,
+  PublishSubmitCommand,
   ReadCommand,
   RecommendCommand,
   RemoveCommand,
@@ -138670,6 +139497,7 @@ export {
   TeamCommand,
   TestCommand,
   TranslateCommand,
+  TreeCommand,
   UICommand,
   UpdateCommand,
   ValidateCommand,