@viren/claude-code-dashboard 0.0.1

package/src/markdown.mjs

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { BOILERPLATE_RE } from "./constants.mjs";
+
+export function getDescFromContent(content) {
+  const lines = content.split("\n");
+
+  // YAML frontmatter
+  if (lines[0] === "---") {
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i] === "---") break;
+      const m = lines[i].match(/^description:\s*(.+)/);
+      if (m) return m[1].trim();
+    }
+  }
+
+  if (lines[0]?.startsWith("# ")) return lines[0].slice(2);
+
+  // First non-empty, non-frontmatter line
+  for (const l of lines.slice(0, 5)) {
+    const t = l.trim();
+    if (t && t !== "---" && !t.startsWith("```")) {
+      return t.length > 60 ? t.slice(0, 57) + "..." : t;
+    }
+  }
+  return "";
+}
+
+export function getDesc(filepath) {
+  try {
+    return getDescFromContent(readFileSync(filepath, "utf8"));
+  } catch {
+    return "";
+  }
+}
+
+export function extractProjectDesc(filepath) {
+  let lines;
+  try {
+    lines = readFileSync(filepath, "utf8").split("\n");
+  } catch {
+    return [];
+  }
+
+  const result = [];
+  let inCode = false;
+  let foundContent = false;
+
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCode = !inCode;
+      continue;
+    }
+    if (inCode) continue;
+    if (line.startsWith("# ") && result.length === 0) continue;
+    if (!line.trim() && !foundContent) continue;
+    if (line.startsWith("## ") && foundContent) break;
+    if (line.startsWith("## ") && !foundContent) continue;
+    if (BOILERPLATE_RE.test(line)) continue;
+    if (/^[^#|`]/.test(line) && line.trim().length > 5) {
+      foundContent = true;
+      result.push(line.replace(/\*\*/g, "").replace(/`/g, ""));
+      if (result.length >= 2) break;
+    }
+  }
+  return result;
+}
+
+export function extractSections(filepath) {
+  let lines;
+  try {
+    lines = readFileSync(filepath, "utf8").split("\n");
+  } catch {
+    return [];
+  }
+
+  const sections = [];
+  let current = null;
+  let inCode = false;
+
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      inCode = !inCode;
+      continue;
+    }
+    if (inCode) continue;
+
+    if (line.startsWith("## ")) {
+      current = { name: line.slice(3), preview: [] };
+      sections.push(current);
+      continue;
+    }
+    if (current && current.preview.length < 3 && !line.startsWith("#") && line.trim()) {
+      let cleaned = line.replace(/\*\*/g, "").replace(/`/g, "").replace(/^- /, "");
+      if (cleaned.trim().length > 2) {
+        if (cleaned.length > 80) cleaned = cleaned.slice(0, 77) + "...";
+        current.preview.push(cleaned.trim());
+      }
+    }
+  }
+  return sections;
+}
+
+export function extractSteps(filepath) {
+  let lines;
+  try {
+    lines = readFileSync(filepath, "utf8").split("\n");
+  } catch {
+    return [];
+  }
+
+  const steps = [];
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      steps.push({ type: "section", text: line.slice(3) });
+    } else if (/^\d+\. /.test(line)) {
+      steps.push({ type: "step", text: line.replace(/^\d+\. /, "").replace(/\*\*/g, "") });
+    } else if (line.startsWith("- **")) {
+      const m = line.match(/^- \*\*([^*]+)\*\*/);
+      if (m) steps.push({ type: "key", text: m[1] });
+    }
+    if (steps.length >= 12) break;
+  }
+  return steps;
+}
+
+export function scanMdDir(dir) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  try {
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".md")) continue;
+      const full = join(dir, f);
+      const name = f.slice(0, -3);
+      const desc = getDesc(full);
+      results.push({ name, desc: desc || "No description", filepath: full });
+    }
+  } catch {
+    /* directory unreadable */
+  }
+  return results.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/mcp.mjs

@@ -0,0 +1,86 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+
+export function parseUserMcpConfig(content) {
+  try {
+    const data = JSON.parse(content);
+    const servers = [];
+    const mcpServers = data.mcpServers || {};
+    for (const [name, cfg] of Object.entries(mcpServers)) {
+      const type = cfg.type || (cfg.command ? "stdio" : cfg.url ? "http" : "unknown");
+      servers.push({ name, type, scope: "user", source: "~/.claude/mcp_config.json" });
+    }
+    return servers;
+  } catch {
+    return [];
+  }
+}
+
+export function parseProjectMcpConfig(content, repoPath) {
+  try {
+    const data = JSON.parse(content);
+    const servers = [];
+    const mcpServers = data.mcpServers || {};
+    for (const [name, cfg] of Object.entries(mcpServers)) {
+      const type = cfg.type || (cfg.command ? "stdio" : cfg.url ? "http" : "unknown");
+      servers.push({ name, type, scope: "project", source: repoPath });
+    }
+    return servers;
+  } catch {
+    return [];
+  }
+}
+
+export function findPromotionCandidates(servers) {
+  const userLevel = new Set(servers.filter((s) => s.scope === "user").map((s) => s.name));
+  const projectServers = servers.filter((s) => s.scope === "project");
+  const byName = {};
+  for (const s of projectServers) {
+    if (userLevel.has(s.name)) continue;
+    if (!byName[s.name]) byName[s.name] = new Set();
+    byName[s.name].add(s.source);
+  }
+  return Object.entries(byName)
+    .filter(([, projects]) => projects.size >= 2)
+    .map(([name, projects]) => ({ name, projects: [...projects].sort() }))
+    .sort((a, b) => b.projects.length - a.projects.length || a.name.localeCompare(b.name));
+}
+
+export function scanHistoricalMcpServers(claudeDir) {
+  const historical = new Set();
+  const fileHistoryDir = join(claudeDir, "file-history");
+  if (!existsSync(fileHistoryDir)) return [];
+  const MAX_SESSION_DIRS = 200;
+  const MAX_FILES_TOTAL = 1000;
+  let filesRead = 0;
+  try {
+    const sessionDirs = readdirSync(fileHistoryDir).sort().slice(-MAX_SESSION_DIRS);
+    for (const sessionDir of sessionDirs) {
+      if (filesRead >= MAX_FILES_TOTAL) break;
+      const sessionPath = join(fileHistoryDir, sessionDir);
+      if (!statSync(sessionPath).isDirectory()) continue;
+      try {
+        for (const snapFile of readdirSync(sessionPath)) {
+          if (filesRead >= MAX_FILES_TOTAL) break;
+          filesRead++;
+          const snapPath = join(sessionPath, snapFile);
+          try {
+            const content = readFileSync(snapPath, "utf8");
+            if (!content.includes("mcpServers")) continue;
+            const data = JSON.parse(content);
+            for (const name of Object.keys(data.mcpServers || {})) {
+              historical.add(name);
+            }
+          } catch {
+            /* skip malformed */
+          }
+        }
+      } catch {
+        /* skip unreadable session dir */
+      }
+    }
+  } catch {
+    /* skip unreadable file-history dir */
+  }
+  return [...historical];
+}

package/src/render.mjs

@@ -0,0 +1,264 @@
+import { esc } from "./helpers.mjs";
+import { extractSteps, extractSections } from "./markdown.mjs";
+import { groupSkillsByCategory } from "./skills.mjs";
+
+export function renderSections(sections) {
+  return sections
+    .map(
+      (s) =>
+        `<details class="agent-section"><summary>${esc(s.name)}</summary>` +
+        (s.preview.length
+          ? `<div class="agent-section-preview">${s.preview.map((l) => `<div class="line">${esc(l)}</div>`).join("")}</div>`
+          : "") +
+        `</details>`,
+    )
+    .join("");
+}
+
+export function renderCmd(cmd, prefix = "/") {
+  const steps = extractSteps(cmd.filepath);
+  const d = esc(cmd.desc);
+  if (steps.length) {
+    const body = steps.map((s) => `<div class="detail-${s.type}">${esc(s.text)}</div>`).join("");
+    return `<details class="cmd-detail"><summary><span class="cmd-name">${prefix}${esc(cmd.name)}</span><span class="cmd-desc">${d}</span></summary><div class="detail-body">${body}</div></details>`;
+  }
+  return `<div class="cmd-row"><span class="cmd-name">${prefix}${esc(cmd.name)}</span><span class="cmd-desc">${d}</span></div>`;
+}
+
+export function renderRule(rule) {
+  const sections = extractSections(rule.filepath);
+  const d = esc(rule.desc);
+  if (sections.length) {
+    return `<details class="cmd-detail"><summary><span class="cmd-name">${esc(rule.name)}</span><span class="cmd-desc">${d}</span></summary><div class="detail-body">${renderSections(sections)}</div></details>`;
+  }
+  return `<div class="cmd-row"><span class="cmd-name">${esc(rule.name)}</span><span class="cmd-desc">${d}</span></div>`;
+}
+
+export function sourceBadgeHtml(source) {
+  if (!source) return "";
+  switch (source.type) {
+    case "superpowers":
+      return `<span class="badge source superpowers">superpowers</span>`;
+    case "skills.sh": {
+      const label = source.repo ? `skills.sh &middot; ${esc(source.repo)}` : "skills.sh";
+      return `<span class="badge source skillssh">${label}</span>`;
+    }
+    default:
+      return `<span class="badge source custom">custom</span>`;
+  }
+}
+
+export function renderSkill(skill) {
+  const sections = extractSections(skill.filepath);
+  const d = esc(skill.desc);
+  const badge = sourceBadgeHtml(skill.source);
+  if (sections.length) {
+    return `<details class="cmd-detail"><summary><span class="cmd-name skill-name">${esc(skill.name)}</span>${badge}<span class="cmd-desc">${d}</span></summary><div class="detail-body">${renderSections(sections)}</div></details>`;
+  }
+  return `<div class="cmd-row"><span class="cmd-name skill-name">${esc(skill.name)}</span>${badge}<span class="cmd-desc">${d}</span></div>`;
+}
+
+// Re-export from skills.mjs (single source of truth)
+export { groupSkillsByCategory };
+
+export function renderBadges(repo) {
+  const b = [];
+  if (repo.commands.length) b.push(`<span class="badge cmds">${repo.commands.length} cmd</span>`);
+  if (repo.rules.length) b.push(`<span class="badge rules">${repo.rules.length} rules</span>`);
+  if (repo.sections.length)
+    b.push(`<span class="badge agent">${repo.sections.length} sections</span>`);
+  if (repo.techStack && repo.techStack.length)
+    b.push(`<span class="badge stack">${esc(repo.techStack.join(", "))}</span>`);
+  return b.join("");
+}
+
+export function healthScoreColor(score) {
+  if (score >= 80) return "var(--green)";
+  if (score >= 50) return "var(--yellow)";
+  return "var(--red)";
+}
+
+export function renderHealthBar(repo) {
+  if (repo.healthScore === undefined) return "";
+  const s = Math.max(0, Math.min(100, repo.healthScore || 0));
+  const color = healthScoreColor(s);
+  return `<div class="health-bar"><div class="health-fill" style="width:${s}%;background:${color}"></div><span class="health-label">${s}</span></div>`;
+}
+
+export function renderDriftIndicator(repo) {
+  if (!repo.drift || repo.drift.level === "unknown" || repo.drift.level === "synced") return "";
+  const cls = `drift-${esc(repo.drift.level)}`;
+  const n = Number(repo.drift.commitsSince) || 0;
+  return `<span class="drift ${cls}" title="${n} commits since config update">${n}&#8203;&#916;</span>`;
+}
+
+export function renderRepoCard(repo) {
+  const badges = renderBadges(repo);
+  const preview = repo.desc[0] ? esc(repo.desc[0].slice(0, 120)) : "";
+  const drift = renderDriftIndicator(repo);
+
+  let body = "";
+
+  body += `<div class="repo-meta"><span class="repo-path">${esc(repo.shortPath)}</span>`;
+  body += `<span class="freshness ${repo.freshnessClass}">${esc(repo.freshnessText)}${drift}</span></div>`;
+
+  body += renderHealthBar(repo);
+
+  if (repo.desc.length) {
+    body += `<div class="repo-desc">${repo.desc.map((l) => esc(l)).join("<br>")}</div>`;
+  }
+
+  if (repo.healthReasons && repo.healthReasons.length) {
+    body += `<div class="label">Quick Wins</div>`;
+    body += `<div class="quick-wins">${repo.healthReasons.map((r) => `<span class="quick-win">${esc(r)}</span>`).join("")}</div>`;
+  }
+
+  if (repo.commands.length) {
+    body += `<div class="label">Commands</div>`;
+    body += repo.commands.map((c) => renderCmd(c)).join("");
+  }
+
+  if (repo.rules.length) {
+    body += `<div class="label">Rules</div>`;
+    body += repo.rules.map((r) => renderRule(r)).join("");
+  }
+
+  if (repo.matchedSkills && repo.matchedSkills.length) {
+    body += `<div class="label">Relevant Skills</div>`;
+    body += `<div class="matched-skills">${repo.matchedSkills
+      .map((m) => `<span class="matched-skill">${esc(m.name)}</span>`)
+      .join("")}</div>`;
+  }
+
+  if (repo.sections.length) {
+    body += `<div class="label">Agent Config</div>`;
+    body += renderSections(repo.sections);
+  }
+
+  const parent = repo.shortPath.split("/").slice(0, -1).join("/");
+
+  return `<details class="repo-card" data-name="${esc(repo.name)}" data-path="${esc(repo.shortPath)}" data-stack="${esc((repo.techStack || []).join(","))}" data-parent="${esc(parent)}">
+  <summary>
+    <div class="repo-header">
+      <div class="repo-name">${esc(repo.name)}<span class="freshness-dot ${repo.freshnessClass}"></span></div>
+    </div>
+    ${preview ? `<div class="repo-preview">${preview}</div>` : ""}
+    ${badges ? `<div class="badges">${badges}</div>` : ""}
+  </summary>
+  <div class="repo-body">${body}</div>
+</details>`;
+}
+
+export function generateCatalogHtml(groups, totalCount, ts) {
+  let cards = "";
+  for (const [cat, skills] of Object.entries(groups)) {
+    const heading = cat.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    let rows = "";
+    for (const s of skills) {
+      const badge = sourceBadgeHtml(s.source);
+      let hint = "";
+      if (s.source) {
+        switch (s.source.type) {
+          case "superpowers":
+            hint = "Included with superpowers-skills";
+            break;
+          case "skills.sh":
+            hint = s.source.repo
+              ? `Installed via skills.sh (${esc(s.source.repo)})`
+              : "Installed via skills.sh";
+            break;
+          default:
+            hint = `Custom skill — copy from ~/.claude/skills/${esc(s.name)}/`;
+        }
+      }
+      rows += `
+      <div class="cat-skill">
+        <div class="cat-skill-head">
+          <span class="cat-skill-name">${esc(s.name)}</span>${badge}
+        </div>
+        <div class="cat-skill-desc">${esc(s.desc)}</div>
+        ${hint ? `<div class="cat-skill-hint">${hint}</div>` : ""}
+      </div>`;
+    }
+    cards += `
+    <section class="cat-group">
+      <h2>${esc(heading)} <span class="cat-n">${skills.length}</span></h2>
+      ${rows}
+    </section>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Claude Code Skill Catalog</title>
+<style>
+  :root {
+    --bg: #0a0a0a; --surface: #111; --surface2: #1a1a1a; --border: #262626;
+    --text: #e5e5e5; --text-dim: #777; --accent: #c4956a; --accent-dim: #8b6a4a;
+    --green: #4ade80; --blue: #60a5fa; --purple: #a78bfa; --yellow: #fbbf24;
+    --red: #f87171;
+  }
+  [data-theme="light"] {
+    --bg: #f5f5f5; --surface: #fff; --surface2: #f0f0f0; --border: #e0e0e0;
+    --text: #1a1a1a; --text-dim: #666; --accent: #9b6b47; --accent-dim: #b8956e;
+    --green: #16a34a; --blue: #2563eb; --purple: #7c3aed; --yellow: #ca8a04;
+    --red: #dc2626;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Text', sans-serif;
+    background: var(--bg); color: var(--text);
+    padding: 2.5rem 2rem; line-height: 1.5; max-width: 900px; margin: 0 auto;
+  }
+  code { font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', monospace; }
+  h1 { font-size: 1.4rem; font-weight: 600; color: var(--accent); margin-bottom: .2rem; }
+  .sub { color: var(--text-dim); font-size: .78rem; margin-bottom: 2rem; }
+  .cat-group { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 1.25rem; margin-bottom: 1.25rem; }
+  .cat-group h2 { font-size: .7rem; font-weight: 700; text-transform: uppercase; letter-spacing: .08em; color: var(--text-dim); margin-bottom: .75rem; display: flex; align-items: center; gap: .5rem; }
+  .cat-n { background: var(--surface2); border: 1px solid var(--border); border-radius: 4px; padding: .05rem .35rem; font-size: .65rem; color: var(--accent); }
+  .cat-skill { padding: .5rem .25rem; border-bottom: 1px solid var(--border); }
+  .cat-skill:last-child { border-bottom: none; }
+  .cat-skill-head { display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+  .cat-skill-name { font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', monospace; font-weight: 600; color: var(--yellow); font-size: .82rem; }
+  .cat-skill-desc { color: var(--text-dim); font-size: .75rem; margin-top: .15rem; }
+  .cat-skill-hint { font-size: .65rem; color: var(--blue); margin-top: .2rem; opacity: .8; }
+  .badge { font-size: .55rem; padding: .1rem .35rem; border-radius: 3px; font-weight: 600; }
+  .badge.source.superpowers { background: rgba(167,139,250,.1); border: 1px solid rgba(167,139,250,.2); color: var(--purple); }
+  .badge.source.skillssh { background: rgba(96,165,250,.1); border: 1px solid rgba(96,165,250,.2); color: var(--blue); }
+  .badge.source.custom { background: rgba(251,191,36,.1); border: 1px solid rgba(251,191,36,.2); color: var(--yellow); }
+  @media (max-width: 600px) { body { padding: 1.5rem 1rem; } }
+  .theme-toggle {
+    position: fixed; top: 1rem; right: 1rem; z-index: 100;
+    background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
+    padding: .4rem .6rem; cursor: pointer; color: var(--text-dim); font-size: .75rem;
+    transition: background .15s, border-color .15s;
+  }
+  .theme-toggle:hover { border-color: var(--accent-dim); }
+  .theme-icon::before { content: "\\263E"; }
+  [data-theme="light"] .theme-icon::before { content: "\\2600"; }
+</style>
+</head>
+<body>
+<h1>Claude Code Skill Catalog</h1>
+<button id="theme-toggle" class="theme-toggle" title="Toggle light/dark mode" aria-label="Toggle theme"><span class="theme-icon"></span></button>
+<div class="sub">${totalCount} skills &middot; generated ${esc(ts)}</div>
+${cards}
+<script>
+var toggle = document.getElementById('theme-toggle');
+var saved = localStorage.getItem('ccd-theme');
+if (saved) document.documentElement.setAttribute('data-theme', saved);
+else if (window.matchMedia('(prefers-color-scheme: light)').matches) {
+  document.documentElement.setAttribute('data-theme', 'light');
+}
+toggle.addEventListener('click', function() {
+  var current = document.documentElement.getAttribute('data-theme');
+  var next = current === 'light' ? 'dark' : 'light';
+  document.documentElement.setAttribute('data-theme', next);
+  localStorage.setItem('ccd-theme', next);
+});
+</script>
+</body>
+</html>`;
+}

package/src/skills.mjs

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync, lstatSync, readlinkSync } from "fs";
+import { join } from "path";
+import { HOME, SKILL_CATEGORIES, CATEGORY_ORDER } from "./constants.mjs";
+import { gitCmd } from "./helpers.mjs";
+import { getDescFromContent } from "./markdown.mjs";
+
+/**
+ * Detect where a skill was sourced from:
+ * - "superpowers" — tracked in the obra/superpowers-skills git repo
+ * - "skills.sh" — installed via skills.sh, symlinked from ~/.agents/skills/
+ * - "custom" — user-created, not tracked by any known source
+ */
+export function detectSkillSource(skillName, skillsDir) {
+  const skillPath = join(skillsDir, skillName);
+
+  // 1. Check if it's a symlink → skills.sh
+  try {
+    const stat = lstatSync(skillPath);
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(skillPath);
+      if (target.includes(".agents/skills") || target.includes(".agents\\skills")) {
+        // Try to read source info from skill-lock.json
+        const lockPath = join(HOME, ".agents", ".skill-lock.json");
+        if (existsSync(lockPath)) {
+          try {
+            const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+            const entry = lock.skills?.[skillName];
+            if (entry) {
+              return {
+                type: "skills.sh",
+                repo: entry.source || "",
+                url: (entry.sourceUrl || "").replace(/\.git$/, ""),
+              };
+            }
+          } catch {
+            /* malformed JSON */
+          }
+        }
+        return { type: "skills.sh" };
+      }
+    }
+  } catch {
+    /* not a symlink or unreadable */
+  }
+
+  // 2. Check if it comes from the git repo (e.g. obra/superpowers-skills)
+  if (existsSync(join(skillsDir, ".git"))) {
+    const remote = gitCmd(skillsDir, "remote", "get-url", "origin");
+    if (remote) {
+      const tracked = gitCmd(skillsDir, "ls-tree", "--name-only", "HEAD:skills/");
+      if (tracked) {
+        const trackedNames = new Set(tracked.split("\n").filter(Boolean));
+        if (trackedNames.has(skillName)) {
+          const repoSlug = remote.replace(/\.git$/, "").replace(/^https?:\/\/github\.com\//, "");
+          return {
+            type: "superpowers",
+            repo: repoSlug,
+            url: remote.replace(/\.git$/, ""),
+          };
+        }
+      }
+    }
+  }
+
+  // 3. Fallback: custom
+  return { type: "custom" };
+}
+
+/** Categorize a skill based on its name and description content. */
+export function categorizeSkill(name, content) {
+  const nameLower = name.toLowerCase();
+  const contentLower = content.toLowerCase();
+  let bestCategory = "workflow";
+  let bestScore = 0;
+
+  for (const [category, keywords] of Object.entries(SKILL_CATEGORIES)) {
+    // Name matches get 3x weight since the name is the strongest signal
+    const nameScore = keywords.reduce((sum, kw) => sum + (nameLower.includes(kw) ? 3 : 0), 0);
+    const contentScore = keywords.reduce((sum, kw) => sum + (contentLower.includes(kw) ? 1 : 0), 0);
+    const score = nameScore + contentScore;
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = category;
+    }
+  }
+  return bestCategory;
+}
+
+/** Scan ~/.claude/skills/ — each subdirectory with a SKILL.md is a skill. */
+export function scanSkillsDir(dir) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      const skillFile = join(dir, entry, "SKILL.md");
+      if (!existsSync(skillFile)) continue;
+      let content = "";
+      try {
+        content = readFileSync(skillFile, "utf8");
+      } catch {
+        /* unreadable */
+      }
+      const desc = getDescFromContent(content);
+      const source = detectSkillSource(entry, dir);
+      const category = categorizeSkill(entry, content);
+      results.push({
+        name: entry,
+        desc: desc || "No description",
+        filepath: skillFile,
+        source,
+        category,
+      });
+    }
+  } catch {
+    /* directory unreadable */
+  }
+  return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function groupSkillsByCategory(skills) {
+  const groups = {};
+  for (const cat of CATEGORY_ORDER) {
+    groups[cat] = [];
+  }
+  for (const skill of skills) {
+    const cat = skill.category || "workflow";
+    if (!groups[cat]) groups[cat] = [];
+    groups[cat].push(skill);
+  }
+  // Remove empty categories
+  for (const cat of Object.keys(groups)) {
+    if (groups[cat].length === 0) delete groups[cat];
+  }
+  return groups;
+}