@minhpnq1807/contextos 0.5.38 → 0.5.40

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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.
+- **Skills & workflows in report:** `Suggested Skills` and `Suggested Workflows` sections now appear in the compliance report when available. Data is passed through from `stop-hook.js` → `buildReport()` → `formatReport()`.
+- **No more truncation:** All rules now display in the report — removed the artificial item limits that caused `... N more` messages.
+- **Emoji status indicators:** Rule outcomes use ✅/❌/❓/⚠️ prefixes for quick scanning.
+
+
 ## 0.5.38
 
 - **Unified agent branding:** All user-facing text now shows `antigravity` instead of `agy`. Internal value remains `agy` for backward compatibility. Interactive prompts display "Antigravity" without the parenthetical alias.

package/bin/ctx.js

@@ -34,6 +34,8 @@ 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 } from "../plugins/ctx/lib/skill-library.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -70,6 +72,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 +613,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 +633,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 +667,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 +700,31 @@ 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") {
+    // Browse community skill libraries
+    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"];
+    }
+    console.log("Fetching community skill libraries...\n");
+    const libraryResults = await fetchSkillsForAgents(agents, {
+      dataDir: contextOSDataDir()
+    });
+    printSkillRecommendations(libraryResults);
+    console.log("");
+    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.");
+    } else {
+      console.log(`Total: ${totalSkills} skills across ${libraryResults.filter((r) => r.count > 0).length} libraries.`);
+      console.log("");
+      console.log("To install skills, visit the library URLs above or use:");
+      console.log("  ctx sync --skills       Sync skills across agents via skillshare");
+    }
   } else if (command === "sync") {
     if (args.includes("--workflows")) {
       await syncWorkflows({
@@ -719,4 +762,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.38",
+  "version": "0.5.40",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/reporter.js

@@ -1,7 +1,6 @@
 import { isSystemUserRule } from "./analyzer.js";
-import { section, table, truncateCell } from "./terminal-ui.js";
 
-export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot, compliance, runtimeEvidence }) {
+export function buildReport({ cwd, prompt, relevantFiles, suggestedSkills, suggestedWorkflows, scheduled, gitSnapshot, compliance, runtimeEvidence }) {
   const actionableCompliance = compliance.filter((item) => !isSystemUserRule(item.rule));
   const followed = actionableCompliance.filter((item) => item.status === "followed");
   const ignored = actionableCompliance.filter((item) => item.status === "ignored");
@@ -16,6 +15,8 @@ export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot
     prompt,
     injectedRuleCount: (scheduled?.highRules?.length || 0) + (scheduled?.midRules?.length || 0),
     relevantFiles,
+    suggestedSkills: suggestedSkills || [],
+    suggestedWorkflows: suggestedWorkflows || [],
     changedFiles: gitSnapshot.changedFiles,
     warnings: gitSnapshot.warnings || [],
     runtimeEvidence: summarizeRuntimeEvidence(runtimeEvidence),
@@ -33,47 +34,77 @@ export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot
 export function formatReport(report) {
   report = sanitizeReport(report);
   const lines = [];
-  lines.push("ContextOS report");
-  lines.push(section("Summary"));
-  lines.push(table(["Metric", "Value"], [
-    ["Efficiency", report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`],
-    ["Injected rules", report.injectedRuleCount || 0],
-    ["Measured rules", report.measuredRuleCount ?? ((report.followed?.length || 0) + (report.ignored?.length || 0))],
-    ["Changed files", report.changedFiles?.length ? report.changedFiles.length : "none detected"]
-  ]));
-
-  lines.push(section("Rule Outcomes"));
-  lines.push(table(["Status", "Count"], [
-    ["followed", report.followed?.length || 0],
-    ["ignored", report.ignored?.length || 0],
-    ["unknown", report.unknown?.length || 0],
-    ["unmeasurable", report.unmeasurable?.length || 0]
-  ]));
-
+  lines.push("# ContextOS Report\n");
+
+  // Summary
+  lines.push("## Summary");
+  lines.push(`- **Efficiency:** ${report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`}`);
+  lines.push(`- **Injected rules:** ${report.injectedRuleCount || 0}`);
+  lines.push(`- **Measured rules:** ${report.measuredRuleCount ?? ((report.followed?.length || 0) + (report.ignored?.length || 0))}`);
+  lines.push(`- **Changed files:** ${report.changedFiles?.length ? report.changedFiles.length : "none detected"}`);
+  lines.push("");
+
+  // Rule Outcomes
+  lines.push("## Rule Outcomes");
+  lines.push(`- ✅ Followed: ${report.followed?.length || 0}`);
+  lines.push(`- ❌ Ignored: ${report.ignored?.length || 0}`);
+  lines.push(`- ❓ Unknown: ${report.unknown?.length || 0}`);
+  lines.push(`- ⚠️ Unmeasurable: ${report.unmeasurable?.length || 0}`);
+  lines.push("");
+
+  // Suggested Files
   if (report.relevantFiles?.length) {
-    lines.push(section("Suggested Files"));
-    lines.push(table(["#", "Path", "Score"], report.relevantFiles.slice(0, 10).map((file, index) => [
-      index + 1,
-      truncateCell(file.path, 90),
-      typeof file.score === "number" ? file.score.toFixed(2) : ""
-    ])));
+    lines.push("## Suggested Files");
+    for (const [index, file] of report.relevantFiles.entries()) {
+      const score = typeof file.score === "number" ? ` (${file.score.toFixed(2)})` : "";
+      lines.push(`${index + 1}. ${file.path}${score}`);
+    }
+    lines.push("");
+  }
+
+  // Suggested Skills
+  if (report.suggestedSkills?.length) {
+    lines.push("## Suggested Skills");
+    for (const skill of report.suggestedSkills) {
+      const desc = skill.description ? `: ${truncate(skill.description, 80)}` : "";
+      lines.push(`- **${skill.name}**${desc}`);
+    }
+    lines.push("");
+  }
+
+  // Suggested Workflows
+  if (report.suggestedWorkflows?.length) {
+    lines.push("## Suggested Workflows");
+    for (const workflow of report.suggestedWorkflows) {
+      const name = workflow.title || workflow.name;
+      const chain = workflow.chain?.length ? ` → ${workflow.chain.join(" → ")}` : "";
+      lines.push(`- **${name}**${chain}`);
+    }
+    lines.push("");
   }
+
+  // Runtime Telemetry
   if (report.runtimeEvidence?.signals?.length) {
-    lines.push(section("Runtime Telemetry"));
-    lines.push(table(["#", "Signal"], report.runtimeEvidence.signals.map((signal, index) => [index + 1, signal])));
+    lines.push("## Runtime Telemetry");
+    for (const signal of report.runtimeEvidence.signals) {
+      lines.push(`- ${signal}`);
+    }
+    lines.push("");
   }
 
-  for (const warning of report.warnings || []) lines.push(`Warning: ${warning}`);
+  // Warnings
+  for (const warning of report.warnings || []) lines.push(`> ⚠️ ${warning}\n`);
 
+  // Rule details
   appendBucket(lines, "Followed", report.followed);
   appendBucket(lines, "Ignored", report.ignored);
   appendBucket(lines, "Unknown", report.unknown);
   appendBucket(lines, "Unmeasurable", report.unmeasurable);
 
   if (report.ignored?.length) {
-    lines.push(`Suggestion: fix ignored rule evidence first: ${truncate(report.ignored[0].rule?.content || "", 70)}`);
+    lines.push(`> **Suggestion:** Fix ignored rule evidence first: ${truncate(report.ignored[0].rule?.content || "", 70)}`);
   } else if (report.unknown?.length && !(report.followed?.length || report.ignored?.length)) {
-    lines.push("Suggestion: these rules need runtime evidence or more concrete keywords before ContextOS can score them from git diff.");
+    lines.push("> **Suggestion:** These rules need runtime evidence or more concrete keywords before ContextOS can score them from git diff.");
   }
 
   return lines.join("\n");
@@ -82,15 +113,15 @@ export function formatReport(report) {
 export function formatEvidence(report) {
   report = sanitizeReport(report);
   const lines = [];
-  lines.push("ContextOS evidence");
-  lines.push(section("Summary"));
-  lines.push(table(["Field", "Value"], [
-    ["Prompt", truncateCell(report.prompt || "(empty)", 100)],
-    ["Efficiency", report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`],
-    ["Changed files", report.changedFiles?.length ? report.changedFiles.join(", ") : "none detected"]
-  ]));
+  lines.push("# ContextOS Evidence\n");
+
+  lines.push("## Summary");
+  lines.push(`- **Prompt:** ${truncate(report.prompt || "(empty)", 100)}`);
+  lines.push(`- **Efficiency:** ${report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`}`);
+  lines.push(`- **Changed files:** ${report.changedFiles?.length ? report.changedFiles.join(", ") : "none detected"}`);
+  lines.push("");
 
-  for (const warning of report.warnings || []) lines.push(`Warning: ${warning}`);
+  for (const warning of report.warnings || []) lines.push(`> ⚠️ ${warning}\n`);
 
   const items = [
     ...(report.followed || []).map((item) => ({ ...item, status: "followed" })),
@@ -105,43 +136,34 @@ export function formatEvidence(report) {
     return lines.join("\n");
   }
 
-  lines.push(section("Evidence Table"));
-  lines.push(table(["#", "Status", "Score", "Kind", "Rule", "Evidence"], items.map((item, index) => [
-    index + 1,
-    item.status.toUpperCase(),
-    typeof item.rule?.score === "number" ? item.rule.score.toFixed(2) : "",
-    item.kind || "",
-    truncateCell(item.rule?.content || "(missing rule)", 46),
-    truncateCell(item.evidence || "(none)", 58)
-  ])));
-
-  items.forEach((item, index) => {
-    lines.push(section(`${index + 1}. ${item.status.toUpperCase()}`));
-    lines.push(table(["Field", "Value"], [
-      ["Rule", truncateCell(item.rule?.content || "(missing rule)", 120)],
-      ["Source", item.rule?.sourcePath || ""],
-      ["Score", typeof item.rule?.score === "number" ? item.rule.score.toFixed(2) : ""],
-      ["Kind", item.kind || ""],
-      ["Keywords", item.keywords?.length ? truncateCell(item.keywords.join(", "), 120) : ""],
-      ["Evidence", truncateCell(item.evidence || "(none)", 120)]
-    ].filter(([, value]) => value !== "")));
+  lines.push("## Evidence Details\n");
+  for (const [index, item] of items.entries()) {
+    const statusIcon = { followed: "✅", ignored: "❌", unknown: "❓", unmeasurable: "⚠️" }[item.status] || "";
+    lines.push(`### ${index + 1}. ${statusIcon} ${item.status.toUpperCase()}`);
+    lines.push(`- **Rule:** ${truncate(item.rule?.content || "(missing rule)", 120)}`);
+    if (item.rule?.sourcePath) lines.push(`- **Source:** ${item.rule.sourcePath}`);
+    if (typeof item.rule?.score === "number") lines.push(`- **Score:** ${item.rule.score.toFixed(2)}`);
+    if (item.kind) lines.push(`- **Kind:** ${item.kind}`);
+    lines.push(`- **Evidence:** ${truncate(item.evidence || "(none)", 120)}`);
     for (const line of item.matchedLines || []) {
       const where = line.file ? `${line.file}${typeof line.line === "number" ? `:${line.line}` : ""}` : "diff";
-      lines.push(`Matched line: ${where} ${truncate(line.content || "", 140)}`);
+      lines.push(`  - Match: \`${where}\` ${truncate(line.content || "", 100)}`);
     }
-  });
+    lines.push("");
+  }
 
   return lines.join("\n");
 }
 
 function appendBucket(lines, label, items = []) {
   if (!items.length) return;
-  lines.push(`${label}:`);
-  for (const item of items.slice(0, 5)) {
-    lines.push(`- Rule: ${truncate(item.rule.content, 68)}`);
-    lines.push(`  Evidence: ${truncate(item.evidence, 64)}`);
+  const icon = { Followed: "✅", Ignored: "❌", Unknown: "❓", Unmeasurable: "⚠️" }[label] || "";
+  lines.push(`### ${icon} ${label}`);
+  for (const item of items) {
+    lines.push(`- **Rule:** ${truncate(item.rule.content, 100)}`);
+    lines.push(`  - Evidence: ${truncate(item.evidence, 100)}`);
   }
-  if (items.length > 5) lines.push(`- ... ${items.length - 5} more`);
+  lines.push("");
 }
 
 function truncate(value, max) {

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

@@ -0,0 +1,290 @@
+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"
+  },
+  {
+    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/main/README.md",
+    agents: ["claude"],
+    description: "Curated Claude Code skills & workflows"
+  },
+  {
+    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/main/README.md",
+    agents: ["codex"],
+    description: "Practical Codex CLI skills & automations"
+  },
+  {
+    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"
+  }
+];
+
+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;
+}

package/plugins/ctx/lib/stop-hook.js

@@ -42,6 +42,8 @@ export function handleStopPayload(payload, { contextPath, reportPath, historyPat
     cwd,
     prompt: promptContext?.prompt || "",
     relevantFiles: promptContext?.relevantFiles || [],
+    suggestedSkills: promptContext?.suggestedSkills || [],
+    suggestedWorkflows: promptContext?.suggestedWorkflows || [],
     scheduled,
     gitSnapshot,
     compliance,

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");
+}