skild 0.6.0 → 0.7.0

package/README.md

@@ -32,6 +32,9 @@ skild uninstall pdf -t codex --local
 
 # Create a new Skill
 skild init my-skill
+
+# Extract GitHub skills
+skild extract-github-skills https://github.com/ComposioHQ/awesome-claude-skills
 ```
 
 Full user guide (CLI + registry + console):

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk16 from "chalk";
+import chalk17 from "chalk";
 import { createRequire } from "module";
 
 // src/commands/install.ts
@@ -71,10 +71,10 @@ var logger = {
   /**
    * Log a skill entry with status indicator.
    */
-  skillEntry: (name, path5, hasSkillMd) => {
+  skillEntry: (name, path6, hasSkillMd) => {
     const status = hasSkillMd ? chalk.green("\u2713") : chalk.yellow("\u26A0");
     console.log(`  ${status} ${chalk.cyan(name)}`);
-    console.log(chalk.dim(`    \u2514\u2500 ${path5}`));
+    console.log(chalk.dim(`    \u2514\u2500 ${path6}`));
   },
   /**
    * Log installation result details.
@@ -337,6 +337,19 @@ function formatTreeNode(node, selection, isCursor, options = {}) {
   }
   return `${cursorMark}${indent}${checkbox} ${name}${count}${suffix}${hint}`;
 }
+function truncateDescription(value, maxLen) {
+  const trimmed = value.trim();
+  if (trimmed.length <= maxLen) return trimmed;
+  return `${trimmed.slice(0, maxLen - 3).trimEnd()}...`;
+}
+function getSkillDescriptionSuffix(skills, node, isCursor) {
+  if (!isCursor || !node.isLeaf || node.leafIndices.length !== 1) return "";
+  const skill = skills[node.leafIndices[0]];
+  if (!skill?.description) return "";
+  const description = truncateDescription(skill.description, 72);
+  if (!description) return "";
+  return chalk2.dim(` - ${description}`);
+}
 async function promptSkillsInteractive(skills, options = {}) {
   if (skills.length === 0) return null;
   const targetPlatforms = options.targetPlatforms || [];
@@ -355,19 +368,20 @@ async function promptSkillsInteractive(skills, options = {}) {
     subtitle: "\u2191\u2193 navigate \u2022 Space toggle \u2022 Enter confirm",
     buildTree: buildSkillTree,
     formatNode: (node, selection, isCursor) => {
-      let suffix = "";
+      let installedSuffix = "";
       if (node.isLeaf && node.leafIndices.length === 1) {
         const skill = skills[node.leafIndices[0]];
         if (skill?.installedPlatforms?.length) {
           if (skill.installedPlatforms.length === targetPlatforms.length && targetPlatforms.length > 0) {
-            suffix = chalk2.dim(" [installed]");
+            installedSuffix = chalk2.dim(" [installed]");
           } else if (skill.installedPlatforms.length > 0) {
-            suffix = chalk2.dim(` [installed on ${skill.installedPlatforms.length}]`);
+            installedSuffix = chalk2.dim(` [installed on ${skill.installedPlatforms.length}]`);
           }
         }
       }
-      const formatted = formatTreeNode(node, selection, isCursor, { suffix });
-      if (isCursor && suffix && selection.state !== "all") {
+      const descriptionSuffix = getSkillDescriptionSuffix(skills, node, isCursor);
+      const formatted = formatTreeNode(node, selection, isCursor, { suffix: `${installedSuffix}${descriptionSuffix}` });
+      if (isCursor && installedSuffix && selection.state !== "all") {
         return formatted.replace("\u2190 Space to select", "\u2190 Space to reinstall");
       }
       return formatted;
@@ -388,7 +402,10 @@ async function promptSkillsTreeInteractive(skills, tree, options = {}) {
     title: "Select skills from markdown",
     subtitle: "\u2191\u2193 navigate \u2022 Space toggle \u2022 Enter confirm",
     buildTree: () => buildTreeFromSkillNodes(tree, skills.length),
-    formatNode: (node, selection, isCursor) => formatTreeNode(node, selection, isCursor),
+    formatNode: (node, selection, isCursor) => {
+      const descriptionSuffix = getSkillDescriptionSuffix(skills, node, isCursor);
+      return formatTreeNode(node, selection, isCursor, { suffix: descriptionSuffix });
+    },
     defaultAll: options.defaultAll !== false
   });
   if (!selectedIndices) return null;
@@ -425,12 +442,32 @@ async function promptPlatformsInteractive(options = {}) {
 // src/commands/install-discovery.ts
 import fs from "fs";
 import path from "path";
+import { parseSkillFrontmatter, readSkillMd } from "@skild/core";
 function parsePositiveInt(input, fallback) {
   if (input == null) return fallback;
   const n = typeof input === "number" ? input : Number(String(input).trim());
   if (!Number.isFinite(n) || n <= 0) return fallback;
   return Math.floor(n);
 }
+function parseNonNegativeInt(input, fallback) {
+  if (input == null) return fallback;
+  const n = typeof input === "number" ? input : Number(String(input).trim());
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return Math.floor(n);
+}
+function extractSkillMetadata(skillMdContent) {
+  const frontmatter = parseSkillFrontmatter(skillMdContent);
+  if (!frontmatter) return null;
+  const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : void 0;
+  const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : void 0;
+  if (!name && !description) return null;
+  return { name, description };
+}
+function readSkillMetadata(skillDir) {
+  const content = readSkillMd(skillDir);
+  if (!content) return null;
+  return extractSkillMetadata(content);
+}
 function normalizeRelPath(relPath) {
   return relPath.split(path.sep).join("/").replace(/^\/+/, "").replace(/\/+$/, "");
 }
@@ -504,7 +541,7 @@ function discoverSkillDirsWithHeuristics(rootDir, options) {
   return discoverSkillDirs(root, options);
 }
 
-// src/commands/install-markdown.ts
+// src/commands/markdown-discovery.ts
 import fs2 from "fs";
 import path2 from "path";
 import { unified } from "unified";
@@ -514,7 +551,8 @@ import { deriveChildSource, fetchWithTimeout, materializeSourceToTemp } from "@s
 var README_CANDIDATES = ["README.md", "readme.md", "Readme.md", "README.markdown", "readme.markdown"];
 async function discoverMarkdownSkillsFromSource(input) {
   const ctx = {
-    maxDepth: input.maxDepth,
+    maxDocDepth: input.maxDocDepth,
+    maxSkillDepth: input.maxSkillDepth,
     maxSkills: input.maxSkills,
     maxLinks: Math.min(400, Math.max(200, input.maxSkills * 2)),
     linkLimitReached: false,
@@ -558,7 +596,7 @@ function cleanupRepoCache(ctx) {
   ctx.repoCache.clear();
 }
 async function parseMarkdownDoc(doc, ctx, depth, visitedDocs) {
-  if (depth > ctx.maxDepth) return [];
+  if (depth > ctx.maxDocDepth) return [];
   const docKey = `${doc.repo.owner}/${doc.repo.repo}#${doc.repo.ref || ""}:${doc.docPath}`;
   if (visitedDocs.has(docKey)) return [];
   visitedDocs.add(docKey);
@@ -646,7 +684,8 @@ async function parseInlineLinks(node, parent, doc, ctx, depth, visitedDocs) {
     if (!resolved) continue;
     const label = normalizeLabel(link.label) || resolved.displayName;
     const maybeMarkdown = !isLikelyFilePath(resolved.pathHint) || looksLikeMarkdownPath(resolved.pathHint);
-    if (maybeMarkdown) {
+    const canRecurseMarkdown = depth < ctx.maxDocDepth;
+    if (maybeMarkdown && canRecurseMarkdown) {
       const childDoc = await resolveMarkdownDoc(resolved.source, ctx);
       if (childDoc) {
         const childNodes = await parseMarkdownDoc(childDoc, ctx, depth + 1, visitedDocs);
@@ -666,10 +705,7 @@ async function parseInlineLinks(node, parent, doc, ctx, depth, visitedDocs) {
       parent.children.push(createSkillLeaf(ctx, skillIndices[0], label));
     } else {
       const groupLabel = label || resolved.displayName || "Skills";
-      const groupNode = createNode(ctx, groupLabel, "list", []);
-      for (const skillIndex of skillIndices) {
-        groupNode.children.push(createSkillLeaf(ctx, skillIndex));
-      }
+      const groupNode = buildSkillPathTree(ctx, skillIndices, groupLabel);
       parent.children.push(groupNode);
     }
   }
@@ -690,6 +726,50 @@ function createSkillLeaf(ctx, skillIndex, labelOverride) {
   node.skillIndex = skillIndex;
   return node;
 }
+function buildSkillPathTree(ctx, skillIndices, label) {
+  const root = createNode(ctx, label || "Skills", "list", []);
+  const childMap = /* @__PURE__ */ new WeakMap();
+  const ensureChild = (parent, segment) => {
+    let map = childMap.get(parent);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      childMap.set(parent, map);
+    }
+    const existing = map.get(segment);
+    if (existing) return existing;
+    const node = createNode(ctx, segment, "list", []);
+    parent.children.push(node);
+    map.set(segment, node);
+    return node;
+  };
+  for (const skillIndex of skillIndices) {
+    const skill = ctx.skills[skillIndex];
+    if (!skill) continue;
+    let relPath = skill.relPath || "";
+    if (relPath === "." || relPath === "./") {
+      root.children.push(createSkillLeaf(ctx, skillIndex, skill.displayName));
+      continue;
+    }
+    if (relPath.startsWith("./")) relPath = relPath.slice(2);
+    relPath = relPath.replace(/^\/+/, "");
+    if (!relPath) {
+      root.children.push(createSkillLeaf(ctx, skillIndex, skill.displayName));
+      continue;
+    }
+    const segments = relPath.split("/").filter(Boolean);
+    if (segments.length === 0) {
+      root.children.push(createSkillLeaf(ctx, skillIndex, skill.displayName));
+      continue;
+    }
+    let parent = root;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+      parent = ensureChild(parent, segments[i]);
+    }
+    const leafLabel = skill.displayName || segments[segments.length - 1];
+    parent.children.push(createSkillLeaf(ctx, skillIndex, leafLabel));
+  }
+  return root;
+}
 function collapseSingleChildNodes(nodes) {
   const collapsed = [];
   for (const node of nodes) {
@@ -773,17 +853,19 @@ async function resolveSkillsFromSource(source, displayName, ctx, repoHint) {
   }
   const skillMd = path2.join(materializedDir, "SKILL.md");
   if (fs2.existsSync(skillMd)) {
+    const metadata = readSkillMetadata(materializedDir);
     const skillIndex = registerSkill(ctx, {
       relPath: ".",
       suggestedSource: source,
       materializedDir,
-      displayName: displayName || deriveDisplayName(source)
+      displayName: metadata?.name || displayName || deriveDisplayName(source),
+      description: metadata?.description
     });
     const indices2 = [skillIndex];
     ctx.skillCache.set(source, indices2);
     return indices2;
   }
-  const discovered = discoverSkillDirsWithHeuristics(materializedDir, { maxDepth: ctx.maxDepth, maxSkills: ctx.maxSkills });
+  const discovered = discoverSkillDirsWithHeuristics(materializedDir, { maxDepth: ctx.maxSkillDepth, maxSkills: ctx.maxSkills });
   if (discovered.length === 0) {
     ctx.skillCache.set(source, []);
     return [];
@@ -791,11 +873,13 @@ async function resolveSkillsFromSource(source, displayName, ctx, repoHint) {
   const indices = [];
   for (const skill of discovered) {
     const childSource = deriveChildSource(source, skill.relPath);
+    const metadata = readSkillMetadata(skill.absDir);
     const skillIndex = registerSkill(ctx, {
       relPath: skill.relPath,
       suggestedSource: childSource,
       materializedDir: skill.absDir,
-      displayName: deriveDisplayName(childSource)
+      displayName: metadata?.name || deriveDisplayName(childSource),
+      description: metadata?.description
     });
     indices.push(skillIndex);
   }
@@ -808,23 +892,27 @@ function resolveSkillsFromLocal(repoHint, source, displayName, ctx) {
   if (!fs2.existsSync(base)) return [];
   const skillMd = path2.join(base, "SKILL.md");
   if (fs2.existsSync(skillMd)) {
+    const metadata = readSkillMetadata(base);
     return [
       registerSkill(ctx, {
         relPath: ".",
         suggestedSource: source,
-        displayName: displayName || deriveDisplayName(source)
+        displayName: metadata?.name || displayName || deriveDisplayName(source),
+        description: metadata?.description
       })
     ];
   }
-  const discovered = discoverSkillDirsWithHeuristics(base, { maxDepth: ctx.maxDepth, maxSkills: ctx.maxSkills });
+  const discovered = discoverSkillDirsWithHeuristics(base, { maxDepth: ctx.maxSkillDepth, maxSkills: ctx.maxSkills });
   if (discovered.length === 0) return [];
   const indices = [];
   for (const skill of discovered) {
     const childSource = deriveChildSource(source, skill.relPath);
+    const metadata = readSkillMetadata(skill.absDir);
     const skillIndex = registerSkill(ctx, {
       relPath: skill.relPath,
       suggestedSource: childSource,
-      displayName: deriveDisplayName(childSource)
+      displayName: metadata?.name || deriveDisplayName(childSource),
+      description: metadata?.description
     });
     indices.push(skillIndex);
   }
@@ -842,16 +930,19 @@ async function tryFetchSkillManifest(source, displayName, ctx) {
       if (res.status === 404) return [];
       return [];
     }
+    const content = await res.text();
+    const metadata = extractSkillMetadata(content);
+    return [
+      registerSkill(ctx, {
+        relPath: ".",
+        suggestedSource: source,
+        displayName: metadata?.name || displayName || deriveDisplayName(source),
+        description: metadata?.description
+      })
+    ];
   } catch {
     return [];
   }
-  return [
-    registerSkill(ctx, {
-      relPath: ".",
-      suggestedSource: source,
-      displayName: displayName || deriveDisplayName(source)
-    })
-  ];
 }
 function registerSkill(ctx, skill) {
   const key = skill.suggestedSource;
@@ -1046,12 +1137,18 @@ function getPlatformPromptList(scope) {
   const installed = getInstalledPlatforms(scope);
   return installed.length > 0 ? installed : [...PLATFORMS2];
 }
-function asDiscoveredSkills(discovered, toSuggestedSource, toMaterializedDir) {
-  return discovered.map((d) => ({
-    relPath: d.relPath,
-    suggestedSource: toSuggestedSource(d),
-    materializedDir: toMaterializedDir ? toMaterializedDir(d) : void 0
-  }));
+function asDiscoveredSkills(discovered, toSuggestedSource, toMaterializedDir, toMetadataDir) {
+  return discovered.map((d) => {
+    const metadataDir = toMetadataDir ? toMetadataDir(d) : void 0;
+    const metadata = metadataDir ? readSkillMetadata(metadataDir) : null;
+    return {
+      relPath: d.relPath,
+      suggestedSource: toSuggestedSource(d),
+      materializedDir: toMaterializedDir ? toMaterializedDir(d) : void 0,
+      displayName: metadata?.name,
+      description: metadata?.description
+    };
+  });
 }
 function createContext(source, options) {
   const scope = options.local ? "project" : "global";
@@ -1082,7 +1179,8 @@ function createContext(source, options) {
     jsonOnly,
     interactive,
     yes,
-    maxDepth: parsePositiveInt(options.depth, 6),
+    markdownDepth: parseNonNegativeInt(options.depth, 0),
+    scanDepth: parseNonNegativeInt(options.scanDepth, 6),
     maxSkills: parsePositiveInt(options.maxSkills, 200),
     resolvedSource: source.trim(),
     targets,
@@ -1129,7 +1227,7 @@ async function resolveSource(ctx) {
   return true;
 }
 async function discoverSkills(ctx) {
-  const { resolvedSource, maxDepth, maxSkills, jsonOnly } = ctx;
+  const { resolvedSource, markdownDepth, scanDepth, maxSkills, jsonOnly } = ctx;
   if (ctx.spinner) {
     ctx.spinner.text = `Discovery at ${chalk3.cyan(ctx.source)}...`;
   }
@@ -1144,11 +1242,17 @@ async function discoverSkills(ctx) {
     if (isLocal) {
       const hasSkillMd2 = fs3.existsSync(path3.join(maybeLocalRoot, "SKILL.md"));
       if (hasSkillMd2) {
+        const metadata = readSkillMetadata(maybeLocalRoot);
         ctx.isSingleSkill = true;
-        ctx.selectedSkills = [{ relPath: maybeLocalRoot, suggestedSource: resolvedSource }];
+        ctx.selectedSkills = [{
+          relPath: maybeLocalRoot,
+          suggestedSource: resolvedSource,
+          displayName: metadata?.name,
+          description: metadata?.description
+        }];
         return true;
       }
-      const discovered2 = discoverSkillDirsWithHeuristics(maybeLocalRoot, { maxDepth, maxSkills });
+      const discovered2 = discoverSkillDirsWithHeuristics(maybeLocalRoot, { maxDepth: scanDepth, maxSkills });
       if (discovered2.length === 0) {
         const message = `No SKILL.md found at ${maybeLocalRoot} (or within subdirectories).`;
         if (jsonOnly) {
@@ -1160,12 +1264,18 @@ async function discoverSkills(ctx) {
         process.exitCode = 1;
         return false;
       }
-      ctx.discoveredSkills = asDiscoveredSkills(discovered2, (d) => path3.join(maybeLocalRoot, d.relPath));
+      ctx.discoveredSkills = asDiscoveredSkills(
+        discovered2,
+        (d) => path3.join(maybeLocalRoot, d.relPath),
+        void 0,
+        (d) => d.absDir
+      );
       return true;
     }
     const markdownResult = await discoverMarkdownSkillsFromSource({
       source: resolvedSource,
-      maxDepth,
+      maxDocDepth: markdownDepth,
+      maxSkillDepth: scanDepth,
       maxSkills,
       onProgress: (update2) => {
         if (ctx.spinner) {
@@ -1188,11 +1298,18 @@ async function discoverSkills(ctx) {
     ctx.cleanupMaterialized = appendCleanup(ctx.cleanupMaterialized, materialized.cleanup);
     const hasSkillMd = fs3.existsSync(path3.join(ctx.materializedDir, "SKILL.md"));
     if (hasSkillMd) {
+      const metadata = readSkillMetadata(ctx.materializedDir);
       ctx.isSingleSkill = true;
-      ctx.selectedSkills = [{ relPath: ".", suggestedSource: resolvedSource, materializedDir: ctx.materializedDir }];
+      ctx.selectedSkills = [{
+        relPath: ".",
+        suggestedSource: resolvedSource,
+        materializedDir: ctx.materializedDir,
+        displayName: metadata?.name,
+        description: metadata?.description
+      }];
       return true;
     }
-    const discovered = discoverSkillDirsWithHeuristics(ctx.materializedDir, { maxDepth, maxSkills });
+    const discovered = discoverSkillDirsWithHeuristics(ctx.materializedDir, { maxDepth: scanDepth, maxSkills });
     if (discovered.length === 0) {
       const message = `No SKILL.md found in source "${resolvedSource}".`;
       if (jsonOnly) {
@@ -1207,6 +1324,7 @@ async function discoverSkills(ctx) {
     ctx.discoveredSkills = asDiscoveredSkills(
       discovered,
       (d) => deriveChildSource2(resolvedSource, d.relPath),
+      (d) => d.absDir,
       (d) => d.absDir
     );
     return true;
@@ -2250,13 +2368,310 @@ async function search(query, options = {}) {
   }
 }
 
+// src/commands/extract-github-skills.ts
+import fs5 from "fs";
+import path5 from "path";
+import os2 from "os";
+import chalk16 from "chalk";
+import {
+  deriveChildSource as deriveChildSource3,
+  materializeSourceToTemp as materializeSourceToTemp3,
+  SkildError as SkildError11
+} from "@skild/core";
+async function extractGithubSkills(source, options) {
+  const resolvedSource = source.trim();
+  const jsonOnly = Boolean(options.json);
+  if (!parseGitHubSource(resolvedSource)) {
+    const message = `Only GitHub sources are supported for extract-github-skills: "${resolvedSource}"`;
+    if (jsonOnly) {
+      process.stdout.write(JSON.stringify({ ok: false, error: message }, null, 2) + "\n");
+    } else {
+      console.error(chalk16.red(message));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const maxDocDepth = parseNonNegativeInt(options.depth, 0);
+  const maxSkillDepth = parseNonNegativeInt(options.scanDepth, 6);
+  const maxSkills = parsePositiveInt(options.maxSkills, 200);
+  const outDir = resolveOutDir(options.out);
+  const force = Boolean(options.force);
+  try {
+    prepareOutputDir(outDir, force);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (jsonOnly) {
+      process.stdout.write(JSON.stringify({ ok: false, error: message }, null, 2) + "\n");
+    } else {
+      console.error(chalk16.red(message));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const spinner = createSpinner(`Parsing markdown at ${chalk16.cyan(resolvedSource)}...`);
+  if (!jsonOnly) spinner.start();
+  let skills = [];
+  let tree = [];
+  let cleanup = null;
+  try {
+    const markdownResult = await discoverMarkdownSkillsFromSource({
+      source: resolvedSource,
+      maxDocDepth,
+      maxSkillDepth,
+      maxSkills,
+      onProgress: (update2) => {
+        if (!spinner) return;
+        const current = update2.current ? ` \xB7 ${update2.current}` : "";
+        const capped = update2.linkLimitReached ? " \xB7 link cap reached" : "";
+        spinner.text = `Parsing markdown (${update2.docsScanned} docs, ${update2.linksChecked} links, ${update2.skillsFound} skills)${current}${capped}`;
+      }
+    });
+    if (markdownResult && markdownResult.skills.length > 0) {
+      skills = markdownResult.skills;
+      tree = markdownResult.tree;
+      cleanup = markdownResult.cleanup;
+    } else {
+      if (!jsonOnly) spinner.text = `Scanning repository at ${chalk16.cyan(resolvedSource)}...`;
+      const materialized = await materializeSourceToTemp3(resolvedSource);
+      cleanup = materialized.cleanup;
+      const discovered = discoverSkillDirsWithHeuristics(materialized.dir, { maxDepth: maxSkillDepth, maxSkills });
+      if (discovered.length === 0) {
+        throw new SkildError11("SKILL_NOT_FOUND", `No SKILL.md found in source "${resolvedSource}".`);
+      }
+      skills = discovered.map((d) => {
+        const metadata = readSkillMetadata(d.absDir);
+        return {
+          relPath: d.relPath,
+          suggestedSource: d.relPath === "." ? resolvedSource : deriveChildSource3(resolvedSource, d.relPath),
+          materializedDir: d.absDir,
+          displayName: metadata?.name,
+          description: metadata?.description
+        };
+      });
+      tree = buildTreeFromRelPaths(skills);
+    }
+    if (skills.length > maxSkills) {
+      throw new SkildError11("INVALID_SOURCE", `Found more than ${maxSkills} skills. Increase --max-skills to proceed.`);
+    }
+    const exportPaths = buildExportPathMap(tree, skills);
+    const repoCache = /* @__PURE__ */ new Map();
+    for (let i = 0; i < skills.length; i++) {
+      const skill = skills[i];
+      const exportSegments = exportPaths.get(i);
+      if (!exportSegments || exportSegments.length === 0) continue;
+      const exportPath = path5.join(outDir, ...exportSegments);
+      const localDir = await resolveSkillDirectory(skill, repoCache);
+      copyDirectory(localDir, exportPath);
+      const metadata = readSkillMetadata(localDir) || { name: skill.displayName, description: skill.description };
+      const skillJson = {
+        name: metadata?.name || skill.displayName || skill.relPath || void 0,
+        description: metadata?.description || skill.description || void 0,
+        source: skill.suggestedSource,
+        relPath: skill.relPath,
+        exportPath: path5.relative(outDir, exportPath).split(path5.sep).join("/")
+      };
+      fs5.writeFileSync(path5.join(exportPath, "skill.json"), JSON.stringify(skillJson, null, 2));
+    }
+    const catalogSkills = skills.map((skill, index) => {
+      const exportSegments = exportPaths.get(index) || [];
+      const exportPath = exportSegments.length > 0 ? exportSegments.join("/") : slugifySegment(skill.displayName || skill.relPath || "skill", "skill");
+      return {
+        index,
+        name: skill.displayName || void 0,
+        description: skill.description || void 0,
+        source: skill.suggestedSource,
+        relPath: skill.relPath,
+        exportPath
+      };
+    });
+    const catalog = {
+      schemaVersion: 1,
+      source: resolvedSource,
+      exportRoot: outDir,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tree,
+      skills: catalogSkills
+    };
+    fs5.writeFileSync(path5.join(outDir, "catalog.json"), JSON.stringify(catalog, null, 2));
+    for (const entry of repoCache.values()) entry.cleanup();
+    cleanup?.();
+    if (!jsonOnly) {
+      spinner.succeed(`Exported ${skills.length} skill${skills.length > 1 ? "s" : ""} to ${chalk16.cyan(outDir)}`);
+    } else {
+      process.stdout.write(JSON.stringify({ ok: true, outDir, skills: catalogSkills }, null, 2) + "\n");
+    }
+  } catch (error) {
+    cleanup?.();
+    if (!jsonOnly) spinner.stop();
+    const message = error instanceof SkildError11 ? error.message : error instanceof Error ? error.message : String(error);
+    if (jsonOnly) {
+      process.stdout.write(JSON.stringify({ ok: false, error: message }, null, 2) + "\n");
+    } else {
+      console.error(chalk16.red(message));
+    }
+    process.exitCode = 1;
+  }
+}
+function resolveOutDir(out) {
+  if (!out || !out.trim()) {
+    return path5.resolve(process.cwd(), "skild-github-skills");
+  }
+  const trimmed = out.trim();
+  if (trimmed.startsWith("~")) {
+    return path5.resolve(os2.homedir(), trimmed.slice(1));
+  }
+  return path5.resolve(process.cwd(), trimmed);
+}
+function prepareOutputDir(outDir, force) {
+  if (fs5.existsSync(outDir)) {
+    const entries = fs5.readdirSync(outDir);
+    if (entries.length > 0) {
+      if (!force) {
+        throw new Error(`Output directory is not empty: ${outDir}. Use --force to overwrite.`);
+      }
+      fs5.rmSync(outDir, { recursive: true, force: true });
+    }
+  }
+  fs5.mkdirSync(outDir, { recursive: true });
+}
+async function resolveSkillDirectory(skill, repoCache) {
+  if (skill.materializedDir && fs5.existsSync(skill.materializedDir)) return skill.materializedDir;
+  const parsed = parseGitHubSource(skill.suggestedSource);
+  if (!parsed) throw new SkildError11("INVALID_SOURCE", `Unsupported skill source: ${skill.suggestedSource}`);
+  const ref = parsed.ref || "HEAD";
+  const repoKey = `${parsed.owner}/${parsed.repo}#${ref}`;
+  let cached = repoCache.get(repoKey);
+  if (!cached) {
+    const materialized = await materializeSourceToTemp3(repoKey);
+    cached = { dir: materialized.dir, cleanup: materialized.cleanup };
+    repoCache.set(repoKey, cached);
+  }
+  const relPath = parsed.path ? parsed.path.replace(/^\/+/, "") : "";
+  const resolved = relPath ? path5.join(cached.dir, relPath) : cached.dir;
+  if (!fs5.existsSync(resolved)) {
+    throw new SkildError11("SKILL_NOT_FOUND", `Skill path missing in repo: ${skill.suggestedSource}`);
+  }
+  return resolved;
+}
+function copyDirectory(fromDir, toDir) {
+  fs5.mkdirSync(path5.dirname(toDir), { recursive: true });
+  fs5.cpSync(fromDir, toDir, { recursive: true, errorOnExist: false, force: true });
+}
+function buildTreeFromRelPaths(skills) {
+  let nodeId = 0;
+  const root = { id: "root", label: "root", kind: "list", children: [] };
+  const ensureChild = (parent, label) => {
+    const found = parent.children.find((child2) => child2.label === label);
+    if (found) return found;
+    nodeId += 1;
+    const child = { id: `rel-${nodeId}`, label, kind: "list", children: [] };
+    parent.children.push(child);
+    return child;
+  };
+  skills.forEach((skill, index) => {
+    const relPath = skill.relPath === "." ? "" : skill.relPath;
+    const segments = relPath.split("/").filter(Boolean);
+    let parent = root;
+    if (segments.length === 0) {
+      nodeId += 1;
+      parent.children.push({
+        id: `rel-${nodeId}`,
+        label: skill.displayName || "skill",
+        kind: "skill",
+        skillIndex: index,
+        children: []
+      });
+      return;
+    }
+    for (let i = 0; i < segments.length - 1; i += 1) {
+      parent = ensureChild(parent, segments[i]);
+    }
+    nodeId += 1;
+    parent.children.push({
+      id: `rel-${nodeId}`,
+      label: skill.displayName || segments[segments.length - 1],
+      kind: "skill",
+      skillIndex: index,
+      children: []
+    });
+  });
+  return collapseSingleChildNodes2(root.children);
+}
+function buildExportPathMap(tree, skills) {
+  const paths = /* @__PURE__ */ new Map();
+  const usedPaths = /* @__PURE__ */ new Set();
+  const walk = (nodes, parentSegments) => {
+    const siblingCounts = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      const base = slugifySegment(node.label, node.kind === "skill" ? "skill" : "section");
+      const segment = ensureUniqueSegment(base, siblingCounts);
+      if (node.kind === "skill" && node.skillIndex != null) {
+        const segments = ensureUniquePath([...parentSegments, segment], usedPaths);
+        paths.set(node.skillIndex, segments);
+        usedPaths.add(segments.join("/"));
+        continue;
+      }
+      if (node.children.length > 0) {
+        walk(node.children, [...parentSegments, segment]);
+      }
+    }
+  };
+  walk(tree, []);
+  for (let i = 0; i < skills.length; i++) {
+    if (paths.has(i)) continue;
+    const skill = skills[i];
+    const fallbackSegments = relPathSegments(skill);
+    const segments = ensureUniquePath(fallbackSegments, usedPaths);
+    paths.set(i, segments);
+    usedPaths.add(segments.join("/"));
+  }
+  return paths;
+}
+function relPathSegments(skill) {
+  if (skill.relPath && skill.relPath !== ".") {
+    return skill.relPath.split("/").filter(Boolean).map((segment) => slugifySegment(segment, "skill"));
+  }
+  return [slugifySegment(skill.displayName || skill.relPath || "skill", "skill")];
+}
+function ensureUniqueSegment(base, counts) {
+  const next = (counts.get(base) || 0) + 1;
+  counts.set(base, next);
+  return next === 1 ? base : `${base}-${next}`;
+}
+function ensureUniquePath(segments, usedPaths) {
+  let candidate = segments.join("/");
+  if (!usedPaths.has(candidate)) return segments;
+  let suffix = 2;
+  const baseSegments = [...segments];
+  while (usedPaths.has(candidate)) {
+    candidate = [...baseSegments.slice(0, -1), `${baseSegments[baseSegments.length - 1]}-${suffix}`].join("/");
+    suffix += 1;
+  }
+  return candidate.split("/");
+}
+function slugifySegment(label, fallback) {
+  const normalized = label.trim().toLowerCase();
+  const slug = normalized.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+function collapseSingleChildNodes2(nodes) {
+  return nodes.map((node) => collapseNode2(node)).filter(Boolean);
+}
+function collapseNode2(node) {
+  node.children = node.children.map((child) => collapseNode2(child)).filter(Boolean);
+  if (node.kind !== "heading" && node.kind !== "skill" && node.children.length === 1 && !node.skillIndex) {
+    return node.children[0];
+  }
+  return node;
+}
+
 // src/index.ts
 import { PLATFORMS as PLATFORMS4 } from "@skild/core";
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var program = new Command();
 program.name("skild").description("The npm for Agent Skills \u2014 Discover, install, manage, and publish AI Agent Skills with ease.").version(version);
-program.command("install <source>").alias("i").description("Install a Skill from a Git URL, degit shorthand, or local directory").option("-t, --target <platform>", `Target platform: ${PLATFORMS4.join(", ")}`).option("--all", `Install to all platforms: ${PLATFORMS4.join(", ")}`).option("--recursive", "If source is a multi-skill directory/repo, install all discovered skills").option("-y, --yes", "Skip confirmation prompts (assume yes)").option("--depth <n>", "Max directory depth to scan for SKILL.md (default: 6)", "6").option("--max-skills <n>", "Max discovered skills to install (default: 200)", "200").option("-l, --local", "Install to project-level directory instead of global").option("-f, --force", "Overwrite existing installation").option("--registry <url>", "Registry base URL (default: https://registry.skild.sh)").option("--json", "Output JSON").action(async (source, options) => {
+program.command("install <source>").alias("i").description("Install a Skill from a Git URL, degit shorthand, or local directory").option("-t, --target <platform>", `Target platform: ${PLATFORMS4.join(", ")}`).option("--all", `Install to all platforms: ${PLATFORMS4.join(", ")}`).option("--recursive", "If source is a multi-skill directory/repo, install all discovered skills").option("-y, --yes", "Skip confirmation prompts (assume yes)").option("--depth <n>", "Max markdown recursion depth (default: 0)", "0").option("--scan-depth <n>", "Max directory depth to scan for SKILL.md (default: 6)", "6").option("--max-skills <n>", "Max discovered skills to install (default: 200)", "200").option("-l, --local", "Install to project-level directory instead of global").option("-f, --force", "Overwrite existing installation").option("--registry <url>", "Registry base URL (default: https://registry.skild.sh)").option("--json", "Output JSON").action(async (source, options) => {
   await install(source, options);
 });
 program.command("list").alias("ls").description("List installed Skills").option("-t, --target <platform>", `Target platform: ${PLATFORMS4.join(", ")} (optional; omit to list all)`).option("-l, --local", "List project-level directory instead of global").option("--paths", "Show install paths").option("--verbose", "Show skillset dependency details").option("--json", "Output JSON").action(async (options) => list(options));
@@ -2271,8 +2686,11 @@ program.command("logout").description("Remove stored registry credentials").acti
 program.command("whoami").description("Show current registry identity").action(async () => whoami());
 program.command("publish").description("Publish a Skill directory to the registry (hosted tarball)").option("--dir <path>", "Skill directory (defaults to cwd)").option("--name <@publisher/skill>", "Override skill name (defaults to SKILL.md frontmatter)").option("--skill-version <semver>", "Override version (defaults to SKILL.md frontmatter)").option("--alias <alias>", "Optional short identifier (global unique) for `skild install <alias>`").option("--description <text>", "Override description (defaults to SKILL.md frontmatter)").option("--targets <list>", "Comma-separated target platforms metadata (optional)").option("--tag <tag>", "Dist-tag (default: latest)", "latest").option("--registry <url>", "Registry base URL (defaults to saved login)").option("--json", "Output JSON").action(async (options) => publish(options));
 program.command("search <query>").description("Search Skills in the registry").option("--registry <url>", "Registry base URL (default: https://registry.skild.sh)").option("--limit <n>", "Max results (default: 50)", "50").option("--json", "Output JSON").action(async (query, options) => search(query, options));
+program.command("extract-github-skills <source>").description("Extract GitHub skills into a local catalog directory").option("--out <dir>", "Output directory (default: ./skild-github-skills)").option("-f, --force", "Overwrite existing output directory").option("--depth <n>", "Max markdown recursion depth (default: 0)", "0").option("--scan-depth <n>", "Max directory depth to scan for SKILL.md (default: 6)", "6").option("--max-skills <n>", "Max discovered skills to export (default: 200)", "200").option("--json", "Output JSON").action(async (source, options) => {
+  await extractGithubSkills(source, options);
+});
 program.action(() => {
-  console.log(chalk16.bold("\n\u{1F6E1}\uFE0F skild \u2014 Get your agents skilled.\n"));
+  console.log(chalk17.bold("\n\u{1F6E1}\uFE0F skild \u2014 Get your agents skilled.\n"));
   program.outputHelp();
 });
 var argv = process.argv.slice();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skild",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The npm for Agent Skills — Discover, install, manage, and publish AI Agent Skills with ease.",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,7 @@
     "remark-parse": "^11.0.0",
     "tar": "^7.4.3",
     "unified": "^11.0.4",
-    "@skild/core": "^0.5.2"
+    "@skild/core": "^0.7.0"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",