@minhpnq1807/contextos 0.5.46 → 0.5.50

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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.
+
+## 0.5.48
+
+- **Publish-safe embedding warm:** `ctx embeddings warm` now skips remote model downloads by default in CI and returns best-effort warm results when local embedding model loading fails, preventing npm publish workflows from failing on Hugging Face 429/rate-limit errors.
+- **CI graph embedding skip:** Code-review-graph embedding refresh is skipped when remote embeddings are disabled, avoiding extra Hugging Face calls during publish jobs.
+
+## 0.5.47
+
+- **Semantic-only skill discovery:** Replaced taxonomy/keyword skill ranking with fused semantic retrieval. ContextOS now embeds `prompt + project profile` and compares it against cached skill vectors, so mixed Vietnamese/English prompts can use package, language, and recent-file signals without hard-coded categories.
+- **Project profile cache:** Added a bounded project profiler that builds an embeddable string from root/workspace `package.json` dependencies, scripts, detected languages, and recent git files. The cache invalidates when package metadata or git `HEAD` changes.
+- **Skill dedupe and activation format:** Skill catalogs are deduplicated by normalized skill name before indexing/searching, preferring project and Codex roots. Prompt output now renders skill activations as `$skill-name`.
+- **Refresh rebuilds skill index:** `ctx install` and `ctx refresh` now rebuild the skill embedding index by default because prompt-time skill discovery no longer falls back to taxonomy or keyword ranking for large catalogs.
+- **Skill hook timeout split:** Prompt hooks now use a separate skill embedding timeout, so large indexed skill catalogs can still produce suggestions after direct fallback without slowing rule scoring.
+- **Read-only embedding cache close:** Prompt-time embedding reads no longer rewrite the whole `embeddings.db` when no cache entries changed.
+
 ## 0.5.46
 
 - **Configurable prompt suggestion limits:** `ctx --config` and interactive `ctx setup` now let users choose how many suggested files, skills, and workflows appear in prompt context. Defaults are five each, with caps of 20 files, 10 skills, and 5 workflows.

package/README.md

@@ -445,7 +445,7 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx skills` | Installs community skill libraries. | You want curated skills without running the full setup wizard. | Opens the community installer, uses a portable shell on Windows/Linux/macOS, repairs unsafe skill symlinks, and syncs installed skills to selected agents. |
 | `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills/workflows. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, skill, and workflow vectors to `~/.ctx/contextos/embeddings.db`. |
 | `ctx --config` | Opens an interactive panel for prompt sections and suggestion limits. | You want to reduce ContextOS prompt output noise. | Toggles critical rules, suggested files, suggested skills, and suggested workflows globally under `~/.ctx/contextos/output-config.json`, then lets you set suggestion counts for files, skills, and workflows. |
-| `ctx refresh` | Refreshes the active Codex marketplace plugin and rebuilds local indexes. | Local development updates or a stale file retrieval index. | Copies the current package to `$CODEX_HOME/marketplaces/contextos`, rebuilds file-path embeddings and import adjacency, and refreshes code-review-graph embeddings when available. |
+| `ctx refresh` | Refreshes the active Codex marketplace plugin and rebuilds local indexes. | Local development updates or stale file/skill retrieval indexes. | Copies the current package to `$CODEX_HOME/marketplaces/contextos`, rebuilds file-path embeddings, skill embeddings, import adjacency, and refreshes code-review-graph embeddings when available. |
 | `ctx ruler -- <args>` | Forwards args to the installed `ruler` CLI. | You need native Ruler commands such as `init`, `apply`, or `revert`. | Preserves Ruler stdout/stderr and exit status. |
 | `ctx skillshare -- <args>` | Forwards args to the installed `skillshare` CLI. | You need native skillshare commands such as `status`, `target list`, `doctor`, `push`, or `pull`. | Preserves skillshare stdout/stderr and exit status. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
@@ -511,17 +511,23 @@ This keeps the hook fast and local while still using graph semantics when availa
 
 Prompt scoring does not walk the repository for file candidates or import expansion. `ctx install` and `ctx embeddings warm` rebuild the persisted file-vector index and one-hop import adjacency index by walking source paths once; prompt hooks query those indexes directly. Rules, files, skills, and workflows are scored concurrently with `Promise.all()`.
 
-`ctx embeddings warm` automatically refreshes the active Codex marketplace payload before rebuilding indexes. Use `ctx refresh` when you want the same marketplace sync plus install-style file/import index and code-review-graph embedding refresh in one command.
+`ctx embeddings warm` automatically refreshes the active Codex marketplace payload before rebuilding indexes. Use `ctx refresh` when you want the same marketplace sync plus install-style file, skill, import, and code-review-graph embedding refresh in one command.
 
 If a prompt has no usable context candidates, the hook fails open without emitting an empty `hook context` block, records `emptyContextReason` in the workspace runtime file, and starts a detached `autowarm` rebuild with a cooldown. That background rebuild refreshes file vectors, skill/workflow vectors, import adjacency, and available code-review-graph node embeddings for the next prompt while keeping repository walking out of the current prompt hot path.
 
 Use `ctx --config` to choose which prompt sections ContextOS injects and how many suggestions each section may show. Interactive `ctx setup` includes the same section picker and limit prompts, while `ctx setup --yes` keeps the current saved config for automation. The panel supports multiple selection with `Space` and persists the global choice in `~/.ctx/contextos/output-config.json`. Defaults are five suggested files, five skills, and five workflows; caps are 20 files, 10 skills, and 5 workflows. Disabling rules hides both critical and additional relevant rule sections; compliance metadata remains available for reports.
 
-Injected prompt sections are intentionally compact: rules show only detected rule text, files show a comma-separated inline list of basenames without paths, skills show unique names as a comma-separated inline list without descriptions, and workflows show names with their agent chain. Stop hooks persist reports silently; run `ctx report` or `ctx evidence` when you want the detailed compliance output.
+Injected prompt sections are intentionally compact: rules show only detected rule text, files show a comma-separated inline list of basenames without paths, skills show unique `$skill-name` activations as a comma-separated inline list without descriptions, and workflows show names with their agent chain. Stop hooks persist reports silently; run `ctx report` or `ctx evidence` when you want the detailed compliance output.
 
 Codex may flatten newlines in its `UserPromptSubmit hook (completed)` preview. The injected `additionalContext` payload remains multiline; this is a Codex preview display limitation.
 
-Skill ranking uses bounded project hints from root/workspace `package.json` files and known mobile config files such as `app.json`, `app.config.*`, and `eas.json`. This lets Expo/EAS and MCP tasks activate specialized skills without walking the source tree on every prompt. Document-authoring prompts also get explicit intent handling for README, wiki, workspace documentation, guides, specs, and ADR work, while document-processing or workspace-automation providers only rank highly when the prompt actually names that provider or processing task.
+Skill ranking is semantic-only. ContextOS builds a fused query from the user prompt plus a cached project profile, then compares that vector with cached skill vectors:
+
+```text
+embed(prompt + project profile) -> cosine -> embed(skill name + description)
+```
+
+The project profile is an embeddable string built from bounded root/workspace `package.json` metadata, dependencies, scripts, detected languages, and recent git files. It is cached under the ContextOS workspace data directory and invalidated when package metadata or git `HEAD` changes. ContextOS does not maintain a skill taxonomy or domain gate list for ranking; if the skill index is cold for a large catalog, prompt hooks fail open instead of falling back to arbitrary keyword matches. Skill catalogs are deduplicated by normalized skill name before indexing and rendering.
 
 After `ctx refresh`, ContextOS invalidates the private hook bridge socket so prompts fall back to direct scoring until Codex restarts the long-running `ctx-mcp` process. Hook clients also discard a same-inode socket if an older bridge revision is detected.
 
@@ -538,6 +544,8 @@ CONTEXTOS_HOOK_DEADLINE_MS=8500 hard fail-open deadline for prompt hooks
 CONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS=6000 direct scoring timeout when the bridge is unavailable
 CONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS=500 rule embedding timeout during hook direct fallback
 CONTEXTOS_EMBEDDING_TIMEOUT_MS=800 embedding scoring timeout inside ctx-mcp/debug
+CONTEXTOS_HOOK_SKILL_EMBEDDING_TIMEOUT_MS=2000 skill retrieval timeout during hook direct fallback
+CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS=2000 skill retrieval timeout inside ctx-mcp/debug
 CONTEXTOS_FILE_EMBEDDINGS=0       disable file-path embedding retrieval
 CONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS=500 file retrieval timeout during hook direct fallback
 CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS=1000 file-path embedding retrieval timeout

package/bin/ctx.js

@@ -487,6 +487,7 @@ function graphStrategyForInstall() {
 async function warmInstallEmbeddings() {
   const dataDir = contextOSDataDir();
   const modelReady = isModelCacheReady(dataDir);
+  const allowRemote = shouldAllowRemoteWarm(modelReady);
   const result = await warmRuleEmbeddings({
     rules: [
       { content: "Always use project rules that are semantically relevant to the user prompt." },
@@ -496,29 +497,29 @@ async function warmInstallEmbeddings() {
     task: "kiểm duyệt upload moderation semantic code search",
     dataDir,
     sources: [],
-    allowRemote: !modelReady
+    allowRemote
   });
   const fileResult = await warmFileEmbeddings({
     cwd: process.cwd(),
     dataDir,
-    allowRemote: !modelReady
+    allowRemote
+  });
+  const skillResult = await warmSkillEmbeddings({
+    cwd: process.cwd(),
+    dataDir,
+    allowRemote
   });
   const warmDiscovery = process.env.CONTEXTOS_INSTALL_WARM_DISCOVERY === "1";
-  const skillResult = warmDiscovery
-    ? await warmSkillEmbeddings({
-      cwd: process.cwd(),
-      dataDir,
-      allowRemote: !modelReady
-    })
-    : { count: 0 };
   const workflowResult = warmDiscovery
     ? await warmWorkflowEmbeddings({
       cwd: process.cwd(),
       dataDir,
-      allowRemote: !modelReady
+      allowRemote
     })
     : { count: 0 };
-  const graphEmbedding = embedCodeReviewGraph({ cwd: process.cwd() });
+  const graphEmbedding = allowRemote
+    ? embedCodeReviewGraph({ cwd: process.cwd() })
+    : { status: "skipped", reason: "remote-embedding-disabled" };
   return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count, skillCount: skillResult.count, workflowCount: workflowResult.count, graphEmbedding };
 }
 
@@ -663,31 +664,36 @@ async function warmEmbeddings(task, { syncMarketplace = true, quiet = false } =
 
 async function warmWorkspaceIndexes({ task = "project context" } = {}) {
   const cwd = process.cwd();
+  const dataDir = contextOSDataDir();
+  const modelReady = isModelCacheReady(dataDir);
+  const allowRemote = shouldAllowRemoteWarm(modelReady);
   const merged = readAgentsChain({ cwd });
   const rules = scoreRules(filterActionableRules(parseRules(merged.content)), task, []);
   const result = await warmRuleEmbeddings({
     rules,
     task,
-    dataDir: contextOSDataDir(),
+    dataDir,
     sources: merged.sources,
-    allowRemote: true
+    allowRemote
   });
   const fileResult = await warmFileEmbeddings({
     cwd,
-    dataDir: contextOSDataDir(),
-    allowRemote: true
+    dataDir,
+    allowRemote
   });
   const skillResult = await warmSkillEmbeddings({
     cwd,
-    dataDir: contextOSDataDir(),
-    allowRemote: true
+    dataDir,
+    allowRemote
   });
   const workflowResult = await warmWorkflowEmbeddings({
     cwd,
-    dataDir: contextOSDataDir(),
-    allowRemote: true
+    dataDir,
+    allowRemote
   });
-  const graphEmbedding = embedCodeReviewGraph({ cwd });
+  const graphEmbedding = allowRemote
+    ? embedCodeReviewGraph({ cwd })
+    : { status: "skipped", reason: "remote-embedding-disabled" };
   return {
     ruleCount: result.count,
     fileCount: fileResult.count,
@@ -698,12 +704,28 @@ async function warmWorkspaceIndexes({ task = "project context" } = {}) {
   };
 }
 
+function shouldAllowRemoteWarm(modelReady) {
+  if (modelReady) return false;
+  if (process.env.CONTEXTOS_EMBEDDING_ALLOW_REMOTE !== undefined) {
+    return process.env.CONTEXTOS_EMBEDDING_ALLOW_REMOTE === "1";
+  }
+  return !isCiEnvironment();
+}
+
+function isCiEnvironment() {
+  return process.env.CI === "true"
+    || process.env.GITHUB_ACTIONS === "true"
+    || process.env.CONTINUOUS_INTEGRATION === "true"
+    || process.env.BUILD_ID !== undefined
+    || process.env.RUN_ID !== undefined;
+}
+
 async function refresh() {
   const marketplaceSync = syncActiveCodexMarketplace();
   const invalidatedBridge = invalidateCtxMcpSocket(contextOSDataDir());
   const warmResult = await warmInstallEmbeddings();
   console.log(`Marketplace: ${marketplaceSync.synced ? "synced" : "already active"} (${marketplaceSync.targetRoot})`);
-  console.log(`Indexes: ${warmResult.fileCount || 0} file paths rebuilt`);
+  console.log(`Indexes: ${warmResult.fileCount || 0} file paths rebuilt, ${warmResult.skillCount || 0} skills indexed`);
   console.log(`Graph embeddings: ${formatCodeReviewGraphEmbedding(warmResult.graphEmbedding)}`);
   if (invalidatedBridge) console.log("Bridge: stale private socket invalidated");
   console.log("Restart Codex if ctx-mcp was already running.");

package/package.json

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

package/plugins/ctx/lib/embedding-scorer.js

@@ -65,13 +65,28 @@ export async function warmRuleEmbeddings({
     ...rules.map((rule) => rule.content || "")
   ].filter((text) => String(text).trim()))];
 
-  const cache = await openEmbeddingCache(dataDir);
-  const embedder = await getExtractor({ allowRemote, dataDir });
-  for (const text of texts) {
-    await getCachedEmbedding({ cache, embedder, text, sources });
+  let cache;
+  try {
+    cache = await openEmbeddingCache(dataDir);
+    const embedder = await getExtractor({ allowRemote, dataDir });
+    for (const text of texts) {
+      await getCachedEmbedding({ cache, embedder, text, sources, flush: false });
+    }
+    cache.close();
+    return { count: texts.length, cachePath: cache.path, status: "enabled" };
+  } catch (error) {
+    try {
+      cache?.close();
+    } catch {
+      // Ignore close failures while reporting a best-effort warm result.
+    }
+    return {
+      count: 0,
+      cachePath: path.join(dataDir, "embeddings.db"),
+      status: "warm-failed",
+      error: error?.message || String(error)
+    };
   }
-  cache.close();
-  return { count: texts.length, cachePath: cache.path };
 }
 
 export async function searchIndexedEmbeddings({
@@ -106,20 +121,35 @@ export async function warmIndexedEmbeddings({
     return { count: 0, cachePath: path.join(dataDir, "embeddings.db"), status: "missing-model" };
   }
 
-  const cache = await openEmbeddingCache(dataDir);
-  const embedder = await getExtractor({ allowRemote, dataDir });
-  if (String(task || "").trim()) await getCachedEmbedding({ cache, embedder, text: task, sources });
-
-  const indexed = [];
-  for (const item of items) {
-    const text = String(item.text || "");
-    if (!item.id || !text.trim()) continue;
-    const vector = await getCachedEmbedding({ cache, embedder, text, sources });
-    indexed.push({ id: item.id, text, vector });
+  let cache;
+  try {
+    cache = await openEmbeddingCache(dataDir);
+    const embedder = await getExtractor({ allowRemote, dataDir });
+    if (String(task || "").trim()) await getCachedEmbedding({ cache, embedder, text: task, sources });
+
+    const indexed = [];
+    for (const item of items) {
+      const text = String(item.text || "");
+      if (!item.id || !text.trim()) continue;
+      const vector = await getCachedEmbedding({ cache, embedder, text, sources, flush: false });
+      indexed.push({ id: item.id, text, vector });
+    }
+    cache.replaceIndex(kind, indexed);
+    cache.close();
+    return { count: indexed.length, cachePath: cache.path, status: "enabled" };
+  } catch (error) {
+    try {
+      cache?.close();
+    } catch {
+      // Ignore close failures while reporting a best-effort warm result.
+    }
+    return {
+      count: 0,
+      cachePath: path.join(dataDir, "embeddings.db"),
+      status: "warm-failed",
+      error: error?.message || String(error)
+    };
   }
-  cache.replaceIndex(kind, indexed);
-  cache.close();
-  return { count: indexed.length, cachePath: cache.path };
 }
 
 async function enhanceRuleScores(rules, task, { dataDir, sources, allowRemote }) {
@@ -187,7 +217,10 @@ async function getExtractor({ allowRemote, dataDir }) {
       return transformers.pipeline("feature-extraction", DEFAULT_MODEL, {
         quantized: true
       });
-    })());
+    })().catch((error) => {
+      extractorPromises.delete(key);
+      throw error;
+    }));
   }
   return extractorPromises.get(key);
 }
@@ -206,7 +239,7 @@ export function isModelCacheReady(dataDir = defaultDataRoot()) {
   ].every((relativePath) => fs.existsSync(path.join(modelDir, relativePath)));
 }
 
-async function getCachedEmbedding({ cache, embedder, text, sources }) {
+async function getCachedEmbedding({ cache, embedder, text, sources, flush = true }) {
   const key = cacheKey(text, sources);
   const existing = cache.get(key);
   if (existing) return existing;
@@ -216,7 +249,7 @@ async function getCachedEmbedding({ cache, embedder, text, sources }) {
     normalize: true
   });
   const embedding = Array.from(output.data || []);
-  cache.set(key, embedding);
+  cache.set(key, embedding, { flush });
   return embedding;
 }
 
@@ -225,6 +258,7 @@ export async function openEmbeddingCache(dataDir) {
   const cachePath = path.join(dataDir, "embeddings.db");
   const SQL = await getSql();
   const db = initializeEmbeddingDatabase(SQL, cachePath);
+  let dirty = false;
 
   return {
     path: cachePath,
@@ -238,12 +272,16 @@ export async function openEmbeddingCache(dataDir) {
         stmt.free();
       }
     },
-    set(key, vector) {
+    set(key, vector, { flush = true } = {}) {
       db.run(
         "INSERT OR REPLACE INTO embeddings (key, model, vector, updated_at) VALUES (?, ?, ?, ?)",
         [key, DEFAULT_MODEL, JSON.stringify(vector), new Date().toISOString()]
       );
-      writeDatabaseAtomically(cachePath, db);
+      dirty = true;
+      if (flush) {
+        writeDatabaseAtomically(cachePath, db);
+        dirty = false;
+      }
     },
     listIndexed(kind) {
       const stmt = db.prepare("SELECT id, text, vector FROM embedding_index WHERE kind = ? AND model = ?");
@@ -268,9 +306,10 @@ export async function openEmbeddingCache(dataDir) {
         );
       }
       writeDatabaseAtomically(cachePath, db);
+      dirty = false;
     },
     close() {
-      writeDatabaseAtomically(cachePath, db);
+      if (dirty) writeDatabaseAtomically(cachePath, db);
       db.close();
     }
   };

package/plugins/ctx/lib/graph-strategy.js

@@ -91,6 +91,7 @@ export function formatCodeReviewGraphEmbedding(result) {
   }
   if (result.reason === "missing-graph-index") return "skipped (no .code-review-graph/graph.db)";
   if (result.reason === "missing-code-review-graph-python") return "skipped (code-review-graph Python unavailable)";
+  if (result.reason === "remote-embedding-disabled") return "skipped (remote embedding disabled)";
   return `skipped (${result.error || result.reason || "unavailable"})`;
 }
 

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

@@ -0,0 +1,207 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const PROFILE_CACHE_FILE = "project-profile.json";
+const MAX_DEPENDENCIES = 80;
+const MAX_SCRIPTS = 30;
+const MAX_RECENT_FILES = 20;
+
+export function projectProfile({ cwd = process.cwd(), dataDir } = {}) {
+  const fingerprint = projectFingerprint(cwd);
+  const cachePath = dataDir ? path.join(dataDir, PROFILE_CACHE_FILE) : null;
+  const cached = cachePath ? readCachedProfile(cachePath, fingerprint) : null;
+  if (cached) return cached;
+
+  const packagePaths = workspacePackagePaths(cwd);
+  const packageTexts = packagePaths.map((packagePath) => packageSignal(cwd, packagePath)).filter(Boolean);
+  const recentFiles = recentGitFiles(cwd, MAX_RECENT_FILES);
+  const languages = languageSignal({ cwd, packagePaths, recentFiles });
+  const embeddableString = [
+    packageTexts.length ? `[project packages: ${packageTexts.join(" | ")}]` : "",
+    languages.length ? `[project languages: ${languages.join(" ")}]` : "",
+    recentFiles.length ? `[recent files: ${recentFiles.join(", ")}]` : ""
+  ].filter(Boolean).join(" ");
+
+  const profile = { fingerprint, embeddableString };
+  if (cachePath) writeCachedProfile(cachePath, profile);
+  return profile;
+}
+
+export function fusedProjectQuery({ prompt = "", cwd = process.cwd(), dataDir } = {}) {
+  const profile = projectProfile({ cwd, dataDir });
+  return [String(prompt || "").trim(), profile.embeddableString].filter(Boolean).join("\n");
+}
+
+function readCachedProfile(cachePath, fingerprint) {
+  try {
+    const cached = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+    if (cached?.fingerprint === fingerprint && typeof cached.embeddableString === "string") return cached;
+  } catch {
+    // Cache miss.
+  }
+  return null;
+}
+
+function writeCachedProfile(cachePath, profile) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify(profile, null, 2));
+  } catch {
+    // The profile is an optimization; prompt scoring can continue without a cache write.
+  }
+}
+
+function projectFingerprint(cwd) {
+  const parts = [];
+  for (const packagePath of workspacePackagePaths(cwd)) {
+    try {
+      const stat = fs.statSync(packagePath);
+      parts.push(`${path.relative(cwd, packagePath)}:${stat.mtimeMs}:${stat.size}`);
+    } catch {
+      parts.push(`${path.relative(cwd, packagePath)}:missing`);
+    }
+  }
+  parts.push(`git:${gitHead(cwd)}`);
+  return parts.join("|");
+}
+
+function packageSignal(cwd, packagePath) {
+  const packageJson = readJson(packagePath);
+  if (!packageJson) return "";
+  const packageDir = path.dirname(packagePath);
+  const dependencies = [
+    ...Object.keys(packageJson.dependencies || {}),
+    ...Object.keys(packageJson.devDependencies || {}),
+    ...Object.keys(packageJson.peerDependencies || {})
+  ].slice(0, MAX_DEPENDENCIES);
+  const scripts = Object.keys(packageJson.scripts || {}).slice(0, MAX_SCRIPTS);
+  const configFiles = ["app.json", "app.config.js", "app.config.ts", "eas.json", "tsconfig.json", "Dockerfile"]
+    .filter((fileName) => fs.existsSync(path.join(packageDir, fileName)));
+  return [
+    path.relative(cwd, packagePath) || "package.json",
+    packageJson.name,
+    packageJson.description,
+    Array.isArray(packageJson.keywords) ? packageJson.keywords.join(" ") : "",
+    dependencies.join(" "),
+    scripts.length ? `scripts ${scripts.join(" ")}` : "",
+    configFiles.join(" ")
+  ].filter(Boolean).join(" ");
+}
+
+function languageSignal({ cwd, packagePaths, recentFiles }) {
+  const values = new Set();
+  for (const packagePath of packagePaths) {
+    const packageDir = path.dirname(packagePath);
+    const packageJson = readJson(packagePath);
+    const deps = normalize(Object.keys({
+      ...(packageJson?.dependencies || {}),
+      ...(packageJson?.devDependencies || {})
+    }).join(" "));
+    if (deps.includes("typescript") || fs.existsSync(path.join(packageDir, "tsconfig.json"))) values.add("TypeScript");
+    if (deps.includes("python")) values.add("Python");
+    if (deps.includes("go")) values.add("Go");
+    if (deps.includes("react")) values.add("React");
+    if (deps.includes("next")) values.add("Next.js");
+    if (deps.includes("expo") || deps.includes("react native")) values.add("React Native");
+  }
+  for (const file of recentFiles) {
+    const ext = path.extname(file);
+    if ([".ts", ".tsx"].includes(ext)) values.add("TypeScript");
+    if ([".js", ".jsx", ".mjs", ".cjs"].includes(ext)) values.add("JavaScript");
+    if (ext === ".py") values.add("Python");
+    if (ext === ".go") values.add("Go");
+    if (ext === ".rs") values.add("Rust");
+    if (ext === ".java") values.add("Java");
+  }
+  if (!values.size && fs.existsSync(path.join(cwd, "package.json"))) values.add("JavaScript");
+  return [...values];
+}
+
+function recentGitFiles(cwd, limit) {
+  try {
+    const output = execFileSync("git", ["log", "--name-only", "--pretty=format:", "-n", "30"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 300
+    });
+    const seen = new Set();
+    for (const line of output.split(/\r?\n/)) {
+      const file = line.trim();
+      if (!file || seen.has(file)) continue;
+      seen.add(file);
+      if (seen.size >= limit) break;
+    }
+    return [...seen];
+  } catch {
+    return [];
+  }
+}
+
+function gitHead(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 300
+    }).trim();
+  } catch {
+    return "nogit";
+  }
+}
+
+export function workspacePackagePaths(cwd) {
+  const rootPackagePath = path.join(cwd, "package.json");
+  const rootPackage = readJson(rootPackagePath);
+  const paths = new Set(fs.existsSync(rootPackagePath) ? [rootPackagePath] : []);
+  for (const workspace of workspacePatterns(rootPackage?.workspaces)) {
+    for (const packagePath of expandWorkspacePattern({ cwd, pattern: workspace })) {
+      paths.add(packagePath);
+    }
+  }
+  return [...paths];
+}
+
+function workspacePatterns(workspaces) {
+  if (Array.isArray(workspaces)) return workspaces.filter((item) => typeof item === "string");
+  if (Array.isArray(workspaces?.packages)) return workspaces.packages.filter((item) => typeof item === "string");
+  return [];
+}
+
+function expandWorkspacePattern({ cwd, pattern }) {
+  const normalizedPattern = String(pattern || "").replace(/\\/g, "/").replace(/\/+$/g, "");
+  if (!normalizedPattern || normalizedPattern.startsWith("..") || path.isAbsolute(normalizedPattern)) return [];
+  if (!normalizedPattern.includes("*")) {
+    const packagePath = path.join(cwd, normalizedPattern, "package.json");
+    return fs.existsSync(packagePath) ? [packagePath] : [];
+  }
+  const parts = normalizedPattern.split("/");
+  const starIndex = parts.indexOf("*");
+  if (starIndex < 0 || parts.includes("**")) return [];
+  const baseDir = path.join(cwd, ...parts.slice(0, starIndex));
+  const suffix = parts.slice(starIndex + 1);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(baseDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => path.join(baseDir, entry.name, ...suffix, "package.json"))
+    .filter((packagePath) => fs.existsSync(packagePath));
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function normalize(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}

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

@@ -56,7 +56,8 @@ export async function handlePromptPayload(
         maxWorkflows: promptLimits.workflows,
         dataDir: mcpDataDir || dataDir,
         embeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS || 500),
-        fileEmbeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS || 1000)
+        fileEmbeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_FILE_EMBEDDING_TIMEOUT_MS || 1000),
+        skillEmbeddingTimeoutMs: Number(process.env.CONTEXTOS_HOOK_SKILL_EMBEDDING_TIMEOUT_MS || 2000)
       }), directFallbackTimeoutMs, "direct fallback scoring");
       scored.telemetry = {
         ...(scored.telemetry || {}),

package/plugins/ctx/lib/scheduler.js

@@ -97,7 +97,8 @@ function formatFile(file, basenameCounts) {
 }
 
 function formatSkill(skill) {
-  return skill.name;
+  const name = String(skill.name || "").trim();
+  return name.startsWith("$") ? name : `$${name}`;
 }
 
 function formatWorkflow(workflow) {

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

@@ -17,7 +17,9 @@ export async function scoreContext({
   skills = null,
   workflows = null,
   embeddingTimeoutMs = 5000,
-  fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 1000)
+  fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 1000),
+  skillEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || embeddingTimeoutMs),
+  skillSearchOptions = {}
 } = {}) {
   const started = Date.now();
   const ruleInputsPromise = Promise.resolve().then(() => {
@@ -59,7 +61,15 @@ export async function scoreContext({
     const catalog = Array.isArray(skills) ? skills : scanSkills({ cwd });
     return {
       catalog,
-      suggestions: await suggestSkills({ cwd, prompt, skills: catalog, dataDir, limit: maxSkills })
+      suggestions: await suggestSkills({
+        cwd,
+        prompt,
+        skills: catalog,
+        dataDir,
+        limit: maxSkills,
+        timeoutMs: skillEmbeddingTimeoutMs,
+        ...skillSearchOptions
+      })
     };
   });
 

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

@@ -2,40 +2,33 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { enhanceRuleScoresWithEmbeddings, warmRuleEmbeddings } from "./embedding-scorer.js";
+import {
+  enhanceRuleScoresWithEmbeddings,
+  searchIndexedEmbeddings,
+  warmIndexedEmbeddings
+} from "./embedding-scorer.js";
+import { fusedProjectQuery, workspacePackagePaths } from "./project-profiler.js";
 
 const DEFAULT_LIMIT = 3;
 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 GENERIC_SKILL_TOKENS = new Set([
-  "active", "agent", "agents", "code", "config", "configuration", "create", "development",
-  "environment", "file", "files", "graph", "install", "integration", "local", "node", "package",
-  "project", "refresh", "rebuild", "setup", "skill", "skills", "sync", "tool", "tools", "using",
-  "build", "can", "not", "production", "show", "something", "https", "http", "com", "www",
-  "a", "an", "and", "are", "as", "at", "be", "before", "after", "both", "by", "from", "for",
-  "if", "in", "into", "is", "must", "of", "on", "or", "the", "then", "this", "to", "user",
-  "users", "when", "where", "whether", "with"
-]);
-const SPECIALIZED_SKILL_TOKENS = new Set([
-  "android", "architecture", "authorization", "cicd", "documentation", "docs", "document",
-  "eas", "expo", "frontend", "ios", "next", "nextjs", "mcp", "modelcontextprotocol",
-  "postgres", "postgresql", "react", "react-native", "readme", "tailwind", "typescript",
-  "ui", "wiki", "writer"
-]);
+const SKILL_EMBEDDING_THRESHOLD = 0.45;
+const DEFAULT_SKILL_TIMEOUT_MS = 2000;
 
 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"),
@@ -124,8 +117,9 @@ function monotonicNow() {
 }
 
 function cacheAndReturnSkills(cacheKey, skills) {
-  scanCache.set(cacheKey, { createdAt: monotonicNow(), skills });
-  return skills;
+  const deduped = dedupeSkills(skills);
+  scanCache.set(cacheKey, { createdAt: monotonicNow(), skills: deduped });
+  return deduped;
 }
 
 function findSkillFiles(root) {
@@ -171,47 +165,90 @@ export async function suggestSkills({
   dataDir,
   cwd = process.cwd(),
   limit = DEFAULT_LIMIT,
-  timeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800)
+  timeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || DEFAULT_SKILL_TIMEOUT_MS),
+  indexedSearcher = searchIndexedEmbeddings,
+  embeddingEnhancer = enhanceRuleScoresWithEmbeddings
 } = {}) {
   if (!String(prompt || "").trim() || !skills.length) return [];
-  const base = scoreSkillsByKeyword({ prompt, skills, projectHints: projectSkillHints({ cwd }) });
-  if (skills.length > DEFAULT_SEMANTIC_CATALOG_LIMIT) {
-    return finalizeSkillScores(base, limit, { minimumKeywordScore: 0.5 });
+  const catalog = dedupeSkills(skills);
+  const query = fusedProjectQuery({ prompt, cwd, dataDir });
+  const byId = new Map(catalog.map((skill) => [skillIndexId(skill), skill]));
+  const explicitSkills = explicitSkillSuggestions({ prompt, byId });
+
+  if (dataDir) {
+    const indexed = await indexedSearcher({
+      kind: skillIndexKind(cwd),
+      task: query,
+      dataDir,
+      timeoutMs,
+      allowRemote: false
+    });
+    if (indexed.status === "enabled" && indexed.items.length) {
+      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);
+    }
   }
 
-  const embeddingCandidates = selectEmbeddingCandidates(base);
-  if (!embeddingCandidates.length) return [];
+  if (catalog.length > DEFAULT_EMBEDDING_CANDIDATES) return finalizeSkillScores(explicitSkills, limit);
+
+  const embeddingCandidates = catalog.map((skill, index) => skillRule({ skill, index }));
+  if (!embeddingCandidates.length) return finalizeSkillScores(explicitSkills, limit);
 
-  const embedding = await enhanceRuleScoresWithEmbeddings(embeddingCandidates, prompt, {
+  const embedding = await embeddingEnhancer(embeddingCandidates, query, {
     dataDir,
     sources: embeddingCandidates.map((skill) => skill.path).filter(Boolean),
     timeoutMs,
     allowRemote: false
   });
 
-  return finalizeSkillScores(embedding.rules, limit);
+  return finalizeSkillScores([...explicitSkills, ...embedding.rules], limit);
+}
+
+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 finalizeSkillScores(skills, limit, { minimumKeywordScore = 0.35 } = {}) {
+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) {
   const ranked = skills
-    .filter((rule) => rule.domainEligible !== false)
     .map((rule) => ({
       name: rule.name,
       description: rule.description,
       path: rule.path,
       scope: rule.scope,
-      keywordScore: rule.keywordScore,
       score: Math.min(1, Number(rule.score || 0)),
       embeddingScore: rule.embeddingScore,
-      relevancePriority: Number(rule.relevancePriority || 0),
-      rankScore: Math.min(1, Number(rule.score || 0)) + Number(rule.relevancePriority || 0) / 100,
+      rankScore: Math.min(1, Number(rule.score || 0)),
       reasons: rule.reasons || []
     }))
-    .filter((skill) => Number(skill.keywordScore || 0) >= minimumKeywordScore
-      || Number(skill.embeddingScore || 0) >= 0.62
-      || Number(skill.relevancePriority || 0) >= 50)
+    .filter((skill) => Number(skill.embeddingScore || skill.score || 0) >= SKILL_EMBEDDING_THRESHOLD)
     .sort((a, b) => b.rankScore - a.rankScore
-      || b.relevancePriority - a.relevancePriority
       || b.score - a.score
       || scopePriority(b.scope) - scopePriority(a.scope)
       || a.name.localeCompare(b.name));
@@ -230,14 +267,6 @@ function scopePriority(scope) {
   return scope === "project" ? 1 : 0;
 }
 
-function selectEmbeddingCandidates(skills) {
-  if (skills.length <= DEFAULT_EMBEDDING_CANDIDATES) return skills;
-  return [...skills]
-    .filter((skill) => Number(skill.keywordScore || 0) > 0)
-    .sort((a, b) => Number(b.keywordScore || 0) - Number(a.keywordScore || 0) || a.name.localeCompare(b.name))
-    .slice(0, DEFAULT_EMBEDDING_CANDIDATES);
-}
-
 export async function warmSkillEmbeddings({
   cwd = process.cwd(),
   dataDir,
@@ -245,304 +274,81 @@ export async function warmSkillEmbeddings({
   skills = scanSkills({ cwd })
 } = {}) {
   if (!dataDir || !skills.length) return { count: 0, cachePath: null };
-  return warmRuleEmbeddings({
-    rules: skills.map((skill) => ({ content: `${skill.name} ${skill.description}` })),
-    task: "skill discovery semantic retrieval",
+  const catalog = dedupeSkills(skills);
+  return warmIndexedEmbeddings({
+    kind: skillIndexKind(cwd),
+    items: catalog.map((skill) => ({
+      id: skillIndexId(skill),
+      text: skillEmbeddingText(skill)
+    })),
+    task: fusedProjectQuery({ prompt: "skill discovery semantic retrieval", cwd, dataDir }),
     dataDir,
-    sources: skills.map((skill) => skill.path).filter(Boolean),
+    sources: catalog.map((skill) => skill.path).filter(Boolean),
     allowRemote
   });
 }
 
-function scoreSkillsByKeyword({ prompt, skills, projectHints = [] }) {
-  const normalizedPrompt = normalizePrompt(prompt);
-  const promptTokens = new Set(normalizedPrompt.split(/\s+/).filter(Boolean));
-  const projectTokens = new Set(projectHints);
-  return skills.map((skill, index) => {
-    const enriched = skill.searchTokens ? skill : enrichSkill(skill);
-    const name = String(enriched.name || "");
-    const description = truncateDescription(enriched.description || "");
-    const content = `${name} ${description}`;
-    const matches = filterSkillMatches(
-      enriched.searchTokens.filter((token) => promptTokens.has(token) && token.length > 2 && !GENERIC_SKILL_TOKENS.has(token)),
-      { normalizedPrompt, enriched }
-    );
-    const projectMatches = enriched.searchTokens.filter((token) => projectTokens.has(token) && SPECIALIZED_SKILL_TOKENS.has(token));
-    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 = enriched.scope === "project" ? 0.08 : 0;
-    const intentBonus = skillIntentBonus(normalizedPrompt, enriched, projectTokens);
-    const relevancePriority = skillRelevancePriority(normalizedPrompt, enriched, projectTokens);
-    const domainEligible = isSkillDomainEligible(normalizedPrompt, enriched, projectTokens);
-    const matchScore = matches.reduce((sum, token) => sum + (SPECIALIZED_SKILL_TOKENS.has(token) ? 0.2 : 0.08), 0);
-    const projectBonus = intentBonus ? Math.min(0.16, projectMatches.length * 0.04) : 0;
-    const score = Math.min(1, (matches.length ? 0.25 + matchScore : 0) + projectBonus + intentBonus + (nameHit ? 0.2 : 0) + (nameTokenHit ? 0.18 : 0) + scopeBonus);
-    return {
-      id: `skill-${index + 1}`,
-      name,
-      description,
-      path: enriched.path,
-      scope: enriched.scope,
-      content,
-      score,
-      keywordScore: score,
-      relevancePriority,
-      domainEligible,
-      reasons: [
-        ...(matches.length ? [`keyword:${matches.slice(0, 4).join(",")}`] : []),
-        ...(projectBonus ? [`project:${projectMatches.slice(0, 4).join(",")}`] : []),
-        ...(intentBonus ? ["intent-match"] : []),
-        ...(nameHit || nameTokenHit ? ["name-match"] : [])
-      ],
-      originalOrder: index
-    };
-  });
-}
-
-function filterSkillMatches(matches, { normalizedPrompt, enriched }) {
-  if (!/\beas\b/.test(normalizedPrompt)) return matches;
-  const skillText = normalize(`${enriched.name} ${enriched.description}`);
-  if (/\b(eas|expo|cicd)\b/.test(skillText)) return matches;
-  return matches.filter((token) => token !== "android" && token !== "ios");
+function skillRule({ skill, index }) {
+  const enriched = skill.searchTokens ? skill : enrichSkill(skill);
+  return {
+    id: skillIndexId(enriched),
+    name: enriched.name,
+    description: enriched.description,
+    path: enriched.path,
+    scope: enriched.scope,
+    content: skillEmbeddingText(enriched),
+    score: 0,
+    originalOrder: index
+  };
 }
 
-function isSkillDomainEligible(normalizedPrompt, enriched, projectTokens = new Set()) {
-  const skillText = normalize(`${enriched.name} ${enriched.description}`);
-  if (isMcpSkill(skillText) && !isMcpRelevantTask(normalizedPrompt, projectTokens)) return false;
-  if (isOffensiveSecuritySkill(skillText) && !isSecurityTask(normalizedPrompt)) return false;
-  if (isPlatformCommerceSkill(skillText) && !isPlatformCommerceTask(normalizedPrompt, skillText)) return false;
-  if (isDocumentProcessingSkill(skillText) && !isDocumentProcessingTask(normalizedPrompt, skillText)) return false;
-  if (isWorkspaceAutomationSkill(skillText) && !isWorkspaceAutomationTask(normalizedPrompt, skillText)) return false;
-  if (!/\beas\b/.test(normalizedPrompt)) return true;
-  if (!/\b(android|ios)\b/.test(skillText)) return true;
-  return /\b(eas|expo|cicd)\b/.test(skillText);
+function skillScoreFromEmbedding(skill, embeddingScore, reasons = []) {
+  const score = Math.min(1, Number(embeddingScore || 0));
+  return {
+    name: skill.name,
+    description: skill.description,
+    path: skill.path,
+    scope: skill.scope,
+    score,
+    embeddingScore: score,
+    reasons
+  };
 }
 
-function skillIntentBonus(normalizedPrompt, enriched, projectTokens = new Set()) {
-  const skillText = normalize(`${enriched.name} ${enriched.description}`);
-  if (isDocumentAuthoringTask(normalizedPrompt)
-    && /\b(documentation|document|docs|doc|readme|wiki|writer|writing|coauthor|technical documentation|architecture documentation|onboarding|office productivity)\b/.test(skillText)) {
-    return 0.48;
-  }
-  if (isMcpRelevantTask(normalizedPrompt, projectTokens)
-    && /\b(mcp|model context protocol|modelcontextprotocol|agent memory|tool developer|tool builder)\b/.test(skillText)) {
-    return 0.48;
-  }
-  if (isCommerceTask(normalizedPrompt)
-    && /\b(payment|payments|checkout|billing|bill|invoice|wallet|balance|stripe|paypal|commerce|monetization)\b/.test(skillText)) {
-    return 0.46;
-  }
-  if (isContentAccessTask(normalizedPrompt)
-    && /\b(api|endpoint|backend|service|services|auth|authorization|permission|permissions|access|rbac|frontend api)\b/.test(skillText)) {
-    return 0.34;
-  }
-  if (isNotificationTask(normalizedPrompt)
-    && /\b(notification|notifications|notify|message|sms|email|event|webhook)\b/.test(skillText)) {
-    return 0.3;
-  }
-  if (isFrontendCheckoutTask(normalizedPrompt)
-    && /\b(frontend|react|next|nextjs|ui|component|modal|api integration)\b/.test(skillText)) {
-    return 0.32;
-  }
-  if (isExpoRuntimeTask(normalizedPrompt, projectTokens)
-    && /\b(expo|eas|nativewind|react native|tailwind)\b/.test(skillText)) {
-    return 0.46;
-  }
-  if (isNextAppRouterTask(normalizedPrompt)
-    && /\b(next|nextjs)\b/.test(skillText)
-    && /\b(app router|router|routing|server components)\b/.test(skillText)) {
-    return 0.5;
-  }
-  if (/\beas\b/.test(normalizedPrompt)
-    && /\b(eas|expo)\b/.test(skillText)
-    && /\b(cicd|workflow|workflows|build|deploy|deployment|pipeline|pipelines)\b/.test(skillText)) {
-    return 0.28;
-  }
-  if (/\b(webapp|frontend|ui|dashboard|button|page|component|app|router)\b/.test(normalizedPrompt)
-    && /\b(frontend|react|next|nextjs|ui|component|tailwind|app router)\b/.test(skillText)) {
-    return 0.36;
-  }
-  if (/\b(role|admin|creator|permission|permissions|authorization|access)\b/.test(normalizedPrompt)
-    && /\b(auth|authentication|authorization|permission|permissions|access|rbac)\b/.test(skillText)) {
-    return 0.32;
+function dedupeSkills(skills) {
+  const byName = new Map();
+  for (const skill of skills || []) {
+    const enriched = skill.searchTokens ? skill : enrichSkill(skill);
+    const key = normalize(enriched.name);
+    if (!key) continue;
+    const existing = byName.get(key);
+    if (!existing || skillSourcePriority(enriched) > skillSourcePriority(existing)) {
+      byName.set(key, enriched);
+    }
   }
-  return 0;
+  return [...byName.values()];
 }
 
-function skillRelevancePriority(normalizedPrompt, enriched, projectTokens = new Set()) {
-  const skillText = normalize(`${enriched.name} ${enriched.description}`);
-  const skillName = normalize(enriched.name);
+function skillSourcePriority(skill) {
   let priority = 0;
-  if (isDocumentAuthoringTask(normalizedPrompt)) {
-    if (skillName === "doc coauthoring") priority += 1300;
-    if (skillName === "documentation") priority += 720;
-    if (skillName === "docs architect") priority += 700;
-    if (skillName === "readme") priority += 660;
-    if (skillName === "wiki page writer") priority += 640;
-    if (skillName === "wiki architect") priority += 620;
-    if (skillName === "wiki onboarding") priority += 600;
-    if (skillName === "writer" || skillName === "docx" || skillName === "office productivity") priority += 560;
-    if (skillName === "agents md") priority += 420;
-    if (/\b(code documentation doc generate|documentation generation doc generate|api documentation|api documenter|reference builder|architecture)\b/.test(skillText)) priority += 320;
-    if (/\b(documentation|document|docs|doc|readme|wiki|writer|writing|coauthor|technical documentation)\b/.test(skillText)) priority += 130;
-    if (/\b(mcp|model context protocol|metasploit|penetration|exploit)\b/.test(skillText)) priority -= 220;
-  }
-  if (isMcpRelevantTask(normalizedPrompt, projectTokens)) {
-    if (skillName === "mcp builder") priority += 760;
-    if (skillName === "mcp management") priority += 740;
-    if (skillName === "mcp tool developer") priority += 720;
-    if (skillName === "agent memory mcp") priority += 700;
-    if (skillName === "agent tool builder" || skillName === "context agent") priority += 260;
-    if (/\b(mcp|model context protocol|modelcontextprotocol)\b/.test(skillText)) priority += 160;
-  }
-  if (isCommerceTask(normalizedPrompt)) {
-    if (/\b(payment integration|stripe integration|paypal integration)\b/.test(skillText)) priority += 520;
-    if (/\bbilling automation\b/.test(skillText)) priority += 430;
-    if (/\b(payment|payments|checkout|billing|wallet|balance|stripe|paypal|commerce|monetization)\b/.test(skillText)) priority += 160;
-    if (!/\bstripe\b/.test(normalizedPrompt) && /\bstripe\b/.test(skillText)) priority -= 520;
-    if (!/\bpaypal\b/.test(normalizedPrompt) && /\bpaypal\b/.test(skillText)) priority -= 520;
-    if (!/\bsquare\b/.test(normalizedPrompt) && /\bsquare\b/.test(skillText)) priority -= 440;
-    if (/\b(mcp|metasploit|penetration|exploit|bug bounty)\b/.test(skillText)) priority -= 500;
-  }
-  if (isContentAccessTask(normalizedPrompt)) {
-    if (/\b(api endpoint builder|backend development|backend architect|frontend api integration patterns)\b/.test(skillText)) priority += 260;
-    if (/\b(auth implementation patterns|authorization|permission|permissions|access|rbac)\b/.test(skillText)) priority += 120;
-  }
-  if (isNotificationTask(normalizedPrompt)) {
-    if (/\bsendblue notify\b/.test(skillText)) priority += 140;
-    if (/\b(notification|notifications|notify|message|sms|email|event|webhook)\b/.test(skillText)) priority += 90;
-  }
-  if (isFrontendCheckoutTask(normalizedPrompt)) {
-    if (/\bfrontend api integration patterns\b/.test(skillText)) priority += 220;
-    if (/\breact nextjs development|nextjs best practices|nextjs app router patterns|frontend developer\b/.test(skillText)) priority += 90;
-  }
-  if (isExpoRuntimeTask(normalizedPrompt, projectTokens)) {
-    if (/\bexpo deployment\b/.test(skillText)) priority += 900;
-    if (/\bbuilding native ui\b/.test(skillText)) priority += 760;
-    if (/\bexpo tailwind setup\b/.test(skillText)) priority += 620;
-    if (/\bexpo\b/.test(skillText) && /\b(qr|expo go|run|running|start|connect|eas|deployment|build)\b/.test(skillText)) priority += 220;
-    if (/\bnativewind|tailwind\b/.test(skillText) && projectTokens.has("nativewind")) priority += 120;
-    if (/\b(next|nextjs|frontend designer|dark themed|glassmorphism|framer motion)\b/.test(skillText)) priority -= 160;
-  }
-  if (isNextAppRouterTask(normalizedPrompt)) {
-    if (/\bnextjs app router patterns\b/.test(skillText)) priority += 600;
-    if (/\bnextjs best practices\b/.test(skillText)) priority += 560;
-    if (/\breact nextjs development\b/.test(skillText)) priority += 420;
-    if (/\b(next|nextjs)\b/.test(skillText) && /\b(app router|router|routing|server components)\b/.test(skillText)) priority += 100;
-    if (/\b(next|nextjs)\b/.test(skillText) && /\breact\b/.test(skillText)) priority += 70;
-    if (/\b(glassmorphism|dark themed|dark theme|framer motion)\b/.test(skillText)) priority -= 40;
-  }
-  if (/\b(role|admin|creator|permission|permissions|authorization|access)\b/.test(normalizedPrompt)
-    && /\b(auth|authentication|authorization|permission|permissions|access|rbac)\b/.test(skillText)) {
-    priority += 55;
-  }
+  if (skill.scope === "project") priority += 100;
+  const skillPath = String(skill.path || "");
+  if (skillPath.includes(`${path.sep}.codex${path.sep}skills${path.sep}`)) priority += 30;
+  if (skillPath.includes(`${path.sep}.config${path.sep}skillshare${path.sep}skills${path.sep}`)) priority += 20;
+  if (skillPath.includes(`${path.sep}.agents${path.sep}skills${path.sep}`)) priority += 10;
   return priority;
 }
 
-function isNextAppRouterTask(normalizedPrompt) {
-  return /\bwebapp\b.*\bsrc\b.*\bapp\b/.test(normalizedPrompt)
-    || /\b(next|nextjs)\b.*\b(app router|router|routing)\b/.test(normalizedPrompt)
-    || /\bapp router\b/.test(normalizedPrompt);
-}
-
-function isExpoRuntimeTask(normalizedPrompt, projectTokens = new Set()) {
-  const expoProject = projectTokens.has("expo") || projectTokens.has("nativewind") || projectTokens.has("eas");
-  if (!expoProject) return false;
-  return /\b(qr|connect|run|start|expo go|device|metro|tunnel|lan)\b/.test(normalizedPrompt);
-}
-
-function isCommerceTask(normalizedPrompt) {
-  return /\b(purchase|purchased|buy|buyer|seller|payment|pay|checkout|wallet|balance|top up|topup|funded|billing|invoice)\b/.test(normalizedPrompt);
-}
-
-function isContentAccessTask(normalizedPrompt) {
-  return /\b(content access service|content access|access permissions|grant access|permissions|library|resources|tutorials|collections)\b/.test(normalizedPrompt);
-}
-
-function isNotificationTask(normalizedPrompt) {
-  return /\b(notification|notifications|notify|buyer|seller)\b/.test(normalizedPrompt);
-}
-
-function isFrontendCheckoutTask(normalizedPrompt) {
-  return /\b(modal|display|show|checkout|library|frontend|webapp|page|button)\b/.test(normalizedPrompt);
-}
-
-function isDocumentAuthoringTask(normalizedPrompt) {
-  return /\b(create|write|edit|update|draft|generate|author|maintain|work on|produce)\b.*\b(document|documents|documentation|docs|doc|readme|wiki|workspace|workspaces|manual|guide|onboarding|spec|adr)\b/.test(normalizedPrompt)
-    || /\b(document|documents|documentation|docs|doc|readme|wiki|workspace|workspaces|manual|guide|onboarding|spec|adr)\b.*\b(create|write|edit|update|draft|generate|author|maintain|work on|produce)\b/.test(normalizedPrompt);
-}
-
-function isMcpTask(normalizedPrompt) {
-  return /\b(mcp|model context protocol|tool server|tools server|server tool|bridge|proxy)\b/.test(normalizedPrompt);
-}
-
-function isMcpRelevantTask(normalizedPrompt, projectTokens = new Set()) {
-  return isMcpTask(normalizedPrompt)
-    || (isMcpProject(projectTokens) && isContextRetrievalTask(normalizedPrompt));
-}
-
-function isMcpProject(projectTokens = new Set()) {
-  return projectTokens.has("mcp") || projectTokens.has("modelcontextprotocol");
-}
-
-function isContextRetrievalTask(normalizedPrompt) {
-  return /\b(suggest|suggested|suggestion|skills|files|context|retrieval|retrieve|scorer|scoring|match|matching|prompt|hook|inject|injection)\b/.test(normalizedPrompt);
-}
-
-function isSecurityTask(normalizedPrompt) {
-  return /\b(security|pentest|penetration|exploit|vulnerability|metasploit|bug bounty|owasp|xss|csrf|attack|audit)\b/.test(normalizedPrompt);
-}
-
-function isMcpSkill(skillText) {
-  return /\bmcp\b|\bmodel context protocol\b/.test(skillText);
-}
-
-function isOffensiveSecuritySkill(skillText) {
-  return /\b(metasploit|penetration testing|bug bounty|exploit|exploitation|privilege escalation|ethical hacking|web fuzzing|security assessment)\b/.test(skillText);
-}
-
-function isPlatformCommerceSkill(skillText) {
-  return /\b(wordpress|woocommerce|shopify|odoo)\b/.test(skillText);
-}
-
-function isPlatformCommerceTask(normalizedPrompt, skillText) {
-  if (/\bwordpress\b/.test(skillText)) return /\bwordpress\b/.test(normalizedPrompt);
-  if (/\bwoocommerce\b/.test(skillText)) return /\bwoocommerce\b/.test(normalizedPrompt);
-  if (/\bshopify\b/.test(skillText)) return /\bshopify\b/.test(normalizedPrompt);
-  if (/\bodoo\b/.test(skillText)) return /\bodoo\b/.test(normalizedPrompt);
-  return true;
+function skillIndexKind(cwd) {
+  return `skill:${path.resolve(cwd)}`;
 }
 
-function isDocumentProcessingSkill(skillText) {
-  return /\b(azure ai document|document intelligence|formrecognizer|document translation|cosmos db|azure cosmos|search documents|docusign)\b/.test(skillText);
+function skillIndexId(skill) {
+  return normalize(skill.name);
 }
 
-function isDocumentProcessingTask(normalizedPrompt, skillText) {
-  if (/\bdocusign\b/.test(skillText)) return /\bdocusign|signature|envelope|sign\b/.test(normalizedPrompt);
-  if (/\bcosmos db|azure cosmos\b/.test(skillText)) return /\bcosmos|database|nosql|query|container\b/.test(normalizedPrompt);
-  if (/\bsearch documents\b/.test(skillText)) return /\bazure search|vector search|semantic search|index\b/.test(normalizedPrompt);
-  return /\bextract|ocr|analyze|translate|translation|form recognizer|document intelligence|azure\b/.test(normalizedPrompt);
-}
-
-function isWorkspaceAutomationSkill(skillText) {
-  return /\b(asana|bitbucket|slack|coda|google docs|google drive|google sheets|google slides|notion|telegram)\b/.test(skillText)
-    && /\b(automation|automate|workspace|workspaces|manage docs|documents)\b/.test(skillText);
-}
-
-function isWorkspaceAutomationTask(normalizedPrompt, skillText) {
-  if (/\basana\b/.test(skillText)) return /\basana\b/.test(normalizedPrompt);
-  if (/\bbitbucket\b/.test(skillText)) return /\bbitbucket\b/.test(normalizedPrompt);
-  if (/\bslack\b/.test(skillText)) return /\bslack\b/.test(normalizedPrompt);
-  if (/\bcoda\b/.test(skillText)) return /\bcoda\b/.test(normalizedPrompt);
-  if (/\bgoogle docs\b/.test(skillText)) return /\bgoogle docs\b/.test(normalizedPrompt);
-  if (/\bgoogle drive\b/.test(skillText)) return /\bgoogle drive\b/.test(normalizedPrompt);
-  if (/\bgoogle sheets\b/.test(skillText)) return /\bgoogle sheets\b/.test(normalizedPrompt);
-  if (/\bgoogle slides\b/.test(skillText)) return /\bgoogle slides\b/.test(normalizedPrompt);
-  if (/\bnotion\b/.test(skillText)) return /\bnotion\b/.test(normalizedPrompt);
-  if (/\btelegram\b/.test(skillText)) return /\btelegram\b/.test(normalizedPrompt);
-  return true;
+function skillEmbeddingText(skill) {
+  return [skill.name, skill.description].filter(Boolean).join("\n");
 }
 
 export function projectSkillHints({ cwd = process.cwd() } = {}) {
@@ -567,48 +373,6 @@ export function projectSkillHints({ cwd = process.cwd() } = {}) {
   return [...hints];
 }
 
-function workspacePackagePaths(cwd) {
-  const rootPackagePath = path.join(cwd, "package.json");
-  const rootPackage = readJson(rootPackagePath);
-  const paths = new Set([rootPackagePath]);
-  for (const workspace of workspacePatterns(rootPackage?.workspaces)) {
-    for (const packagePath of expandWorkspacePattern({ cwd, pattern: workspace })) {
-      paths.add(packagePath);
-    }
-  }
-  return [...paths];
-}
-
-function workspacePatterns(workspaces) {
-  if (Array.isArray(workspaces)) return workspaces.filter((item) => typeof item === "string");
-  if (Array.isArray(workspaces?.packages)) return workspaces.packages.filter((item) => typeof item === "string");
-  return [];
-}
-
-function expandWorkspacePattern({ cwd, pattern }) {
-  const normalized = String(pattern || "").replace(/\\/g, "/").replace(/\/+$/g, "");
-  if (!normalized || normalized.startsWith("..") || path.isAbsolute(normalized)) return [];
-  if (!normalized.includes("*")) {
-    const packagePath = path.join(cwd, normalized, "package.json");
-    return fs.existsSync(packagePath) ? [packagePath] : [];
-  }
-  const parts = normalized.split("/");
-  const starIndex = parts.indexOf("*");
-  if (starIndex < 0 || parts.includes("**")) return [];
-  const baseDir = path.join(cwd, ...parts.slice(0, starIndex));
-  const suffix = parts.slice(starIndex + 1);
-  let entries = [];
-  try {
-    entries = fs.readdirSync(baseDir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
-    .map((entry) => path.join(baseDir, entry.name, ...suffix, "package.json"))
-    .filter((packagePath) => fs.existsSync(packagePath));
-}
-
 function readJson(filePath) {
   try {
     return JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -639,10 +403,3 @@ function enrichSkill(skill) {
 function normalize(value) {
   return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
 }
-
-function normalizePrompt(value) {
-  return normalize(String(value || "")
-    .replace(/https?:\/\/\S+/gi, " ")
-    .replace(/giao\s+di[eệ]n/gi, "frontend ui")
-    .replace(/phan\s+quyen/gi, "authorization role"));
-}