@minhpnq1807/contextos 0.5.15 → 0.5.16

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.16
+
+- Prints a "Rebuilding skill embeddings... started" status before indexing large skillshare catalogs so `ctx sync --skills` no longer looks stuck after skillshare finishes.
+- Adds `ctx sync --skills --no-embeddings` for fast skill sync when users want to warm embeddings later.
+- Caches oversized skill catalog scans correctly and truncates skill descriptions before scoring, keeping prompt-time skill discovery fast with large skillshare catalogs.
+- Runs native `skillshare sync` in quiet mode by default to avoid flooding ContextOS output with budget warnings; use `--verbose` to show them.
+
 ## 0.5.15
 
 - Replaces the misleading `ctx install --agent codex|claude|agy` usage text with separate commands.

package/README.md

@@ -252,6 +252,8 @@ Useful variants:
 ```bash
 ctx sync --skills --dry-run
 ctx sync --skills --no-collect
+ctx sync --skills --no-embeddings
+ctx sync --skills --verbose
 ctx sync --skills --agents codex,claude
 ctx sync --skills --agents codex,claude,agy
 ```
@@ -432,6 +434,8 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx sync --skills --agents <list>` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude` or `codex,claude,agy`. | Runs `skillshare sync --agents <list>` with `agy` normalized to `antigravity`, then refreshes skill embeddings. |
 | `ctx sync --skills --dry-run` | Previews skillshare sync. | You want to inspect behavior before changing skill directories. | Runs `skillshare sync --dry-run` and skips embedding rebuild. |
 | `ctx sync --skills --no-collect` | Skips collecting existing agent skills into skillshare. | You already manage `~/.config/skillshare/skills` and only want to push it out. | Initializes/syncs skillshare without running `skillshare backup` or `skillshare collect --all`. |
+| `ctx sync --skills --no-embeddings` | Skips ContextOS skill embedding rebuild after skillshare sync. | You have a very large skill catalog and want sync to finish quickly. | Runs skillshare sync, then leaves embeddings to a later `ctx embeddings warm -- "task"` run. |
+| `ctx sync --skills --verbose` | Shows native skillshare token budget warnings during sync. | You are diagnosing skillshare path overlap or always-loaded context size. | Omits ContextOS' default `skillshare sync --quiet` behavior. |
 | `ctx sync --workflows` | Syncs and indexes agent workflow markdown files for prompt-time workflow suggestions. | You use `.claude/workflows/`, `.codex/workflows/`, or Antigravity workflow folders and want every agent to see the same deduped workflow set. | Scans project/global workflow folders, dedupes by workflow name, copies unique workflows to selected global agent roots, warms workflow embeddings, and makes `ctx debug`/prompt hooks show relevant workflow hints. |
 | `ctx sync --workflows --agents <list>` | Syncs workflows only for selected agents. | You want a subset such as `codex,claude` or `codex,claude,agy`. | Accepts comma-separated `codex`, `claude`, `agy`, or `antigravity`; `agy` writes the Gemini/Antigravity workflow roots. |
 | `ctx sync --workflows --dry-run` | Previews workflow sync without writing files. | You want to inspect source workflows and target roots first. | Prints planned sync/index output and skips copying target files. |

package/bin/ctx.js

@@ -69,6 +69,8 @@ Usage:
   ctx sync --workflows --dry-run
   ctx sync --skills --dry-run
   ctx sync --skills --no-collect
+  ctx sync --skills --no-embeddings
+  ctx sync --skills --verbose
   ctx sync --skills --agents codex,claude,antigravity
   ctx embeddings warm -- "task"
   ctx ruler -- <ruler args>

package/package.json

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

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

@@ -9,6 +9,7 @@ const DEFAULT_MAX_SKILLS = 2000;
 const DEFAULT_EMBEDDING_CANDIDATES = 120;
 const DEFAULT_SEMANTIC_CATALOG_LIMIT = 300;
 const SCAN_CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_DESCRIPTION_CHARS = 500;
 
 const scanCache = new Map();
 
@@ -36,11 +37,15 @@ export function parseSkillFrontmatter(content = "", { fallbackName = "", skillPa
   const fallbackDescription = firstParagraph(body);
   return {
     name: fields.name || fallbackName || path.basename(path.dirname(skillPath)),
-    description: fields.description || fallbackDescription,
+    description: truncateDescription(fields.description || fallbackDescription),
     path: skillPath
   };
 }
 
+function truncateDescription(value) {
+  return String(value || "").replace(/\s+/g, " ").trim().slice(0, MAX_DESCRIPTION_CHARS);
+}
+
 function parseYamlishFields(frontmatter) {
   const fields = {};
   const lines = String(frontmatter || "").split(/\r?\n/);
@@ -65,7 +70,7 @@ function firstParagraph(body) {
 export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd }), maxSkills = DEFAULT_MAX_SKILLS } = {}) {
   const cacheKey = `${path.resolve(cwd)}\0${maxSkills}\0${roots.map((root) => path.resolve(root)).join("\0")}`;
   const cached = scanCache.get(cacheKey);
-  if (cached && Date.now() - cached.createdAt < SCAN_CACHE_TTL_MS) {
+  if (cached && monotonicNow() - cached.createdAt < SCAN_CACHE_TTL_MS) {
     return cached.skills;
   }
 
@@ -73,7 +78,7 @@ export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd
   const seen = new Set();
   for (const root of roots) {
     for (const skillPath of findSkillFiles(root)) {
-      if (skills.length >= maxSkills) return skills;
+      if (skills.length >= maxSkills) return cacheAndReturnSkills(cacheKey, skills);
       const realPath = safeRealpath(skillPath) || skillPath;
       if (seen.has(realPath)) continue;
       seen.add(realPath);
@@ -88,15 +93,23 @@ export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd
         skillPath
       });
       if (!skill.name || !skill.description) continue;
-      skills.push({
+      skills.push(enrichSkill({
         ...skill,
         root,
         scope: isInsidePath(skillPath, cwd) ? "project" : "global",
         relativePath: path.relative(cwd, skillPath)
-      });
+      }));
     }
   }
-  scanCache.set(cacheKey, { createdAt: Date.now(), skills });
+  return cacheAndReturnSkills(cacheKey, skills);
+}
+
+function monotonicNow() {
+  return globalThis.performance?.now?.() || Date.now();
+}
+
+function cacheAndReturnSkills(cacheKey, skills) {
+  scanCache.set(cacheKey, { createdAt: monotonicNow(), skills });
   return skills;
 }
 
@@ -208,23 +221,23 @@ function scoreSkillsByKeyword({ prompt, skills }) {
   const normalizedPrompt = normalize(prompt);
   const promptTokens = new Set(normalizedPrompt.split(/\s+/).filter(Boolean));
   return skills.map((skill, index) => {
-    const name = String(skill.name || "");
-    const description = String(skill.description || "");
+    const enriched = skill.searchTokens ? skill : enrichSkill(skill);
+    const name = String(enriched.name || "");
+    const description = truncateDescription(enriched.description || "");
     const content = `${name} ${description}`;
-    const skillTokens = new Set(normalize(content).split(/\s+/).filter(Boolean));
-    const matches = [...skillTokens].filter((token) => promptTokens.has(token) && token.length > 2);
-    const normalizedName = normalize(name);
-    const nameTokens = normalizedName.split(/\s+/).filter((token) => token.length > 2);
+    const matches = enriched.searchTokens.filter((token) => promptTokens.has(token) && token.length > 2);
+    const normalizedName = enriched.normalizedName;
+    const nameTokens = enriched.nameTokens;
     const nameHit = normalizedPrompt.includes(normalizedName);
     const nameTokenHit = nameTokens.length > 1 && nameTokens.every((token) => promptTokens.has(token));
-    const scopeBonus = skill.scope === "project" ? 0.08 : 0;
+    const scopeBonus = enriched.scope === "project" ? 0.08 : 0;
     const score = Math.min(1, (matches.length ? 0.25 + matches.length * 0.08 : 0) + (nameHit ? 0.2 : 0) + (nameTokenHit ? 0.18 : 0) + scopeBonus);
     return {
       id: `skill-${index + 1}`,
       name,
       description,
-      path: skill.path,
-      scope: skill.scope,
+      path: enriched.path,
+      scope: enriched.scope,
       content,
       score,
       keywordScore: score,
@@ -237,6 +250,21 @@ function scoreSkillsByKeyword({ prompt, skills }) {
   });
 }
 
+function enrichSkill(skill) {
+  const name = String(skill.name || "");
+  const description = truncateDescription(skill.description || "");
+  const normalizedName = normalize(name);
+  const searchTokens = [...new Set(normalize(`${name} ${description}`).split(/\s+/).filter(Boolean))];
+  const nameTokens = normalizedName.split(/\s+/).filter((token) => token.length > 2);
+  return {
+    ...skill,
+    description,
+    normalizedName,
+    nameTokens,
+    searchTokens
+  };
+}
+
 function normalize(value) {
   return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
 }

package/plugins/ctx/lib/skillshare-sync.js

@@ -41,6 +41,8 @@ export function parseSyncSkillsArgs(args = []) {
     agents,
     dryRun: args.includes("--dry-run"),
     noCollect: args.includes("--no-collect"),
+    noEmbeddings: args.includes("--no-embeddings"),
+    verbose: args.includes("--verbose"),
     yes: args.includes("--yes") || args.includes("-y")
   };
 }
@@ -367,13 +369,18 @@ export async function syncSkills({
 
   const syncArgs = ["sync"];
   if (options.dryRun) syncArgs.push("--dry-run");
+  if (!options.verbose) syncArgs.push("--quiet");
   if (options.agents.length) syncArgs.push("--agents", options.agents.join(","));
-  run("skillshare", syncArgs, { cwd, stdio: "inherit", dryRun: false });
+  logger(statusLine("Running skillshare sync...", "started"));
+  run("skillshare", syncArgs, { cwd, stdio: options.verbose ? "inherit" : "pipe", dryRun: false });
   const syncedCount = countSkillFiles(skillshareSourceDir({ home }));
   logger(statusLine("Running skillshare sync...", options.dryRun ? "dry-run" : `✓ ${syncedCount} skills → ${options.agents.join(", ")}`));
 
-  let embeddings = { count: 0, cachePath: null, skipped: options.dryRun };
-  if (!options.dryRun) {
+  let embeddings = { count: 0, cachePath: null, skipped: options.dryRun || options.noEmbeddings };
+  if (options.noEmbeddings) {
+    logger(statusLine("Rebuilding skill embeddings...", "skipped by --no-embeddings"));
+  } else if (!options.dryRun) {
+    logger(statusLine("Rebuilding skill embeddings...", `started (${syncedCount} skills)`));
     embeddings = await rebuildSkillEmbeddings({ cwd, home, sourceDir: skillshareSourceDir({ home }) });
     logger(statusLine("Rebuilding skill embeddings...", `✓ ${embeddings.count || 0} skills indexed`));
   } else {