@minhpnq1807/contextos 0.5.49 → 0.5.51

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.51
+
+- **Faster prompt fallback:** Direct prompt-hook fallback now skips embedding work and uses a shorter timeout, so context injection can still return deterministic rule, file, skill, and workflow candidates when MCP or semantic scoring is unavailable.
+- **Shared skill index fallback:** Skill discovery now warms a shared global skill index and searches it when the workspace-specific skill index has no matches, improving reuse across projects.
+- **Agent-visible skill dedupe:** Community skill installs and skill sync now remove duplicate skills visible through shared, Codex, and Antigravity roots while preserving unique agent-specific skills.
+- **Workspace prompt path detection:** Explicit file paths in prompts now tolerate line and column suffixes and can resolve files from workspace packages, improving suggested-file accuracy in monorepos.
+
+## 0.5.50
+
+- **Explicit skill activation:** Prompt skills named with `$skill-name` are now preserved and ranked before semantic suggestions, so user-requested skills such as `$threejs` or `$design-taste-frontend` appear in prompt context even when semantic ranking would not select them.
+- **Agents skill root discovery:** Skill discovery now scans project and global `.agents/skills` roots in addition to Codex, Claude, Gemini, and skillshare roots.
+
 ## 0.5.49
 
 - **Cold-cache MCP smoke:** `npm run test:mcp` now verifies the MCP tool contract without requiring a pre-downloaded ContextOS embedding model. When the model exists it still runs the semantic/performance smoke; otherwise it asserts cold-cache fallback behavior so publish CI does not fail before model warmup.

package/bin/ctx.js

@@ -29,7 +29,7 @@ import { installCopilotMcp } from "../plugins/ctx/lib/copilot-mcp.js";
 import { readCodexMcpServers, syncRules } from "../plugins/ctx/lib/ruler-sync.js";
 import { detectGraphStrategy, embedCodeReviewGraph, formatCodeReviewGraphEmbedding, formatGraphStrategy } from "../plugins/ctx/lib/graph-strategy.js";
 import { writeInnerGitignore, ensureRootGitignore } from "../plugins/ctx/lib/gitignore.js";
-import { repairSkillSymlinks, syncSkills, detectExistingSkills } from "../plugins/ctx/lib/skillshare-sync.js";
+import { dedupeAgentVisibleSkills, repairSkillSymlinks, syncSkills, detectExistingSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
 import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
 import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
@@ -143,6 +143,10 @@ async function runCommunitySkillInstaller(agents = []) {
         if (afterRepair.repaired.length || afterRepair.removedBroken.length) {
           console.log(`${DIM}│${RESET}  Repaired ${afterRepair.repaired.length} skill links after install.`);
         }
+        const deduped = dedupeAgentVisibleSkills({ cwd: process.cwd(), home: os.homedir(), agents });
+        if (deduped.removed.length) {
+          console.log(`${DIM}│${RESET}  Removed ${deduped.removed.length} duplicate agent-visible skills.`);
+        }
         successCount++;
 
         if (installInfo.verify) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.49",
+  "version": "0.5.51",
   "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.49",
+  "version": "0.5.51",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/analyzer.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { findGraphRelevantFiles, mergeRelevantFiles } from "./graph-retriever.js";
 import { expandImportGraph } from "./import-graph.js";
 import { findEmbeddingRelevantFiles } from "./file-embedding-retriever.js";
+import { workspacePackagePaths } from "./project-profiler.js";
 
 const STOP_WORDS = new Set([
   "a", "an", "and", "are", "as", "at", "be", "by", "cho", "co", "cua", "do", "fix", "for",
@@ -433,9 +434,9 @@ function addAll(target, values) {
 export function findExplicitPromptFiles({ cwd = process.cwd(), task = "", limit = 6 } = {}) {
   const candidates = new Set();
   const normalizedTask = String(task || "").replace(/\/\s+/g, "/");
-  const matches = normalizedTask.match(/[A-Za-z0-9_.()[\]@~:-]+(?:\/[A-Za-z0-9_.()[\]@~:-]+)+/g) || [];
+  const matches = normalizedTask.match(/[A-Za-z0-9_.()[\]@~:,-]+(?:\/[A-Za-z0-9_.()[\]@~:,-]+)+/g) || [];
   for (const match of matches) {
-    const cleaned = match.replace(/[),.;:]+$/g, "");
+    const cleaned = cleanPromptFilePath(match);
     for (const filePath of resolvePromptPathCandidates({ cwd, promptPath: cleaned })) {
       candidates.add(filePath);
       if (candidates.size >= limit) break;
@@ -450,6 +451,13 @@ export function findExplicitPromptFiles({ cwd = process.cwd(), task = "", limit
   }));
 }
 
+function cleanPromptFilePath(value) {
+  return String(value || "")
+    .replace(/\.(tsx?|jsx?|mjs|cjs|json|md|sql|py)\(\d+(?:,\d+)?\)[),.;:]*$/i, ".$1")
+    .replace(/\.(tsx?|jsx?|mjs|cjs|json|md|sql|py):\d+(?::\d+)?[),.;:]*$/i, ".$1")
+    .replace(/[),.;:]+$/g, "");
+}
+
 function resolvePromptPathCandidates({ cwd, promptPath }) {
   if (!promptPath || promptPath.includes("://")) return [];
   const relative = promptPath.replace(/^\.?\//, "");
@@ -470,6 +478,13 @@ function resolvePromptPathCandidates({ cwd, promptPath }) {
       if (isSourceFile(candidate)) resolved.push(path.relative(cwd, candidate));
     }
   }
+  if (!resolved.length && !relative.startsWith("..")) {
+    for (const packagePath of workspacePackagePaths(cwd).slice(1)) {
+      const packageDir = path.dirname(packagePath);
+      const candidate = path.join(packageDir, relative);
+      if (isSourceFile(candidate)) resolved.push(path.relative(cwd, candidate));
+    }
+  }
   return resolved;
 }
 

package/plugins/ctx/lib/auto-warm.js

@@ -57,6 +57,7 @@ export function maybeAutoWarmWorkspace({
 function shouldAutoWarm(reason) {
   if (reason === "no-context-candidates") return true;
   if (reason === "enabled-sections-empty-after-formatting") return true;
+  if (String(reason || "").startsWith("enabled-sections-missing-candidates:")) return true;
   return false;
 }
 

package/plugins/ctx/lib/ctx-mcp-client.js

@@ -40,6 +40,7 @@ export async function callCtxScoreContext(payload, {
     let raw = "";
     let responseTimer;
     const connectTimer = setTimeout(() => {
+      invalidateSocketIfUnchanged(socketPath, socketIdentity);
       client.destroy();
       reject(new Error(`ctx-mcp bridge connect timed out after ${connectTimeoutMs}ms`));
     }, connectTimeoutMs);
@@ -47,6 +48,7 @@ export async function callCtxScoreContext(payload, {
     client.on("connect", () => {
       clearTimeout(connectTimer);
       responseTimer = setTimeout(() => {
+        invalidateSocketIfUnchanged(socketPath, socketIdentity);
         client.destroy();
         reject(new Error(`ctx-mcp bridge timed out after ${timeoutMs}ms`));
       }, timeoutMs);

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

@@ -3,6 +3,8 @@ import path from "node:path";
 import { writeJsonFile } from "./fs-utils.js";
 import { defaultDataRoot, workspaceDataDir } from "./workspace-data.js";
 
+let pendingStdoutWrites = 0;
+
 export async function readStdinJson() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -13,13 +15,21 @@ export async function readStdinJson() {
 
 export function writeJson(value) {
   try {
-    process.stdout.write(`${JSON.stringify(value)}\n`);
+    pendingStdoutWrites += 1;
+    process.stdout.write(`${JSON.stringify(value)}\n`, () => {
+      pendingStdoutWrites = Math.max(0, pendingStdoutWrites - 1);
+    });
   } catch (error) {
+    pendingStdoutWrites = Math.max(0, pendingStdoutWrites - 1);
     if (error?.code !== "EPIPE") throw error;
   }
 }
 
 export function exitAfterStdout(code = 0) {
+  if (pendingStdoutWrites > 0) {
+    setImmediate(() => exitAfterStdout(code));
+    return;
+  }
   if (process.stdout.writableNeedDrain) {
     process.stdout.once("drain", () => process.exit(code));
     return;

package/plugins/ctx/lib/project-profiler.js

@@ -6,6 +6,7 @@ const PROFILE_CACHE_FILE = "project-profile.json";
 const MAX_DEPENDENCIES = 80;
 const MAX_SCRIPTS = 30;
 const MAX_RECENT_FILES = 20;
+const MAX_FUSED_PROFILE_CHARS = 500;
 
 export function projectProfile({ cwd = process.cwd(), dataDir } = {}) {
   const fingerprint = projectFingerprint(cwd);
@@ -30,7 +31,10 @@ export function projectProfile({ cwd = process.cwd(), dataDir } = {}) {
 
 export function fusedProjectQuery({ prompt = "", cwd = process.cwd(), dataDir } = {}) {
   const profile = projectProfile({ cwd, dataDir });
-  return [String(prompt || "").trim(), profile.embeddableString].filter(Boolean).join("\n");
+  const profileSignal = profile.embeddableString
+    ? profile.embeddableString.slice(0, MAX_FUSED_PROFILE_CHARS)
+    : "";
+  return [String(prompt || "").trim(), profileSignal].filter(Boolean).join("\n");
 }
 
 function readCachedProfile(cachePath, fingerprint) {

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

@@ -21,7 +21,7 @@ export async function handlePromptPayload(
     autoWarmWorkspace = maybeAutoWarmWorkspace,
     mcpDataDir,
     outputConfig,
-    directFallbackTimeoutMs = Number(process.env.CONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS || 6000)
+    directFallbackTimeoutMs = Number(process.env.CONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS || 2500)
   } = {}
 ) {
   const prompt = payload.prompt || payload.message || payload.user_prompt || "";
@@ -55,6 +55,7 @@ export async function handlePromptPayload(
         maxSkills: promptLimits.skills,
         maxWorkflows: promptLimits.workflows,
         dataDir: mcpDataDir || dataDir,
+        allowEmbeddings: false,
         embeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS || 500),
         fileEmbeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS || 1000),
         skillEmbeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_SKILL_EMBEDDING_TIMEOUT_MS || 2000)
@@ -197,6 +198,9 @@ function emptyContextReason({ scheduled, outputConfig, injectContext }) {
   if (scheduled.suggestedSkills?.length) available.push("skills");
   if (scheduled.suggestedWorkflows?.length) available.push("workflows");
   if (!available.length) return "no-context-candidates";
+  const enabledMissing = ["rules", "files", "skills", "workflows"]
+    .filter((section) => sections[section] !== false && !available.includes(section));
+  if (enabledMissing.length) return `enabled-sections-missing-candidates:${enabledMissing.join(",")}`;
   const enabled = available.filter((section) => sections[section] !== false);
   return enabled.length ? "enabled-sections-empty-after-formatting" : `available-sections-disabled:${available.join(",")}`;
 }

package/plugins/ctx/lib/score-context.js

@@ -19,7 +19,8 @@ export async function scoreContext({
   embeddingTimeoutMs = 5000,
   fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 1000),
   skillEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || embeddingTimeoutMs),
-  skillSearchOptions = {}
+  skillSearchOptions = {},
+  allowEmbeddings = true
 } = {}) {
   const started = Date.now();
   const ruleInputsPromise = Promise.resolve().then(() => {
@@ -35,6 +36,14 @@ export async function scoreContext({
   });
 
   const rulesPromise = ruleInputsPromise.then(({ merged, baseScoredRules }) => {
+    if (!allowEmbeddings) {
+      return {
+        rules: baseScoredRules,
+        status: "disabled",
+        model: null,
+        cachePath: dataDir
+      };
+    }
     return enhanceRuleScoresWithEmbeddings(baseScoredRules, prompt, {
       dataDir,
       sources: merged.sources,
@@ -52,6 +61,7 @@ export async function scoreContext({
       limit: maxFiles,
       fileEmbeddingTimeoutMs,
       fileEmbeddingOptions: {
+        enabled: allowEmbeddings,
         allowRemote: false
       }
     });
@@ -68,6 +78,7 @@ export async function scoreContext({
         dataDir,
         limit: maxSkills,
         timeoutMs: skillEmbeddingTimeoutMs,
+        embeddingsEnabled: allowEmbeddings,
         ...skillSearchOptions
       })
     };
@@ -77,7 +88,7 @@ export async function scoreContext({
     const catalog = Array.isArray(workflows) ? workflows : scanWorkflows({ cwd });
     return {
       catalog,
-      suggestions: await suggestWorkflows({ prompt, workflows: catalog, dataDir, limit: maxWorkflows })
+      suggestions: await suggestWorkflows({ prompt, workflows: catalog, dataDir, limit: maxWorkflows, embeddingsEnabled: allowEmbeddings })
     };
   });
 

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

@@ -22,11 +22,13 @@ const scanCache = new Map();
 export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
   return [
     path.join(cwd, ".codex", "skills"),
+    path.join(cwd, ".agents", "skills"),
     path.join(cwd, ".claude", "skills"),
     path.join(cwd, ".gemini", "skills"),
     path.join(cwd, ".gemini", "antigravity", "skills"),
     path.join(cwd, ".gemini", "antigravity-cli", "skills"),
     path.join(home, ".codex", "skills"),
+    path.join(home, ".agents", "skills"),
     path.join(home, ".claude", "skills"),
     path.join(home, ".config", "skillshare", "skills"),
     path.join(home, ".gemini", "skills"),
@@ -165,36 +167,36 @@ export async function suggestSkills({
   limit = DEFAULT_LIMIT,
   timeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || DEFAULT_SKILL_TIMEOUT_MS),
   indexedSearcher = searchIndexedEmbeddings,
-  embeddingEnhancer = enhanceRuleScoresWithEmbeddings
+  embeddingEnhancer = enhanceRuleScoresWithEmbeddings,
+  embeddingsEnabled = true
 } = {}) {
   if (!String(prompt || "").trim() || !skills.length) return [];
   const catalog = dedupeSkills(skills);
-  const query = fusedProjectQuery({ prompt, cwd, dataDir });
+  const query = skillQuery({ prompt, cwd, dataDir });
   const byId = new Map(catalog.map((skill) => [skillIndexId(skill), skill]));
+  const explicitSkills = explicitSkillSuggestions({ prompt, byId });
+  if (!embeddingsEnabled) return finalizeSkillScores(explicitSkills, limit);
 
   if (dataDir) {
-    const indexed = await indexedSearcher({
-      kind: skillIndexKind(cwd),
-      task: query,
-      dataDir,
-      timeoutMs,
-      allowRemote: false
-    });
+    const indexed = await searchSkillIndexes({ cwd, query, dataDir, timeoutMs, indexedSearcher });
     if (indexed.status === "enabled" && indexed.items.length) {
-      return finalizeSkillScores(indexed.items
+      return finalizeSkillScores([
+        ...explicitSkills,
+        ...indexed.items
         .map((item) => {
           const skill = byId.get(item.id);
           if (!skill) return null;
           return skillScoreFromEmbedding(skill, item.embeddingScore, [`embedding:${Number(item.embeddingScore || 0).toFixed(2)}`]);
         })
-        .filter(Boolean), limit);
+        .filter(Boolean)
+      ], limit);
     }
   }
 
-  if (catalog.length > DEFAULT_EMBEDDING_CANDIDATES) return [];
+  if (catalog.length > DEFAULT_EMBEDDING_CANDIDATES) return finalizeSkillScores(explicitSkills, limit);
 
   const embeddingCandidates = catalog.map((skill, index) => skillRule({ skill, index }));
-  if (!embeddingCandidates.length) return [];
+  if (!embeddingCandidates.length) return finalizeSkillScores(explicitSkills, limit);
 
   const embedding = await embeddingEnhancer(embeddingCandidates, query, {
     dataDir,
@@ -203,7 +205,36 @@ export async function suggestSkills({
     allowRemote: false
   });
 
-  return finalizeSkillScores(embedding.rules, limit);
+  return finalizeSkillScores([...explicitSkills, ...embedding.rules], limit);
+}
+
+function skillQuery({ prompt = "", cwd = process.cwd(), dataDir } = {}) {
+  const focusedPrompt = String(prompt || "").trim();
+  const fused = fusedProjectQuery({ prompt, cwd, dataDir });
+  return [focusedPrompt, focusedPrompt, fused].filter(Boolean).join("\n");
+}
+
+function explicitSkillSuggestions({ prompt = "", byId = new Map() } = {}) {
+  const names = extractExplicitSkillNames(prompt);
+  return names
+    .map((name, index) => ({ skill: byId.get(normalize(name)), index }))
+    .filter(({ skill }) => Boolean(skill))
+    .map(({ skill, index }) => skillScoreFromEmbedding(skill, 1 - index * 0.0001, ["explicit-skill"]));
+}
+
+function extractExplicitSkillNames(prompt = "") {
+  const names = [];
+  const seen = new Set();
+  const pattern = /(?:^|[\s([{,])\$([A-Za-z0-9][A-Za-z0-9_.:-]*)/g;
+  let match;
+  while ((match = pattern.exec(String(prompt || "")))) {
+    const name = match[1];
+    const key = normalize(name);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    names.push(name);
+  }
+  return names;
 }
 
 function finalizeSkillScores(skills, limit) {
@@ -246,7 +277,7 @@ export async function warmSkillEmbeddings({
 } = {}) {
   if (!dataDir || !skills.length) return { count: 0, cachePath: null };
   const catalog = dedupeSkills(skills);
-  return warmIndexedEmbeddings({
+  const workspaceResult = await warmIndexedEmbeddings({
     kind: skillIndexKind(cwd),
     items: catalog.map((skill) => ({
       id: skillIndexId(skill),
@@ -257,6 +288,19 @@ export async function warmSkillEmbeddings({
     sources: catalog.map((skill) => skill.path).filter(Boolean),
     allowRemote
   });
+  if (workspaceResult.status === "missing-model" || workspaceResult.status === "warm-failed") return workspaceResult;
+  await warmIndexedEmbeddings({
+    kind: sharedSkillIndexKind(),
+    items: catalog.map((skill) => ({
+      id: skillIndexId(skill),
+      text: skillEmbeddingText(skill)
+    })),
+    task: fusedProjectQuery({ prompt: "skill discovery semantic retrieval", cwd, dataDir }),
+    dataDir,
+    sources: catalog.map((skill) => skill.path).filter(Boolean),
+    allowRemote
+  });
+  return workspaceResult;
 }
 
 function skillRule({ skill, index }) {
@@ -314,6 +358,30 @@ function skillIndexKind(cwd) {
   return `skill:${path.resolve(cwd)}`;
 }
 
+function sharedSkillIndexKind() {
+  return "skill:global";
+}
+
+async function searchSkillIndexes({ cwd, query, dataDir, timeoutMs, indexedSearcher }) {
+  const workspace = await indexedSearcher({
+    kind: skillIndexKind(cwd),
+    task: query,
+    dataDir,
+    timeoutMs,
+    allowRemote: false
+  });
+  if (workspace.status === "enabled" && workspace.items.length) return workspace;
+  const shared = await indexedSearcher({
+    kind: sharedSkillIndexKind(),
+    task: query,
+    dataDir,
+    timeoutMs,
+    allowRemote: false
+  });
+  if (shared.status === "enabled" && shared.items.length) return shared;
+  return workspace.status === "enabled" ? workspace : shared;
+}
+
 function skillIndexId(skill) {
   return normalize(skill.name);
 }

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

@@ -244,6 +244,106 @@ export function repairSkillSymlinks({
   return { repaired: [...new Set(repaired)], removedBroken: [...new Set(removedBroken)] };
 }
 
+export function dedupeAgentVisibleSkills({
+  cwd = process.cwd(),
+  home = os.homedir(),
+  agents = DEFAULT_AGENTS,
+  dryRun = false
+} = {}) {
+  const roots = visibleSkillRootsForAgents({ cwd, home, agents });
+  const seen = new Map();
+  const kept = [];
+  const removed = [];
+
+  for (const root of roots) {
+    for (const skill of listSkillsInRoot(root)) {
+      const previous = seen.get(skill.key);
+      if (!previous) {
+        seen.set(skill.key, skill);
+        kept.push(skill.path);
+        continue;
+      }
+
+      const previousReal = safeRealpath(previous.path);
+      const currentReal = safeRealpath(skill.path);
+      if (previousReal && currentReal && previousReal === currentReal) {
+        if (!dryRun) fs.rmSync(skill.path, { force: true, recursive: true });
+        removed.push(skill.path);
+        continue;
+      }
+
+      if (!dryRun) fs.rmSync(skill.path, { force: true, recursive: true });
+      removed.push(skill.path);
+    }
+  }
+
+  return { kept: [...new Set(kept)], removed: [...new Set(removed)], roots };
+}
+
+function visibleSkillRootsForAgents({ cwd, home, agents }) {
+  const normalizedAgents = normalizeAgentList(agents);
+  const roots = [];
+  const addShared = () => {
+    roots.push(path.join(home, ".agents", "skills"));
+    roots.push(path.join(cwd, ".agents", "skills"));
+  };
+
+  addShared();
+  if (normalizedAgents.includes("codex")) {
+    roots.push(path.join(home, ".codex", "skills"));
+    roots.push(path.join(cwd, ".codex", "skills"));
+  }
+  if (normalizedAgents.includes("claude")) {
+    roots.push(path.join(home, ".claude", "skills"));
+    roots.push(path.join(cwd, ".claude", "skills"));
+  }
+  if (normalizedAgents.includes("antigravity")) {
+    roots.push(path.join(home, ".gemini", "skills"));
+    roots.push(path.join(home, ".gemini", "antigravity", "skills"));
+    roots.push(path.join(home, ".gemini", "antigravity-cli", "skills"));
+    roots.push(path.join(cwd, ".gemini", "skills"));
+    roots.push(path.join(cwd, ".gemini", "antigravity", "skills"));
+    roots.push(path.join(cwd, ".gemini", "antigravity-cli", "skills"));
+  }
+
+  return uniquePaths(roots);
+}
+
+function listSkillsInRoot(root) {
+  return findSkillFiles(root)
+    .map((skillFile) => {
+      const skillDir = path.dirname(skillFile);
+      const name = readSkillName(skillFile) || path.basename(skillDir);
+      return {
+        name,
+        key: normalizeSkillName(name),
+        path: skillDir,
+        root
+      };
+    })
+    .filter((skill) => skill.key)
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function readSkillName(skillFile) {
+  try {
+    const content = fs.readFileSync(skillFile, "utf8");
+    return content.match(/^\s*name:\s*(.+?)\s*$/m)?.[1]
+      ?.replace(/^["']|["']$/g, "")
+      .trim() || "";
+  } catch {
+    return "";
+  }
+}
+
+function normalizeSkillName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
 function skillRoots({ cwd, home }) {
   return uniquePaths([
     path.join(home, ".claude", "skills"),
@@ -503,6 +603,18 @@ export async function syncSkills({
   const syncedCount = countSkillFiles(skillshareSourceDir({ home }));
   logger(statusLine("Running skillshare sync...", options.dryRun ? "dry-run" : `✓ ${syncedCount} skills → ${options.agents.join(", ")}`));
 
+  const deduped = dedupeAgentVisibleSkills({
+    cwd,
+    home,
+    agents: options.agents,
+    dryRun: options.dryRun
+  });
+  if (deduped.removed.length) {
+    logger(statusLine("Deduping agent-visible skills...", options.dryRun
+      ? `dry-run (${deduped.removed.length} duplicates)`
+      : `✓ ${deduped.removed.length} duplicates removed`));
+  }
+
   let embeddings = { count: 0, cachePath: null, skipped: options.dryRun || options.noEmbeddings };
   if (options.noEmbeddings) {
     logger(statusLine("Rebuilding skill embeddings...", "skipped by --no-embeddings"));

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

@@ -128,12 +128,14 @@ export async function suggestWorkflows({
   workflows = [],
   dataDir,
   limit = DEFAULT_LIMIT,
-  timeoutMs = Number(process.env.CONTEXTOS_WORKFLOW_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800)
+  timeoutMs = Number(process.env.CONTEXTOS_WORKFLOW_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800),
+  embeddingsEnabled = true
 } = {}) {
   if (!String(prompt || "").trim() || !workflows.length) return [];
   const base = scoreWorkflowsByKeyword({ prompt, workflows });
   const embeddingCandidates = selectWorkflowEmbeddingCandidates(base);
   if (!embeddingCandidates.length) return [];
+  if (!embeddingsEnabled) return finalizeWorkflowScores(embeddingCandidates, limit);
 
   const embedding = await enhanceRuleScoresWithEmbeddings(embeddingCandidates, prompt, {
     dataDir,