skild 0.5.2 → 0.6.0

package/dist/index.js

@@ -6,17 +6,18 @@ import chalk16 from "chalk";
 import { createRequire } from "module";
 
 // src/commands/install.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 import chalk3 from "chalk";
 import {
-  deriveChildSource,
-  fetchWithTimeout,
+  deriveChildSource as deriveChildSource2,
+  fetchWithTimeout as fetchWithTimeout2,
   installRegistrySkill,
   installSkill,
   isValidAlias,
+  listSkills,
   loadRegistryAuth,
-  materializeSourceToTemp,
+  materializeSourceToTemp as materializeSourceToTemp2,
   resolveRegistryAlias,
   resolveRegistryUrl,
   stripSourceRef,
@@ -70,10 +71,10 @@ var logger = {
   /**
    * Log a skill entry with status indicator.
    */
-  skillEntry: (name, path4, hasSkillMd) => {
+  skillEntry: (name, path5, hasSkillMd) => {
     const status = hasSkillMd ? chalk.green("\u2713") : chalk.yellow("\u26A0");
     console.log(`  ${status} ${chalk.cyan(name)}`);
-    console.log(chalk.dim(`    \u2514\u2500 ${path4}`));
+    console.log(chalk.dim(`    \u2514\u2500 ${path5}`));
   },
   /**
    * Log installation result details.
@@ -119,6 +120,35 @@ function buildPlatformTree(items) {
   }
   return wrapWithRoot(allNode);
 }
+function buildTreeFromSkillNodes(nodes, totalSkills) {
+  const allNode = createTreeNode("all", "All Skills", 1, false);
+  const attach = (node, depth) => {
+    const treeNode = createTreeNode(
+      node.id,
+      node.label,
+      depth,
+      Boolean(node.skillIndex != null && (!node.children || node.children.length === 0)),
+      node.skillIndex != null ? [node.skillIndex] : []
+    );
+    if (node.children?.length) {
+      for (const child of node.children) {
+        const childNode = attach(child, depth + 1);
+        treeNode.children.push(childNode);
+        treeNode.leafIndices.push(...childNode.leafIndices);
+      }
+    }
+    return treeNode;
+  };
+  for (const node of nodes) {
+    const childNode = attach(node, 2);
+    allNode.children.push(childNode);
+    allNode.leafIndices.push(...childNode.leafIndices);
+  }
+  if (allNode.leafIndices.length === 0 && totalSkills > 0) {
+    for (let i = 0; i < totalSkills; i++) allNode.leafIndices.push(i);
+  }
+  return wrapWithRoot(allNode);
+}
 function createTreeNode(id, name, depth, isLeaf, leafIndices = []) {
   return { id, name, depth, children: [], leafIndices, isLeaf };
 }
@@ -353,8 +383,25 @@ async function promptSkillsInteractive(skills, options = {}) {
 `));
   return selectedSkills;
 }
+async function promptSkillsTreeInteractive(skills, tree, options = {}) {
+  const selectedIndices = await interactiveTreeSelect(skills, {
+    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),
+    defaultAll: options.defaultAll !== false
+  });
+  if (!selectedIndices) return null;
+  const selectedSkills = selectedIndices.map((i) => skills[i]);
+  const names = selectedSkills.map((s) => s.displayName || s.relPath || s.suggestedSource);
+  console.log(chalk2.green(`
+\u2713 Selected ${selectedSkills.length} skill${selectedSkills.length > 1 ? "s" : ""}: ${chalk2.cyan(names.join(", "))}
+`));
+  return selectedSkills;
+}
 async function promptPlatformsInteractive(options = {}) {
-  const platformItems = PLATFORMS.map((p) => ({ platform: p }));
+  const platforms = options.platforms && options.platforms.length > 0 ? options.platforms : PLATFORMS;
+  const platformItems = platforms.map((p) => ({ platform: p }));
   const selectedIndices = await interactiveTreeSelect(platformItems, {
     title: "Select target platforms",
     subtitle: "\u2191\u2193 navigate \u2022 Space toggle \u2022 Enter confirm",
@@ -367,7 +414,7 @@ async function promptPlatformsInteractive(options = {}) {
     defaultAll: options.defaultAll !== false
   });
   if (!selectedIndices) return null;
-  const selected = selectedIndices.map((i) => PLATFORMS[i]);
+  const selected = selectedIndices.map((i) => platforms[i]);
   const names = selected.map((p) => PLATFORM_DISPLAY[p] || p);
   console.log(chalk2.green(`
 \u2713 Installing to ${selected.length} platform${selected.length > 1 ? "s" : ""}: ${chalk2.cyan(names.join(", "))}
@@ -457,6 +504,518 @@ function discoverSkillDirsWithHeuristics(rootDir, options) {
   return discoverSkillDirs(root, options);
 }
 
+// src/commands/install-markdown.ts
+import fs2 from "fs";
+import path2 from "path";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import { toString } from "mdast-util-to-string";
+import { deriveChildSource, fetchWithTimeout, materializeSourceToTemp } from "@skild/core";
+var README_CANDIDATES = ["README.md", "readme.md", "Readme.md", "README.markdown", "readme.markdown"];
+async function discoverMarkdownSkillsFromSource(input) {
+  const ctx = {
+    maxDepth: input.maxDepth,
+    maxSkills: input.maxSkills,
+    maxLinks: Math.min(400, Math.max(200, input.maxSkills * 2)),
+    linkLimitReached: false,
+    onProgress: input.onProgress,
+    docsScanned: 0,
+    linksChecked: 0,
+    skillsFound: 0,
+    repoCache: /* @__PURE__ */ new Map(),
+    skillCache: /* @__PURE__ */ new Map(),
+    skillIndexBySource: /* @__PURE__ */ new Map(),
+    skills: [],
+    skillCleanups: [],
+    nodeId: 0
+  };
+  try {
+    const entryDoc = await resolveMarkdownDoc(input.source, ctx);
+    if (!entryDoc) {
+      cleanupRepoCache(ctx);
+      return null;
+    }
+    const visitedDocs = /* @__PURE__ */ new Set();
+    const tree = await parseMarkdownDoc(entryDoc, ctx, 0, visitedDocs);
+    cleanupRepoCache(ctx);
+    const compacted = collapseSingleChildNodes(tree);
+    return {
+      skills: ctx.skills,
+      tree: compacted,
+      cleanup: () => {
+        for (const cleanup of ctx.skillCleanups) cleanup();
+      }
+    };
+  } catch {
+    cleanupRepoCache(ctx);
+    return null;
+  }
+}
+function cleanupRepoCache(ctx) {
+  for (const entry of ctx.repoCache.values()) {
+    entry.cleanup?.();
+  }
+  ctx.repoCache.clear();
+}
+async function parseMarkdownDoc(doc, ctx, depth, visitedDocs) {
+  if (depth > ctx.maxDepth) return [];
+  const docKey = `${doc.repo.owner}/${doc.repo.repo}#${doc.repo.ref || ""}:${doc.docPath}`;
+  if (visitedDocs.has(docKey)) return [];
+  visitedDocs.add(docKey);
+  let content;
+  try {
+    if (doc.content != null) {
+      content = doc.content;
+    } else if (doc.filePath) {
+      content = fs2.readFileSync(doc.filePath, "utf-8");
+    } else {
+      return [];
+    }
+  } catch {
+    return [];
+  }
+  ctx.docsScanned += 1;
+  updateProgress(ctx, doc.docPath ? path2.posix.basename(doc.docPath) : void 0);
+  const ast = unified().use(remarkParse).parse(content);
+  const rootNode = createNode(ctx, "root", "doc", []);
+  const headingStack = [];
+  for (const child of ast.children) {
+    if (child.type === "heading") {
+      const label = normalizeLabel(toString(child)) || `Section ${child.depth}`;
+      const headingNode = createNode(ctx, label, "heading", []);
+      const parent = findHeadingParent(headingStack, child.depth, rootNode);
+      parent.children.push(headingNode);
+      headingStack.push({ depth: child.depth, node: headingNode });
+    } else if (child.type === "list") {
+      const parent = currentHeading(headingStack, rootNode);
+      await parseListNode(child, parent, doc, ctx, depth, visitedDocs);
+    } else {
+      const parent = currentHeading(headingStack, rootNode);
+      await parseInlineLinks(child, parent, doc, ctx, depth, visitedDocs);
+    }
+  }
+  return rootNode.children;
+}
+function currentHeading(stack, fallback) {
+  return stack.length ? stack[stack.length - 1].node : fallback;
+}
+function findHeadingParent(stack, depth, fallback) {
+  while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+    stack.pop();
+  }
+  return stack.length ? stack[stack.length - 1].node : fallback;
+}
+async function parseListNode(node, parent, doc, ctx, depth, visitedDocs) {
+  if (ctx.linkLimitReached || ctx.skillsFound >= ctx.maxSkills) return;
+  for (const item of node.children) {
+    const label = normalizeLabel(toString(item)) || "Item";
+    const listNode = createNode(ctx, label, "list", []);
+    let hasContent = false;
+    for (const child of item.children) {
+      if (child.type === "list") {
+        await parseListNode(child, listNode, doc, ctx, depth, visitedDocs);
+        if (listNode.children.length > 0) hasContent = true;
+      } else {
+        const added = await parseInlineLinks(child, listNode, doc, ctx, depth, visitedDocs);
+        if (added) hasContent = true;
+      }
+    }
+    if (hasContent) {
+      parent.children.push(listNode);
+    }
+  }
+}
+async function parseInlineLinks(node, parent, doc, ctx, depth, visitedDocs) {
+  const links = collectLinks(node);
+  let added = false;
+  if (ctx.skillsFound >= ctx.maxSkills) {
+    ctx.linkLimitReached = true;
+    updateProgress(ctx);
+    return false;
+  }
+  for (const link of links) {
+    if (ctx.linkLimitReached) return added;
+    if (ctx.linksChecked >= ctx.maxLinks) {
+      ctx.linkLimitReached = true;
+      updateProgress(ctx);
+      return added;
+    }
+    ctx.linksChecked += 1;
+    updateProgress(ctx);
+    const resolved = resolveLink(doc, link.url);
+    if (!resolved) continue;
+    const label = normalizeLabel(link.label) || resolved.displayName;
+    const maybeMarkdown = !isLikelyFilePath(resolved.pathHint) || looksLikeMarkdownPath(resolved.pathHint);
+    if (maybeMarkdown) {
+      const childDoc = await resolveMarkdownDoc(resolved.source, ctx);
+      if (childDoc) {
+        const childNodes = await parseMarkdownDoc(childDoc, ctx, depth + 1, visitedDocs);
+        if (childNodes.length > 0) {
+          const docNode = createNode(ctx, label, "doc", childNodes);
+          parent.children.push(docNode);
+          added = true;
+          continue;
+        }
+      }
+    }
+    if (isLikelyFilePath(resolved.pathHint)) continue;
+    const skillIndices = await resolveSkillsFromSource(resolved.source, label, ctx, resolved.sameRepo ? { repo: doc.repo, pathHint: resolved.pathHint } : void 0);
+    if (skillIndices.length === 0) continue;
+    added = true;
+    if (skillIndices.length === 1) {
+      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));
+      }
+      parent.children.push(groupNode);
+    }
+  }
+  return added;
+}
+function createNode(ctx, label, kind, children) {
+  ctx.nodeId += 1;
+  return {
+    id: `md-${ctx.nodeId}`,
+    label: label.trim(),
+    kind,
+    children
+  };
+}
+function createSkillLeaf(ctx, skillIndex, labelOverride) {
+  const label = labelOverride?.trim() || ctx.skills[skillIndex]?.displayName || ctx.skills[skillIndex]?.relPath || "Skill";
+  const node = createNode(ctx, label, "skill", []);
+  node.skillIndex = skillIndex;
+  return node;
+}
+function collapseSingleChildNodes(nodes) {
+  const collapsed = [];
+  for (const node of nodes) {
+    const next = collapseNode(node);
+    if (next) collapsed.push(next);
+  }
+  return collapsed;
+}
+function collapseNode(node) {
+  node.children = node.children.map(collapseNode).filter(Boolean);
+  if (node.kind !== "heading" && node.kind !== "skill" && node.children.length === 1 && !node.skillIndex) {
+    return node.children[0];
+  }
+  if (node.kind !== "skill" && node.children.length === 0 && !node.skillIndex) {
+    return null;
+  }
+  return node;
+}
+function normalizeLabel(value) {
+  if (!value) return "";
+  return value.replace(/\s+/g, " ").trim();
+}
+function collectLinks(node) {
+  const links = [];
+  const visit = (n) => {
+    if (n.type === "link") {
+      const url = typeof n.url === "string" ? n.url : "";
+      if (url) {
+        links.push({ url, label: toString(n) });
+      }
+      return;
+    }
+    if ("children" in n && Array.isArray(n.children)) {
+      for (const child of n.children) {
+        visit(child);
+      }
+    }
+  };
+  visit(node);
+  return links;
+}
+function isLikelyFilePath(value) {
+  if (!value) return false;
+  const trimmed = value.split("?")[0].split("#")[0];
+  const base = trimmed.split("/").pop() || "";
+  if (!base.includes(".")) return false;
+  const lower = base.toLowerCase();
+  return !lower.endsWith(".md") && !lower.endsWith(".markdown");
+}
+function updateProgress(ctx, current) {
+  if (!ctx.onProgress) return;
+  ctx.onProgress({
+    docsScanned: ctx.docsScanned,
+    linksChecked: ctx.linksChecked,
+    skillsFound: ctx.skillsFound,
+    current,
+    linkLimitReached: ctx.linkLimitReached
+  });
+}
+async function resolveSkillsFromSource(source, displayName, ctx, repoHint) {
+  const cached = ctx.skillCache.get(source);
+  if (cached) return cached;
+  const localIndices = repoHint ? resolveSkillsFromLocal(repoHint, source, displayName, ctx) : [];
+  if (localIndices.length > 0) {
+    ctx.skillCache.set(source, localIndices);
+    return localIndices;
+  }
+  const quickIndex = await tryFetchSkillManifest(source, displayName, ctx);
+  if (quickIndex.length > 0) {
+    ctx.skillCache.set(source, quickIndex);
+    return quickIndex;
+  }
+  let materializedDir;
+  try {
+    const materialized = await materializeSourceToTemp(source);
+    ctx.skillCleanups.push(materialized.cleanup);
+    materializedDir = materialized.dir;
+  } catch {
+    ctx.skillCache.set(source, []);
+    return [];
+  }
+  const skillMd = path2.join(materializedDir, "SKILL.md");
+  if (fs2.existsSync(skillMd)) {
+    const skillIndex = registerSkill(ctx, {
+      relPath: ".",
+      suggestedSource: source,
+      materializedDir,
+      displayName: displayName || deriveDisplayName(source)
+    });
+    const indices2 = [skillIndex];
+    ctx.skillCache.set(source, indices2);
+    return indices2;
+  }
+  const discovered = discoverSkillDirsWithHeuristics(materializedDir, { maxDepth: ctx.maxDepth, maxSkills: ctx.maxSkills });
+  if (discovered.length === 0) {
+    ctx.skillCache.set(source, []);
+    return [];
+  }
+  const indices = [];
+  for (const skill of discovered) {
+    const childSource = deriveChildSource(source, skill.relPath);
+    const skillIndex = registerSkill(ctx, {
+      relPath: skill.relPath,
+      suggestedSource: childSource,
+      materializedDir: skill.absDir,
+      displayName: deriveDisplayName(childSource)
+    });
+    indices.push(skillIndex);
+  }
+  ctx.skillCache.set(source, indices);
+  return indices;
+}
+function resolveSkillsFromLocal(repoHint, source, displayName, ctx) {
+  if (!repoHint.repo.dir) return [];
+  const base = repoHint.pathHint ? path2.join(repoHint.repo.dir, repoHint.pathHint) : repoHint.repo.dir;
+  if (!fs2.existsSync(base)) return [];
+  const skillMd = path2.join(base, "SKILL.md");
+  if (fs2.existsSync(skillMd)) {
+    return [
+      registerSkill(ctx, {
+        relPath: ".",
+        suggestedSource: source,
+        displayName: displayName || deriveDisplayName(source)
+      })
+    ];
+  }
+  const discovered = discoverSkillDirsWithHeuristics(base, { maxDepth: ctx.maxDepth, maxSkills: ctx.maxSkills });
+  if (discovered.length === 0) return [];
+  const indices = [];
+  for (const skill of discovered) {
+    const childSource = deriveChildSource(source, skill.relPath);
+    const skillIndex = registerSkill(ctx, {
+      relPath: skill.relPath,
+      suggestedSource: childSource,
+      displayName: deriveDisplayName(childSource)
+    });
+    indices.push(skillIndex);
+  }
+  return indices;
+}
+async function tryFetchSkillManifest(source, displayName, ctx) {
+  const parsed = parseGitHubSource(source);
+  if (!parsed) return [];
+  const ref = parsed.ref || "HEAD";
+  const pathPrefix = parsed.path ? `${parsed.path.replace(/\/+$/, "")}/` : "";
+  const rawUrl = `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${ref}/${pathPrefix}SKILL.md`;
+  try {
+    const res = await fetchWithTimeout(rawUrl, { method: "GET" }, 5e3);
+    if (!res.ok) {
+      if (res.status === 404) return [];
+      return [];
+    }
+  } catch {
+    return [];
+  }
+  return [
+    registerSkill(ctx, {
+      relPath: ".",
+      suggestedSource: source,
+      displayName: displayName || deriveDisplayName(source)
+    })
+  ];
+}
+function registerSkill(ctx, skill) {
+  const key = skill.suggestedSource;
+  const existing = ctx.skillIndexBySource.get(key);
+  if (existing != null) {
+    if (!ctx.skills[existing].displayName && skill.displayName) {
+      ctx.skills[existing].displayName = skill.displayName;
+    }
+    return existing;
+  }
+  if (ctx.skills.length >= ctx.maxSkills) {
+    ctx.linkLimitReached = true;
+    updateProgress(ctx);
+    return ctx.skills.length - 1;
+  }
+  ctx.skills.push(skill);
+  const index = ctx.skills.length - 1;
+  ctx.skillIndexBySource.set(key, index);
+  ctx.skillsFound = ctx.skills.length;
+  if (ctx.skillsFound >= ctx.maxSkills) {
+    ctx.linkLimitReached = true;
+    updateProgress(ctx);
+  }
+  return index;
+}
+function deriveDisplayName(source) {
+  const clean = source.replace(/[#?].*$/, "");
+  return clean.split("/").filter(Boolean).pop() || source;
+}
+function resolveLink(doc, url) {
+  const trimmed = url.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  if (trimmed.startsWith("mailto:")) return null;
+  const parsed = parseGitHubSource(trimmed);
+  if (parsed) {
+    const source = toRepoSource(parsed);
+    const pathHint = parsed.path;
+    const displayName2 = parsed.path ? parsed.path.split("/").pop() || source : source;
+    const parsedRef = parsed.ref || doc.repo.ref || "HEAD";
+    const docRef = doc.repo.ref || "HEAD";
+    const sameRepo = parsed.owner === doc.repo.owner && parsed.repo === doc.repo.repo && parsedRef === docRef;
+    return { source, displayName: displayName2, pathHint, sameRepo };
+  }
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) return null;
+  const relative = normalizeRepoRelative(trimmed);
+  if (!relative) return null;
+  const baseDir = path2.posix.dirname(doc.docPath);
+  const relativePath = relative.isAbsolute ? path2.posix.normalize(relative.path) : path2.posix.normalize(path2.posix.join(baseDir, relative.path));
+  const resolved = buildRepoSource({
+    owner: doc.repo.owner,
+    repo: doc.repo.repo,
+    ref: doc.repo.ref,
+    path: relativePath.replace(/^\/+/, "")
+  });
+  const displayName = relativePath.split("/").filter(Boolean).pop() || relative.path;
+  return { source: resolved, displayName, pathHint: relativePath, sameRepo: true };
+}
+function normalizeRepoRelative(link) {
+  const cleaned = link.split("#")[0].split("?")[0].trim();
+  if (!cleaned) return null;
+  if (cleaned.startsWith("/")) return { path: cleaned.slice(1), isAbsolute: true };
+  return { path: cleaned, isAbsolute: false };
+}
+function looksLikeMarkdownPath(value) {
+  if (!value) return false;
+  const lower = value.toLowerCase();
+  return lower.endsWith(".md") || lower.endsWith(".markdown") || README_CANDIDATES.some((name) => lower.endsWith(name.toLowerCase()));
+}
+function parseGitHubSource(input) {
+  if (input.includes("github.com") || input.includes("raw.githubusercontent.com")) {
+    try {
+      const url = new URL(input);
+      if (url.hostname === "raw.githubusercontent.com") {
+        const parts2 = url.pathname.split("/").filter(Boolean);
+        if (parts2.length < 4) return null;
+        const [owner2, repo2, ref2, ...rest2] = parts2;
+        return { owner: owner2, repo: repo2.replace(/\.git$/, ""), ref: ref2, path: rest2.join("/"), isFile: true };
+      }
+      if (url.hostname !== "github.com") return null;
+      const parts = url.pathname.split("/").filter(Boolean);
+      if (parts.length < 2) return null;
+      const [owner, repo, type, ref, ...rest] = parts;
+      if (!type) return { owner, repo: repo.replace(/\.git$/, "") };
+      if (type === "tree" || type === "blob") {
+        return { owner, repo: repo.replace(/\.git$/, ""), ref, path: rest.join("/"), isFile: type === "blob" };
+      }
+      return { owner, repo: repo.replace(/\.git$/, ""), path: [type, ref, ...rest].filter(Boolean).join("/") };
+    } catch {
+      return null;
+    }
+  }
+  if (/^[^/]+\/[^/]+/.test(input)) {
+    const [base, ref] = input.split("#", 2);
+    const parts = base.split("/").filter(Boolean);
+    if (parts.length < 2) return null;
+    const [owner, repo, ...rest] = parts;
+    const pathPart = rest.length ? rest.join("/") : void 0;
+    return { owner, repo, ref, path: pathPart, isFile: looksLikeMarkdownPath(pathPart) };
+  }
+  return null;
+}
+function toRepoSource(parsed) {
+  return buildRepoSource(parsed);
+}
+function buildRepoSource(parsed) {
+  const base = `${parsed.owner}/${parsed.repo}${parsed.path ? `/${parsed.path}` : ""}`;
+  return parsed.ref ? `${base}#${parsed.ref}` : base;
+}
+async function resolveMarkdownDoc(source, ctx) {
+  const parsed = parseGitHubSource(source);
+  if (!parsed) return null;
+  const ref = parsed.ref || "HEAD";
+  const repoKey = `${parsed.owner}/${parsed.repo}#${ref}`;
+  let repo = ctx.repoCache.get(repoKey);
+  if (!repo) {
+    repo = { owner: parsed.owner, repo: parsed.repo, ref };
+    ctx.repoCache.set(repoKey, repo);
+  }
+  const targetPath = parsed.path ? parsed.path.replace(/^\/+/, "") : "";
+  if (parsed.isFile || looksLikeMarkdownPath(targetPath)) {
+    const content = await fetchMarkdownContent(repo, targetPath);
+    if (!content) return null;
+    return { repo, docPath: targetPath, content };
+  }
+  const dirPath = targetPath;
+  for (const candidate of README_CANDIDATES) {
+    const docPath = dirPath ? path2.posix.join(dirPath, candidate) : candidate;
+    const content = await fetchMarkdownContent(repo, docPath);
+    if (content) return { repo, docPath, content };
+  }
+  const repoSpec = `${repo.owner}/${repo.repo}#${repo.ref}`;
+  try {
+    const materialized = await materializeSourceToTemp(repoSpec);
+    const localRepo = { ...repo, dir: materialized.dir, cleanup: materialized.cleanup };
+    ctx.repoCache.set(repoKey, localRepo);
+    const localTarget = targetPath;
+    if (parsed.isFile || looksLikeMarkdownPath(localTarget)) {
+      const filePath = path2.join(materialized.dir, localTarget);
+      if (fs2.existsSync(filePath)) return { repo: localRepo, docPath: localTarget, filePath };
+      return null;
+    }
+    for (const candidate of README_CANDIDATES) {
+      const filePath = path2.join(materialized.dir, dirPath, candidate);
+      if (fs2.existsSync(filePath)) {
+        return { repo: localRepo, docPath: path2.posix.join(dirPath, candidate), filePath };
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function fetchMarkdownContent(repo, docPath) {
+  const ref = repo.ref || "HEAD";
+  const rawUrl = `https://raw.githubusercontent.com/${repo.owner}/${repo.repo}/${ref}/${docPath}`;
+  try {
+    const res = await fetchWithTimeout(rawUrl, { method: "GET" }, 5e3);
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/install.ts
 function looksLikeAlias(input) {
   const s = input.trim();
@@ -464,7 +1023,7 @@ function looksLikeAlias(input) {
   if (s.startsWith("@")) return false;
   if (s.includes("/") || s.includes("\\")) return false;
   if (/^https?:\/\//i.test(s) || s.includes("github.com")) return false;
-  if (fs2.existsSync(path2.resolve(s))) return false;
+  if (fs3.existsSync(path3.resolve(s))) return false;
   if (!isValidAlias(s)) return false;
   return true;
 }
@@ -472,6 +1031,21 @@ function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
 }
+function appendCleanup(current, next) {
+  if (!next) return current;
+  if (!current) return next;
+  return () => {
+    current();
+    next();
+  };
+}
+function getInstalledPlatforms(scope) {
+  return PLATFORMS2.filter((platform) => listSkills({ platform, scope }).length > 0);
+}
+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,
@@ -519,6 +1093,7 @@ function createContext(source, options) {
     isSingleSkill: false,
     materializedDir: null,
     cleanupMaterialized: null,
+    markdownTree: null,
     results: [],
     errors: [],
     skipped: [],
@@ -564,10 +1139,10 @@ async function discoverSkills(ctx) {
       ctx.selectedSkills = [{ relPath: resolvedSource, suggestedSource: resolvedSource }];
       return true;
     }
-    const maybeLocalRoot = path2.resolve(resolvedSource);
-    const isLocal = fs2.existsSync(maybeLocalRoot);
+    const maybeLocalRoot = path3.resolve(resolvedSource);
+    const isLocal = fs3.existsSync(maybeLocalRoot);
     if (isLocal) {
-      const hasSkillMd2 = fs2.existsSync(path2.join(maybeLocalRoot, "SKILL.md"));
+      const hasSkillMd2 = fs3.existsSync(path3.join(maybeLocalRoot, "SKILL.md"));
       if (hasSkillMd2) {
         ctx.isSingleSkill = true;
         ctx.selectedSkills = [{ relPath: maybeLocalRoot, suggestedSource: resolvedSource }];
@@ -585,13 +1160,33 @@ async function discoverSkills(ctx) {
         process.exitCode = 1;
         return false;
       }
-      ctx.discoveredSkills = asDiscoveredSkills(discovered2, (d) => path2.join(maybeLocalRoot, d.relPath));
+      ctx.discoveredSkills = asDiscoveredSkills(discovered2, (d) => path3.join(maybeLocalRoot, d.relPath));
       return true;
     }
-    const materialized = await materializeSourceToTemp(resolvedSource);
+    const markdownResult = await discoverMarkdownSkillsFromSource({
+      source: resolvedSource,
+      maxDepth,
+      maxSkills,
+      onProgress: (update2) => {
+        if (ctx.spinner) {
+          const current = update2.current ? ` \xB7 ${update2.current}` : "";
+          const capped = update2.linkLimitReached ? " \xB7 link cap reached" : "";
+          ctx.spinner.text = `Parsing markdown (${update2.docsScanned} docs, ${update2.linksChecked} links, ${update2.skillsFound} skills)${current}${capped}`;
+        }
+      }
+    });
+    if (markdownResult && markdownResult.skills.length > 0) {
+      ctx.discoveredSkills = markdownResult.skills;
+      ctx.markdownTree = markdownResult.tree;
+      ctx.isSingleSkill = markdownResult.skills.length === 1;
+      ctx.selectedSkills = ctx.isSingleSkill ? [markdownResult.skills[0]] : null;
+      ctx.cleanupMaterialized = appendCleanup(ctx.cleanupMaterialized, markdownResult.cleanup);
+      return true;
+    }
+    const materialized = await materializeSourceToTemp2(resolvedSource);
     ctx.materializedDir = materialized.dir;
-    ctx.cleanupMaterialized = materialized.cleanup;
-    const hasSkillMd = fs2.existsSync(path2.join(ctx.materializedDir, "SKILL.md"));
+    ctx.cleanupMaterialized = appendCleanup(ctx.cleanupMaterialized, materialized.cleanup);
+    const hasSkillMd = fs3.existsSync(path3.join(ctx.materializedDir, "SKILL.md"));
     if (hasSkillMd) {
       ctx.isSingleSkill = true;
       ctx.selectedSkills = [{ relPath: ".", suggestedSource: resolvedSource, materializedDir: ctx.materializedDir }];
@@ -611,7 +1206,7 @@ async function discoverSkills(ctx) {
     }
     ctx.discoveredSkills = asDiscoveredSkills(
       discovered,
-      (d) => deriveChildSource(resolvedSource, d.relPath),
+      (d) => deriveChildSource2(resolvedSource, d.relPath),
       (d) => d.absDir
     );
     return true;
@@ -631,7 +1226,10 @@ async function promptSelections(ctx) {
   if (isSingleSkill) {
     if (ctx.needsPlatformPrompt) {
       if (ctx.spinner) ctx.spinner.stop();
-      const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
+      const selectedPlatforms = await promptPlatformsInteractive({
+        defaultAll: true,
+        platforms: getPlatformPromptList(ctx.scope)
+      });
       if (!selectedPlatforms) {
         console.log(chalk3.red("No platforms selected."));
         process.exitCode = 1;
@@ -685,7 +1283,7 @@ async function promptSelections(ctx) {
 `;
       console.log(chalk3.yellow(headline));
     }
-    const selected = await promptSkillsInteractive(discoveredSkills, { defaultAll: true });
+    const selected = ctx.markdownTree ? await promptSkillsTreeInteractive(discoveredSkills, ctx.markdownTree, { defaultAll: true }) : await promptSkillsInteractive(discoveredSkills, { defaultAll: true });
     if (!selected) {
       console.log(chalk3.red("No skills selected."));
       process.exitCode = 1;
@@ -693,7 +1291,10 @@ async function promptSelections(ctx) {
     }
     ctx.selectedSkills = selected;
     if (ctx.needsPlatformPrompt) {
-      const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
+      const selectedPlatforms = await promptPlatformsInteractive({
+        defaultAll: true,
+        platforms: getPlatformPromptList(ctx.scope)
+      });
       if (!selectedPlatforms) {
         console.log(chalk3.red("No platforms selected."));
         process.exitCode = 1;
@@ -905,7 +1506,7 @@ async function reportDownload(record, registryOverride) {
     } else {
       return;
     }
-    await fetchWithTimeout(
+    await fetchWithTimeout2(
       endpoint,
       {
         method: "POST",
@@ -920,7 +1521,7 @@ async function reportDownload(record, registryOverride) {
 
 // src/commands/list.ts
 import chalk4 from "chalk";
-import { PLATFORMS as PLATFORMS3, listAllSkills, listSkills } from "@skild/core";
+import { PLATFORMS as PLATFORMS3, listAllSkills, listSkills as listSkills2 } from "@skild/core";
 function isSkillset(skill) {
   return Boolean(skill.record?.skillset || skill.record?.skill?.frontmatter?.skillset);
 }
@@ -1019,7 +1620,7 @@ async function list(options = {}) {
   const verbose = Boolean(options.verbose);
   const platform = options.target;
   if (platform) {
-    const skills = listSkills({ platform, scope });
+    const skills = listSkills2({ platform, scope });
     if (options.json) {
       console.log(JSON.stringify(skills, null, 2));
       return;
@@ -1185,7 +1786,7 @@ async function init(name, options = {}) {
 
 // src/commands/signup.ts
 import chalk10 from "chalk";
-import { fetchWithTimeout as fetchWithTimeout2, resolveRegistryUrl as resolveRegistryUrl2, SkildError as SkildError6 } from "@skild/core";
+import { fetchWithTimeout as fetchWithTimeout3, resolveRegistryUrl as resolveRegistryUrl2, SkildError as SkildError6 } from "@skild/core";
 
 // src/utils/prompt.ts
 import readline2 from "readline";
@@ -1273,7 +1874,7 @@ async function signup(options) {
   }
   let text = "";
   try {
-    const res = await fetchWithTimeout2(
+    const res = await fetchWithTimeout3(
       `${registry}/auth/signup`,
       {
         method: "POST",
@@ -1325,7 +1926,7 @@ async function signup(options) {
 
 // src/commands/login.ts
 import chalk11 from "chalk";
-import { fetchWithTimeout as fetchWithTimeout3, resolveRegistryUrl as resolveRegistryUrl3, saveRegistryAuth, SkildError as SkildError7 } from "@skild/core";
+import { fetchWithTimeout as fetchWithTimeout4, resolveRegistryUrl as resolveRegistryUrl3, saveRegistryAuth, SkildError as SkildError7 } from "@skild/core";
 async function login(options) {
   const registry = resolveRegistryUrl3(options.registry);
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -1352,7 +1953,7 @@ async function login(options) {
   const finalTokenName = options.tokenName?.trim() || void 0;
   let text = "";
   try {
-    const res = await fetchWithTimeout3(
+    const res = await fetchWithTimeout4(
       `${registry}/auth/login`,
       {
         method: "POST",
@@ -1406,7 +2007,7 @@ async function logout() {
 
 // src/commands/whoami.ts
 import chalk13 from "chalk";
-import { fetchWithTimeout as fetchWithTimeout4, loadRegistryAuth as loadRegistryAuth2, resolveRegistryUrl as resolveRegistryUrl4, SkildError as SkildError8 } from "@skild/core";
+import { fetchWithTimeout as fetchWithTimeout5, loadRegistryAuth as loadRegistryAuth2, resolveRegistryUrl as resolveRegistryUrl4, SkildError as SkildError8 } from "@skild/core";
 async function whoami() {
   const auth = loadRegistryAuth2();
   if (!auth) {
@@ -1416,7 +2017,7 @@ async function whoami() {
   }
   const registryUrl = resolveRegistryUrl4(auth.registryUrl);
   try {
-    const res = await fetchWithTimeout4(
+    const res = await fetchWithTimeout5(
       `${registryUrl}/auth/me`,
       { headers: { authorization: `Bearer ${auth.token}`, accept: "application/json" } },
       5e3
@@ -1438,13 +2039,13 @@ async function whoami() {
 }
 
 // src/commands/publish.ts
-import fs3 from "fs";
+import fs4 from "fs";
 import os from "os";
-import path3 from "path";
+import path4 from "path";
 import crypto from "crypto";
 import * as tar from "tar";
 import chalk14 from "chalk";
-import { assertValidAlias, fetchWithTimeout as fetchWithTimeout5, loadRegistryAuth as loadRegistryAuth3, normalizeAlias, resolveRegistryUrl as resolveRegistryUrl5, SkildError as SkildError9, splitCanonicalName, validateSkillDir } from "@skild/core";
+import { assertValidAlias, fetchWithTimeout as fetchWithTimeout6, loadRegistryAuth as loadRegistryAuth3, normalizeAlias, resolveRegistryUrl as resolveRegistryUrl5, SkildError as SkildError9, splitCanonicalName, validateSkillDir } from "@skild/core";
 function sha256Hex(buf) {
   const h = crypto.createHash("sha256");
   h.update(buf);
@@ -1463,7 +2064,7 @@ async function publish(options = {}) {
     process.exitCode = 1;
     return;
   }
-  const dir = path3.resolve(options.dir || process.cwd());
+  const dir = path4.resolve(options.dir || process.cwd());
   const validation = validateSkillDir(dir);
   if (!validation.ok) {
     console.error(chalk14.red("Skill validation failed:"));
@@ -1492,7 +2093,7 @@ async function publish(options = {}) {
       process.exitCode = 1;
       return;
     }
-    const meRes = await fetchWithTimeout5(
+    const meRes = await fetchWithTimeout6(
       `${registry}/auth/me`,
       { headers: { authorization: `Bearer ${token}` } },
       1e4
@@ -1533,8 +2134,8 @@ async function publish(options = {}) {
     }
   }
   const spinner = createSpinner(`Publishing ${chalk14.cyan(`${name}@${version2}`)} to ${chalk14.dim(registry)}...`);
-  const tempDir = fs3.mkdtempSync(path3.join(os.tmpdir(), "skild-publish-"));
-  const tarballPath = path3.join(tempDir, "skill.tgz");
+  const tempDir = fs4.mkdtempSync(path4.join(os.tmpdir(), "skild-publish-"));
+  const tarballPath = path4.join(tempDir, "skill.tgz");
   try {
     await tar.c(
       {
@@ -1546,7 +2147,7 @@ async function publish(options = {}) {
       },
       ["."]
     );
-    const buf = fs3.readFileSync(tarballPath);
+    const buf = fs4.readFileSync(tarballPath);
     const integrity = sha256Hex(buf);
     const form = new FormData();
     form.set("version", version2);
@@ -1557,7 +2158,7 @@ async function publish(options = {}) {
     form.set("dependencies", JSON.stringify(dependencies));
     form.append("tarball", new Blob([buf], { type: "application/gzip" }), "skill.tgz");
     const { scope, name: skillName } = splitCanonicalName(name);
-    const res = await fetchWithTimeout5(
+    const res = await fetchWithTimeout6(
       `${registry}/skills/${encodeURIComponent(scope)}/${encodeURIComponent(skillName)}/publish`,
       {
         method: "POST",
@@ -1575,7 +2176,7 @@ async function publish(options = {}) {
     }
     if (alias) {
       spinner.text = `Publishing ${chalk14.cyan(`${name}@${version2}`)} \u2014 setting alias ${chalk14.cyan(alias)}...`;
-      const aliasRes = await fetchWithTimeout5(
+      const aliasRes = await fetchWithTimeout6(
         `${registry}/publisher/skills/${encodeURIComponent(scope)}/${encodeURIComponent(skillName)}/alias`,
         {
           method: "POST",
@@ -1613,7 +2214,7 @@ async function publish(options = {}) {
     console.error(chalk14.red(message));
     process.exitCode = 1;
   } finally {
-    fs3.rmSync(tempDir, { recursive: true, force: true });
+    fs4.rmSync(tempDir, { recursive: true, force: true });
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skild",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "The npm for Agent Skills — Discover, install, manage, and publish AI Agent Skills with ease.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,11 +36,15 @@
     "@inquirer/prompts": "^8.2.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
+    "mdast-util-to-string": "^4.0.0",
     "ora": "^8.0.1",
+    "remark-parse": "^11.0.0",
     "tar": "^7.4.3",
+    "unified": "^11.0.4",
     "@skild/core": "^0.5.2"
   },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^20.10.0",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0"