@minhpnq1807/contextos 0.5.39 → 0.5.41

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.41
+
+- **Interactive community skill installer (`ctx skills`):** Replaced the info-only display with a fully functional multi-select installer. Users can now toggle multiple community library sources with `Space`, confirm with `Enter`, and the CLI automatically runs the appropriate install command for each selected source (`npx`, `git clone`, etc.).
+- **Compact selection UI with URL hints:** The skill source picker now shows a clean box-styled header and each option displays its GitHub URL as a dimmed sub-line hint, matching the `◇ / │` visual language used throughout contextOS.
+- **Prefixed install output (`runPrefixed`):** All child-process output during installation (including interactive npx prompts like "Ok to proceed?") is piped through a line-by-line prefixer that prepends `│  ` to every line. This keeps the visual box style consistent and prevents raw command output from breaking the layout. `stdin` remains inherited so users can still answer interactive prompts.
+- **`multiSelect` hint support:** The multi-select component now accepts an optional `hint` property on each option, rendered as a dimmed indented line below the label. Used for URLs but available for any contextual sub-text.
+- **Library install metadata:** `skill-library.js` now exports `getInstallCommands(libraryId)` returning structured install info (command, verify step, type) for each library source, keeping install logic out of the main CLI.
+
+## 0.5.40
+
+- **Update notifier:** `ctx` now checks npm for newer versions in the background (once per day, 3s timeout). If a newer release exists, a boxed notice is printed at the very end of any command: `Update available: 0.5.39 → 0.5.40`. Check result is cached in `$CONTEXTOS_DATA/.update-check.json` to avoid repeated network calls.
+- **Community skill library browser (`ctx skills`):** New command to browse curated skill libraries from the community. Fetches and parses README files from 4 sources:
+  - [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) — 1,400+ universal skills
+  - [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Claude Code skills & workflows
+  - [awesome-codex-skills](https://github.com/ComposioHQ/awesome-codex-skills) — Codex CLI skills & automations
+  - [awesome-copilot](https://github.com/github/awesome-copilot) — GitHub Copilot instructions & agents
+  Results are cached for 24 hours. Use `--agents <names>` to filter and `--refresh` to force refetch.
+- **Post-install skill recommendations:** After interactive `ctx install` or `ctx setup`, a styled recommendation panel shows top 5 skills from each relevant library with descriptions and repo URLs. This guides new users toward useful community skills immediately after setup.
+- **Test stability:** Increased timeout for MCP bridge fallback test to prevent CI flakiness.
+
 ## 0.5.39
 
 - **Report layout fix:** Replaced ASCII table formatting with clean markdown output. Reports now render correctly in all agent UIs (Antigravity, Claude Code, Codex) without truncation or line-wrapping issues.

package/bin/ctx.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
+import { execFileSync, execSync, spawn } from "node:child_process";
 
 import { readAgentsChain } from "../plugins/ctx/lib/reader.js";
 import { filterActionableRules, parseRules, scoreRules } from "../plugins/ctx/lib/analyzer.js";
@@ -34,6 +34,38 @@ import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthr
 import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
 import { multiSelect } from "../plugins/ctx/lib/multi-select.js";
 import { syncWorkflows, warmWorkflowEmbeddings } from "../plugins/ctx/lib/workflow-discoverer.js";
+import { checkForUpdate } from "../plugins/ctx/lib/update-notifier.js";
+import { fetchSkillsForAgents, printSkillRecommendations, getAllLibraries, getInstallCommands } from "../plugins/ctx/lib/skill-library.js";
+
+/**
+ * Run a shell command with all output lines prefixed by │  
+ * Keeps the visual box style consistent during child-process output.
+ * stdin is inherited so interactive prompts (e.g. npx "Ok to proceed?") still work.
+ */
+function runPrefixed(cmd) {
+  const DIM = "\x1B[2m";
+  const RST = "\x1B[0m";
+  const pfx = `${DIM}│${RST}  `;
+  return new Promise((resolve, reject) => {
+    const child = spawn("sh", ["-c", cmd], { stdio: ["inherit", "pipe", "pipe"] });
+    function pipe(stream, target) {
+      let needPrefix = true;
+      stream.on("data", (buf) => {
+        const str = buf.toString();
+        let out = "";
+        for (const ch of str) {
+          if (needPrefix) { out += pfx; needPrefix = false; }
+          out += ch;
+          if (ch === "\n") needPrefix = true;
+        }
+        target.write(out);
+      });
+    }
+    pipe(child.stdout, process.stdout);
+    pipe(child.stderr, process.stderr);
+    child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`exit code ${code}`)));
+  });
+}
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -70,6 +102,9 @@ Usage:
   ctx sync --workflows                              Sync workflows across agents
   ctx sync --workflows --agents <names>             Sync workflows to specific agents
   ctx sync --workflows --dry-run                    Preview workflow sync without writing
+  ctx skills                                        Browse community skill libraries
+  ctx skills --agents <names>                       Filter skills for specific agents
+  ctx skills --refresh                              Force refresh skill library cache
   ctx embeddings warm -- "task"                     Pre-warm embedding caches for a task
   ctx ruler -- <ruler args>                         Passthrough to ruler CLI
   ctx skillshare -- <skillshare args>               Passthrough to skillshare CLI
@@ -608,6 +643,12 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
   console.log("│  Next: restart/open your agent from this project directory.");
   console.log("│  Try: ctx debug -- \"Recheck authen flow\"");
   console.log("");
+
+  // Recommend community skills based on selected agents
+  try {
+    const libraryResults = await fetchSkillsForAgents(options.agents, { dataDir: contextOSDataDir() });
+    printSkillRecommendations(libraryResults);
+  } catch { /* skill library is best-effort */ }
 }
 
 const args = process.argv.slice(2);
@@ -622,6 +663,8 @@ function installAgentsFromArgs(args) {
   return null; // no flag → interactive selection
 }
 
+const notifyUpdate = checkForUpdate({ currentVersion: packageVersion(), dataDir: contextOSDataDir() });
+
 try {
   if (!command || command === "--help" || command === "-h" || command === "help") {
     console.log(usage());
@@ -654,6 +697,11 @@ try {
           await streamSetupOutput(() => install({ copy, agent }));
           console.log("");
         }
+        // Recommend community skills based on selected agents
+        try {
+          const libraryResults = await fetchSkillsForAgents(selected, { dataDir: contextOSDataDir() });
+          printSkillRecommendations(libraryResults);
+        } catch { /* skill library is best-effort */ }
       }
     }
   } else if (command === "setup") {
@@ -682,6 +730,125 @@ try {
     const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
     if (!task.trim()) throw new Error('Usage: ctx benchmark -- "task"');
     console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
+  } else if (command === "skills") {
+    // Interactive community skill library selector + installer
+    const agentsFlag = args.indexOf("--agents");
+    const forceRefresh = args.includes("--refresh");
+    let agents;
+    if (agentsFlag >= 0 && args[agentsFlag + 1]) {
+      agents = args[agentsFlag + 1].split(",").map((a) => a.trim()).filter(Boolean);
+    } else {
+      agents = ["codex", "claude", "agy", "copilot"];
+    }
+
+    const DIM = "\x1B[2m";
+    const RESET = "\x1B[0m";
+    const CYAN = "\x1B[36m";
+    const GREEN = "\x1B[32m";
+    const YELLOW = "\x1B[33m";
+    const BOLD = "\x1B[1m";
+
+    console.log("Fetching community skill libraries...\n");
+    const libraryResults = await fetchSkillsForAgents(agents, {
+      dataDir: contextOSDataDir()
+    });
+
+    const totalSkills = libraryResults.reduce((sum, r) => sum + r.count, 0);
+    if (totalSkills === 0) {
+      console.log("No skills found. Check your network connection or try --refresh.");
+      process.exit(1);
+    }
+
+    // Compact header
+    console.log(`${CYAN}◇${RESET} ${BOLD}Community skill libraries available:${RESET}`);
+    console.log(`${DIM}│${RESET}  Browse and install curated skills from the community.`);
+    console.log(`${DIM}│${RESET}`);
+
+    // Multi-select which sources to install from
+    const allLibs = getAllLibraries();
+    const availableLibs = allLibs.filter((lib) => {
+      const result = libraryResults.find((r) => r.library.id === lib.id);
+      return result && result.count > 0;
+    });
+
+    if (availableLibs.length === 0) {
+      console.log("No installable libraries available.");
+      process.exit(0);
+    }
+
+    const selectedSources = await multiSelect({
+      message: "Select skill sources to install:",
+      options: availableLibs.map((lib) => {
+        const result = libraryResults.find((r) => r.library.id === lib.id);
+        return {
+          label: `${lib.name} (${result?.count || 0} skills)`,
+          value: lib.id,
+          hint: lib.url,
+          selected: false
+        };
+      })
+    });
+
+    if (!selectedSources || selectedSources.length === 0) {
+      console.log(`\n${DIM}No sources selected.${RESET}`);
+      process.exit(0);
+    }
+
+    // Install each selected source using its provided commands
+    let successCount = 0;
+    for (const libId of selectedSources) {
+      const lib = allLibs.find((l) => l.id === libId);
+      if (!lib) continue;
+
+      const installInfo = getInstallCommands(libId);
+      if (!installInfo) {
+        console.log(`${YELLOW}⚠${RESET}  No install info for ${lib.name}. Visit: ${lib.url}`);
+        continue;
+      }
+
+      console.log("");
+      console.log(`${CYAN}◇${RESET} ${BOLD}Installing from ${lib.name}${RESET}`);
+
+      if (installInfo.type === "manual") {
+        console.log(`${DIM}│${RESET}  ${installInfo.instructions}`);
+        console.log(`${DIM}│${RESET}  ${DIM}URL: ${lib.url}${RESET}`);
+        continue;
+      }
+
+      const installCmd = installInfo.fullInstall;
+      if (installCmd) {
+        console.log(`${DIM}│${RESET}  ${GREEN}$ ${installCmd}${RESET}`);
+        console.log(`${DIM}│${RESET}`);
+
+        try {
+          await runPrefixed(installCmd);
+          successCount++;
+
+          // Run verify command if available
+          if (installInfo.verify) {
+            try {
+              await runPrefixed(installInfo.verify);
+            } catch { /* verify is best-effort */ }
+          }
+          console.log(`${DIM}│${RESET}`);
+          console.log(`${GREEN}✔${RESET} ${lib.name} installed successfully.`);
+        } catch (err) {
+          console.error(`${YELLOW}⚠${RESET}  Install failed for ${lib.name}. Try manually:`);
+          console.error(`   ${installCmd}`);
+          console.error(`   ${DIM}${err.message}${RESET}`);
+        }
+      }
+    }
+
+    // Final summary
+    console.log("");
+    if (successCount > 0) {
+      console.log(`${GREEN}✔${RESET} ${BOLD}${successCount} source${successCount > 1 ? "s" : ""} installed.${RESET}`);
+      console.log(`${DIM}│${RESET}  Restart your agent to pick up new skills.`);
+    } else {
+      console.log(`${DIM}No installations were completed.${RESET}`);
+    }
+    console.log("");
   } else if (command === "sync") {
     if (args.includes("--workflows")) {
       await syncWorkflows({
@@ -719,4 +886,6 @@ try {
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;
+} finally {
+  await notifyUpdate();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.39",
+  "version": "0.5.41",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.5.37",
+  "version": "0.5.41",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/multi-select.js

@@ -62,6 +62,9 @@ export function multiSelect({ message, options }) {
         const label = isCursor ? `${BOLD}${CYAN}${options[i].label}${RESET}` : options[i].label;
         const pointer = isCursor ? `${CYAN}❯${RESET}` : " ";
         lines.push(`  ${pointer} ${checkbox} ${label}`);
+        if (options[i].hint) {
+          lines.push(`        ${DIM}${options[i].hint}${RESET}`);
+        }
       }
       return lines;
     }
@@ -140,3 +143,113 @@ export function multiSelect({ message, options }) {
     draw();
   });
 }
+
+/**
+ * Interactive single-select prompt (radio-button style).
+ *
+ * @param {{ message: string, options: Array<{label: string, value: string, disabled?: boolean, isHeader?: boolean}> }} config
+ * @returns {Promise<string|null>} selected value or null
+ */
+export function singleSelect({ message, options }) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      // Non-interactive: return first non-disabled
+      const first = options.find((o) => !o.disabled);
+      resolve(first ? first.value : null);
+      return;
+    }
+
+    // Filter to only selectable items, but keep the full list for rendering
+    const selectableIndices = options
+      .map((o, i) => (o.disabled ? -1 : i))
+      .filter((i) => i >= 0);
+    if (selectableIndices.length === 0) { resolve(null); return; }
+
+    let cursorIdx = 0; // index into selectableIndices
+    let cursor = selectableIndices[0]; // actual index in options
+
+    function render() {
+      const lines = [];
+      lines.push(`${CYAN}◇${RESET} ${message}`);
+      lines.push(`${DIM}  Use ↑/↓ to navigate, Enter to select${RESET}`);
+      for (let i = 0; i < options.length; i++) {
+        const opt = options[i];
+        if (opt.disabled || opt.isHeader) {
+          lines.push(`  ${DIM}${opt.label}${RESET}`);
+          continue;
+        }
+        const isCursor = i === cursor;
+        const radio = isCursor ? `${GREEN}◉${RESET}` : `${DIM}○${RESET}`;
+        const label = isCursor ? `${BOLD}${CYAN}${opt.label}${RESET}` : opt.label;
+        const pointer = isCursor ? `${CYAN}❯${RESET}` : " ";
+        lines.push(`  ${pointer} ${radio} ${label}`);
+      }
+      return lines;
+    }
+
+    let prevLineCount = 0;
+
+    function draw() {
+      const lines = render();
+      if (prevLineCount > 0) {
+        process.stdout.write(`\x1B[${prevLineCount}A`);
+        for (let i = 0; i < prevLineCount; i++) {
+          process.stdout.write("\x1B[2K");
+          if (i < prevLineCount - 1) process.stdout.write("\x1B[1B");
+        }
+        process.stdout.write(`\x1B[${prevLineCount - 1}A`);
+      }
+      process.stdout.write(lines.join("\n") + "\n");
+      prevLineCount = lines.length;
+    }
+
+    process.stdout.write(HIDE_CURSOR);
+
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    function cleanup() {
+      process.stdin.setRawMode(wasRaw || false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onData);
+      process.stdout.write(SHOW_CURSOR);
+    }
+
+    function onData(data) {
+      if (matchKey(data, KEYS.CTRL_C)) {
+        cleanup();
+        process.exit(0);
+      }
+
+      if (matchKey(data, KEYS.UP) || matchKey(data, KEYS.K)) {
+        cursorIdx = (cursorIdx - 1 + selectableIndices.length) % selectableIndices.length;
+        cursor = selectableIndices[cursorIdx];
+        draw();
+      } else if (matchKey(data, KEYS.DOWN) || matchKey(data, KEYS.J)) {
+        cursorIdx = (cursorIdx + 1) % selectableIndices.length;
+        cursor = selectableIndices[cursorIdx];
+        draw();
+      } else if (matchKey(data, KEYS.ENTER)) {
+        cleanup();
+        const selected = options[cursor];
+        // Clear and show result
+        if (prevLineCount > 0) {
+          process.stdout.write(`\x1B[${prevLineCount}A`);
+          for (let i = 0; i < prevLineCount; i++) {
+            process.stdout.write("\x1B[2K");
+            if (i < prevLineCount - 1) process.stdout.write("\x1B[1B");
+          }
+          process.stdout.write(`\x1B[${prevLineCount - 1}A`);
+        }
+        process.stdout.write(`${CYAN}◇${RESET} ${message}\n`);
+        process.stdout.write(`${DIM}│${RESET}  ${GREEN}${selected.label}${RESET}\n`);
+        resolve(selected.value);
+      }
+    }
+
+    process.stdin.on("data", onData);
+    draw();
+  });
+}

package/plugins/ctx/lib/skill-library.js

@@ -0,0 +1,364 @@
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import os from "node:os";
+
+/**
+ * Curated skill library sources, mapped by agent.
+ *
+ * Each source provides a GitHub repo with a README that lists available skills.
+ * We fetch the README, parse skill entries, and let the user pick from a
+ * multi-select panel after agent selection in `ctx install` or `ctx setup`.
+ */
+
+const SKILL_LIBRARIES = [
+  {
+    id: "antigravity-awesome",
+    name: "Antigravity Awesome Skills",
+    repo: "sickn33/antigravity-awesome-skills",
+    url: "https://github.com/sickn33/antigravity-awesome-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/sickn33/antigravity-awesome-skills/main/README.md",
+    agents: ["agy", "claude", "codex", "copilot"],   // universal library
+    description: "1,400+ agentic skills for all agents",
+    install: {
+      type: "npx",
+      fullInstall: "npx antigravity-awesome-skills",
+      agentFlags: {
+        codex: "npx antigravity-awesome-skills --codex",
+        claude: "npx antigravity-awesome-skills --claude",
+        agy: "npx antigravity-awesome-skills --antigravity",
+        copilot: "npx antigravity-awesome-skills --cursor",
+        gemini: "npx antigravity-awesome-skills --gemini"
+      },
+      verify: 'test -d ~/.agents/skills && echo "Skills installed in ~/.agents/skills"'
+    }
+  },
+  {
+    id: "awesome-claude",
+    name: "Awesome Claude Skills",
+    repo: "ComposioHQ/awesome-claude-skills",
+    url: "https://github.com/ComposioHQ/awesome-claude-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/ComposioHQ/awesome-claude-skills/master/README.md",
+    agents: ["claude"],
+    description: "Curated Claude Code skills & workflows",
+    install: {
+      type: "git-clone",
+      clone: "git clone https://github.com/ComposioHQ/awesome-claude-skills.git",
+      skillDir: "~/.claude/skills",
+      copyCommand: (skillName) =>
+        `cp -r awesome-claude-skills/${skillName} ~/.claude/skills/${skillName}`,
+      fullInstall: [
+        "git clone https://github.com/ComposioHQ/awesome-claude-skills.git",
+        "mkdir -p ~/.claude/skills",
+        'for d in awesome-claude-skills/*/; do [ -f "$d/SKILL.md" ] && cp -r "$d" ~/.claude/skills/; done'
+      ].join(" && "),
+      verify: 'ls ~/.claude/skills/'
+    }
+  },
+  {
+    id: "awesome-codex",
+    name: "Awesome Codex Skills",
+    repo: "ComposioHQ/awesome-codex-skills",
+    url: "https://github.com/ComposioHQ/awesome-codex-skills",
+    rawReadmeUrl: "https://raw.githubusercontent.com/ComposioHQ/awesome-codex-skills/master/README.md",
+    agents: ["codex"],
+    description: "Practical Codex CLI skills & automations",
+    install: {
+      type: "git-clone-python",
+      clone: "git clone https://github.com/ComposioHQ/awesome-codex-skills.git",
+      skillDir: "~/.codex/skills",
+      installScript: (skillName) =>
+        `python awesome-codex-skills/skill-installer/scripts/install-skill-from-github.py --repo ComposioHQ/awesome-codex-skills --path ${skillName}`,
+      fullInstall: [
+        "git clone https://github.com/ComposioHQ/awesome-codex-skills.git",
+        "cd awesome-codex-skills",
+        "mkdir -p ~/.codex/skills",
+        'for d in */; do [ -f "$d/SKILL.md" ] && [ "$d" != "skill-installer/" ] && cp -r "$d" ~/.codex/skills/; done'
+      ].join(" && "),
+      verify: 'ls ~/.codex/skills/'
+    }
+  },
+  {
+    id: "awesome-copilot",
+    name: "Awesome Copilot",
+    repo: "github/awesome-copilot",
+    url: "https://github.com/github/awesome-copilot",
+    rawReadmeUrl: "https://raw.githubusercontent.com/github/awesome-copilot/main/README.md",
+    agents: ["copilot"],
+    description: "Community GitHub Copilot instructions & agents",
+    install: {
+      type: "manual",
+      fullInstall: null,
+      instructions: "Browse the repository and copy relevant .instructions.md files to your .github/ directory.",
+      url: "https://github.com/github/awesome-copilot"
+    }
+  }
+];
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 1 day
+
+// ────────────────────────────── HTTP fetch ────────────────────────────────
+
+function fetchUrl(url, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { timeout: timeoutMs }, (res) => {
+      // Follow redirects (301/302/307/308)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        fetchUrl(res.headers.location, timeoutMs).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        res.resume();
+        return;
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      res.on("error", reject);
+    });
+    req.on("timeout", () => { req.destroy(); reject(new Error(`Timeout fetching ${url}`)); });
+    req.on("error", reject);
+  });
+}
+
+// ────────────────────────────── README parser ─────────────────────────────
+
+/**
+ * Parse a GitHub awesome-list README and extract skill entries.
+ *
+ * Looks for markdown links in list items:
+ *   - [Skill Name](url) - Description
+ *   - **[Skill Name](url)** — Description
+ *
+ * Returns: Array<{ name, url, description }>
+ */
+export function parseSkillEntries(readmeContent) {
+  const entries = [];
+  const lines = readmeContent.split("\n");
+  // Match list items with markdown links
+  const linkPattern = /^[-*]\s+\**\[([^\]]+)\]\(([^)]+)\)\**\s*[-–—:]*\s*(.*)/;
+  for (const line of lines) {
+    const match = line.match(linkPattern);
+    if (!match) continue;
+    const [, name, url, description] = match;
+    // Skip non-skill links (images, badges, section headers)
+    if (/\.(png|jpg|svg|gif)$/i.test(url)) continue;
+    if (url.startsWith("#")) continue;
+    entries.push({
+      name: name.trim(),
+      url: url.trim(),
+      description: (description || "").replace(/^\s*[-–—:]+\s*/, "").trim()
+    });
+  }
+  return entries;
+}
+
+// ────────────────────────────── Cache layer ────────────────────────────────
+
+function cacheDir(dataDir) {
+  return path.join(dataDir, "skill-library-cache");
+}
+
+function cacheFilePath(dataDir, libraryId) {
+  return path.join(cacheDir(dataDir), `${libraryId}.json`);
+}
+
+function readCache(dataDir, libraryId) {
+  const filePath = cacheFilePath(dataDir, libraryId);
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    if (Date.now() - (data.fetchedAt || 0) < CACHE_TTL_MS) {
+      return data.entries || [];
+    }
+  } catch { /* cache miss */ }
+  return null;
+}
+
+function writeCache(dataDir, libraryId, entries) {
+  const dir = cacheDir(dataDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const data = { fetchedAt: Date.now(), entries };
+  fs.writeFileSync(cacheFilePath(dataDir, libraryId), JSON.stringify(data, null, 2));
+}
+
+// ────────────────────────────── Public API ─────────────────────────────────
+
+/**
+ * Get libraries relevant to selected agents.
+ */
+export function getLibrariesForAgents(selectedAgents) {
+  const normalized = selectedAgents.map((a) => a.toLowerCase().replace("antigravity", "agy"));
+  return SKILL_LIBRARIES.filter((lib) =>
+    lib.agents.some((agent) => normalized.includes(agent))
+  );
+}
+
+/**
+ * Fetch skill entries from a library (with caching).
+ */
+export async function fetchLibrarySkills(library, { dataDir, forceRefresh = false } = {}) {
+  if (dataDir && !forceRefresh) {
+    const cached = readCache(dataDir, library.id);
+    if (cached) return { entries: cached, source: "cache" };
+  }
+
+  try {
+    const readme = await fetchUrl(library.rawReadmeUrl);
+    const entries = parseSkillEntries(readme);
+    if (dataDir && entries.length > 0) {
+      writeCache(dataDir, library.id, entries);
+    }
+    return { entries, source: "network" };
+  } catch (error) {
+    // Try cache even if expired on network failure
+    if (dataDir) {
+      try {
+        const filePath = cacheFilePath(dataDir, library.id);
+        const raw = fs.readFileSync(filePath, "utf8");
+        const data = JSON.parse(raw);
+        return { entries: data.entries || [], source: "stale-cache" };
+      } catch { /* no cache at all */ }
+    }
+    return { entries: [], source: "error", error: error.message };
+  }
+}
+
+/**
+ * Fetch skills from all relevant libraries for selected agents.
+ * Returns a flat list grouped by library.
+ */
+export async function fetchSkillsForAgents(selectedAgents, { dataDir } = {}) {
+  const libraries = getLibrariesForAgents(selectedAgents);
+  const results = [];
+
+  for (const lib of libraries) {
+    const { entries, source } = await fetchLibrarySkills(lib, { dataDir });
+    results.push({
+      library: lib,
+      entries,
+      source,
+      count: entries.length
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Format skill library results as multi-select options.
+ * Groups by library with a header option (disabled).
+ */
+export function formatAsSelectOptions(libraryResults) {
+  const options = [];
+  for (const result of libraryResults) {
+    if (result.entries.length === 0) continue;
+    // Add library header as separator
+    options.push({
+      label: `── ${result.library.name} (${result.count} skills) ──`,
+      value: `__header__${result.library.id}`,
+      disabled: true,
+      isHeader: true
+    });
+    // Add top skills (limit to prevent overwhelming the user)
+    const topEntries = result.entries.slice(0, 30);
+    for (const entry of topEntries) {
+      const desc = entry.description ? ` — ${entry.description.slice(0, 60)}` : "";
+      options.push({
+        label: `${entry.name}${desc}`,
+        value: entry.url,
+        selected: false,
+        libraryId: result.library.id,
+        skillName: entry.name
+      });
+    }
+    if (result.entries.length > 30) {
+      options.push({
+        label: `  ... and ${result.entries.length - 30} more at ${result.library.url}`,
+        value: `__more__${result.library.id}`,
+        disabled: true,
+        isHeader: true
+      });
+    }
+  }
+  return options;
+}
+
+/**
+ * Print a compact recommendation panel to the terminal.
+ * Used after agent selection in `ctx install` and `ctx setup`.
+ */
+export function printSkillRecommendations(libraryResults, { logger = console.log } = {}) {
+  const DIM = "\x1B[2m";
+  const RESET = "\x1B[0m";
+  const CYAN = "\x1B[36m";
+  const GREEN = "\x1B[32m";
+  const YELLOW = "\x1B[33m";
+  const BOLD = "\x1B[1m";
+
+  const hasSkills = libraryResults.some((r) => r.entries.length > 0);
+  if (!hasSkills) return;
+
+  logger("");
+  logger(`${CYAN}◇${RESET} ${BOLD}Community skill libraries available:${RESET}`);
+  logger(`${DIM}│${RESET}  Browse and install curated skills from the community.`);
+  logger(`${DIM}│${RESET}`);
+
+  for (const result of libraryResults) {
+    if (result.entries.length === 0) continue;
+    const badge = result.source === "cache" ? `${DIM}(cached)${RESET}` : "";
+    logger(`${DIM}│${RESET}  ${GREEN}●${RESET} ${BOLD}${result.library.name}${RESET} ${badge}`);
+    logger(`${DIM}│${RESET}    ${result.count} skills · ${result.library.description}`);
+    logger(`${DIM}│${RESET}    ${DIM}${result.library.url}${RESET}`);
+
+    // Show top 5 skills as preview
+    const preview = result.entries.slice(0, 5);
+    for (const skill of preview) {
+      const desc = skill.description ? ` ${DIM}— ${skill.description.slice(0, 50)}${RESET}` : "";
+      logger(`${DIM}│${RESET}      ${YELLOW}▸${RESET} ${skill.name}${desc}`);
+    }
+    if (result.entries.length > 5) {
+      logger(`${DIM}│${RESET}      ${DIM}... and ${result.entries.length - 5} more${RESET}`);
+    }
+    logger(`${DIM}│${RESET}`);
+  }
+
+  logger(`${DIM}│${RESET}  ${DIM}Run ${CYAN}ctx skills${RESET}${DIM} to browse and install community skills.${RESET}`);
+}
+
+/**
+ * Get all library definitions.
+ */
+export function getAllLibraries() {
+  return SKILL_LIBRARIES;
+}
+
+/**
+ * Get install commands for a specific library.
+ * @param {string} libraryId
+ * @param {string} [agent] - optional agent to target
+ * @returns {{ fullInstall: string|null, agentInstall: string|null, verify: string|null, instructions: string|null, type: string }}
+ */
+export function getInstallCommands(libraryId, agent) {
+  const lib = SKILL_LIBRARIES.find((l) => l.id === libraryId);
+  if (!lib || !lib.install) return null;
+
+  const inst = lib.install;
+  const result = {
+    type: inst.type,
+    fullInstall: typeof inst.fullInstall === "string" ? inst.fullInstall : null,
+    agentInstall: null,
+    verify: inst.verify || null,
+    instructions: inst.instructions || null,
+    url: inst.url || lib.url
+  };
+
+  // Agent-specific install (only for npx-based libs)
+  if (agent && inst.agentFlags) {
+    const normalized = agent.toLowerCase().replace("antigravity", "agy");
+    result.agentInstall = inst.agentFlags[normalized] || null;
+  }
+
+  return result;
+}

package/plugins/ctx/lib/update-notifier.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PACKAGE_NAME = "@minhpnq1807/contextos";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
+const REQUEST_TIMEOUT_MS = 3000;
+
+function cacheFilePath(dataDir) {
+  return path.join(dataDir, ".update-check.json");
+}
+
+function readCache(dataDir) {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFilePath(dataDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(dataDir, data) {
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(cacheFilePath(dataDir), JSON.stringify(data), "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+async function fetchLatestVersion() {
+  const https = await import("node:https");
+  return new Promise((resolve) => {
+    const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+    const req = https.get(url, { timeout: REQUEST_TIMEOUT_MS, headers: { accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        return resolve(null);
+      }
+      let body = "";
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body).version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+  });
+}
+
+function compareVersions(current, latest) {
+  const parse = (v) => String(v || "").replace(/^v/, "").split(".").map(Number);
+  const c = parse(current);
+  const l = parse(latest);
+  for (let i = 0; i < 3; i++) {
+    if ((l[i] || 0) > (c[i] || 0)) return 1;
+    if ((l[i] || 0) < (c[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Check for updates in background (non-blocking).
+ * Returns a function that, when called, prints the update message if available.
+ *
+ * Usage:
+ *   const notify = checkForUpdate({ currentVersion, dataDir });
+ *   // ... run CLI command ...
+ *   await notify(); // prints update message at the very end
+ */
+export function checkForUpdate({ currentVersion, dataDir }) {
+  let resultPromise = null;
+
+  // Start background check lazily
+  function startCheck() {
+    if (resultPromise) return resultPromise;
+    resultPromise = (async () => {
+      try {
+        const cache = readCache(dataDir);
+        const isFresh = cache && typeof cache.checkedAt === "number" && (Date.now() - cache.checkedAt < CHECK_INTERVAL_MS);
+
+        if (isFresh) {
+          return cache.latestVersion && compareVersions(currentVersion, cache.latestVersion) > 0
+            ? cache.latestVersion
+            : null;
+        }
+
+        const latestVersion = await fetchLatestVersion();
+        if (latestVersion) {
+          writeCache(dataDir, { checkedAt: Date.now(), latestVersion });
+        }
+
+        return latestVersion && compareVersions(currentVersion, latestVersion) > 0
+          ? latestVersion
+          : null;
+      } catch {
+        return null;
+      }
+    })();
+    return resultPromise;
+  }
+
+  // Start immediately (non-blocking)
+  startCheck();
+
+  return async () => {
+    const latestVersion = await startCheck();
+    if (latestVersion) {
+      console.error(formatUpdateBox(currentVersion, latestVersion));
+    }
+  };
+}
+
+function formatUpdateBox(currentVersion, latestVersion) {
+  const lines = [
+    `Update available: ${currentVersion} → ${latestVersion}`,
+    "",
+    `Run: npm install -g ${PACKAGE_NAME}`,
+    `Then run: ctx install --agents codex`,
+  ];
+  const maxLen = lines.reduce((m, l) => Math.max(m, l.length), 0);
+  const width = maxLen + 4;
+  const pad = (text) => `│ ${text.padEnd(width - 4)} │`;
+  const top = `╭${"─".repeat(width - 2)}╮`;
+  const bottom = `╰${"─".repeat(width - 2)}╯`;
+  return ["", top, ...lines.map(pad), bottom, ""].join("\n");
+}