@minhpnq1807/contextos 0.3.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.1
+
+- Fixes `ctx sync --skills` first-run ordering by running `skillshare init` before `skillshare backup`, matching skillshare's config requirement.
+
+## 0.5.0
+
+- Adds `ctx sync --skills` for skillshare-backed skill sync across Codex, Claude Code, and Antigravity.
+- Detects existing global/project skill directories, backs them up, optionally collects them into skillshare, runs sync, and rebuilds skill embeddings.
+- Adds `~/.config/skillshare/skills` to skill discovery roots so ContextOS ranks the shared source of truth after sync.
+
+## 0.4.1
+
+- Adds Antigravity skill discovery roots for `.gemini/skills`, `.gemini/antigravity/skills`, and `.gemini/antigravity-cli/skills`.
+- Raises the skill catalog scan cap to cover large Antigravity skill catalogs before ranking.
+
+## 0.4.0
+
+- Adds prompt-aware skill discovery to `ctx_score_context`, returning `suggestedSkills` alongside rules and files.
+- Scans project/global `.codex/skills`, `.claude/skills`, and Antigravity `.gemini/**/skills` catalogs, ranks skill `name` + `description`, and injects top skill hints into prompt context.
+- Warms skill embeddings during `ctx install` and `ctx embeddings warm`.
+
 ## 0.3.0
 
 - Adds `ctx sync --rules` for Ruler-backed project rule/MCP sync across Codex, Claude Code, and Antigravity.

package/README.md

@@ -77,6 +77,7 @@ With ContextOS, each prompt gets a compact block:
 - Registers a `ctx-mcp` MCP server that owns model loading and semantic scoring.
 - Reads the active `AGENTS.md` chain for the current workspace.
 - Scores rules by relevance to the user prompt.
+- Scans project/global `.codex/skills`, `.claude/skills`, and Antigravity `.gemini/**/skills`, ranks skill descriptions by task relevance, and injects top skill hints.
 - Filters host/session setup rules such as "run commands as user X" or `sudo -u user` because they are environment instructions, not project guidance.
 - Finds likely relevant files with a hybrid retriever:
   - first, local prompt/file heuristics create seed candidates;
@@ -168,6 +169,32 @@ npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx --version
 npm exec --yes --package=@minhpnq1807/contextos@latest -- ctx debug -- "Recheck authen flow"
 ```
 
+## Skill Sync
+
+Use skillshare when you want Codex, Claude Code, and Antigravity to share one skills catalog:
+
+```bash
+ctx sync --skills
+```
+
+ContextOS checks for `skillshare`, initializes it when needed, backs up existing skills before collection, runs `skillshare collect --all` unless `--no-collect` is provided, then runs `skillshare sync`. After sync, ContextOS rebuilds skill embeddings so prompt-time skill discovery can rank the shared source immediately.
+
+The shared source is:
+
+```text
+~/.config/skillshare/skills/
+```
+
+Useful variants:
+
+```bash
+ctx sync --skills --dry-run
+ctx sync --skills --no-collect
+ctx sync --skills --agents codex,claude
+```
+
+After this, `ctx debug -- "task"` and prompt hooks can suggest skills from `~/.config/skillshare/skills/` plus agent-specific skill folders.
+
 ## Modes
 
 Injection mode is the default:
@@ -287,7 +314,11 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx sync --rules --dry-run` | Previews Ruler sync without writing files or running apply. | You want to inspect behavior before changing project config. | Prints the same flow with dry-run status. |
 | `ctx sync --rules --force` | Rewrites ContextOS-owned Ruler sections. | You changed the ContextOS install path or need to refresh `ctx-mcp`. | Removes and re-adds ContextOS-owned `mcp`, `mcp_servers.ctx-mcp`, and selected agent sections. |
 | `ctx sync --rules --no-import-codex-mcp` | Skips Codex MCP import. | You only want ContextOS' own `ctx-mcp` in Ruler. | Does not read `~/.codex/config.toml`. |
-| `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx sync --skills` | Syncs agent skills through skillshare. | You want Codex, Claude Code, and Antigravity to share one skill source. | Installs or verifies `skillshare`, initializes it if needed, backs up and collects existing skills unless skipped, runs `skillshare sync`, and rebuilds ContextOS skill embeddings. |
+| `ctx sync --skills --agents <list>` | Syncs skills only for selected agents. | You want to target a subset such as `codex,claude`. | Runs `skillshare sync --agents <list>` and 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 embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, and skill vectors to `~/.ctx/contextos/embeddings.db`. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
 ## Runtime Files

package/bin/ctx.js

@@ -22,6 +22,8 @@ import { installClaudeMcp } from "../plugins/ctx/lib/claude-mcp.js";
 import { installAntigravityHooks } from "../plugins/ctx/lib/antigravity-hooks.js";
 import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
+import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
+import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -48,6 +50,10 @@ Usage:
   ctx sync --rules --agents codex,claude,antigravity
   ctx sync --rules --dry-run
   ctx sync --rules --no-import-codex-mcp
+  ctx sync --skills
+  ctx sync --skills --dry-run
+  ctx sync --skills --no-collect
+  ctx sync --skills --agents codex,claude,antigravity
   ctx embeddings warm -- "task"
   ctx --version
 `;
@@ -96,6 +102,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
     console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
     console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
     console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
+    console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
     console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
     console.log("Restart Claude Code if it was already running, then submit a task to trigger ContextOS.");
     return;
@@ -113,6 +120,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
     console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
     console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
     console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
+    console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
     console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
     console.log("Restart Antigravity or agy if it was already running, then submit a task to trigger ContextOS.");
     return;
@@ -143,6 +151,7 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
   console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
   console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
   console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
+  console.log(`Skill embeddings warmed: ${warmResult.skillCount || 0}`);
   console.log(`Prompt context injection: ${inject ? "enabled" : "quiet logging only"}`);
   console.log("Restart Codex if it was already running, then submit a task to trigger ContextOS.");
 }
@@ -169,7 +178,12 @@ async function warmInstallEmbeddings() {
     dataDir,
     allowRemote: !modelReady
   });
-  return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count };
+  const skillResult = await warmSkillEmbeddings({
+    cwd: process.cwd(),
+    dataDir,
+    allowRemote: !modelReady
+  });
+  return { ...result, modelAlreadyCached: modelReady, fileCount: fileResult.count, skillCount: skillResult.count };
 }
 
 function tryRunCodex(args) {
@@ -226,7 +240,8 @@ async function debug(task) {
   });
   const rules = scored.scoredRules;
   const relevantFiles = scored.suggestedFiles.slice(0, 3);
-  const scheduled = scheduleContext({ rules, relevantFiles });
+  const suggestedSkills = (scored.suggestedSkills || []).slice(0, 3);
+  const scheduled = scheduleContext({ rules, relevantFiles, suggestedSkills });
 
   console.log("ContextOS debug");
   console.log(`cwd: ${cwd}`);
@@ -250,6 +265,14 @@ async function debug(task) {
   }
   if (!relevantFiles.length) console.log("(none)");
   console.log("");
+  console.log("Suggested skills:");
+  for (const skill of suggestedSkills) {
+    const score = Number(skill.score || 0).toFixed(2);
+    const location = skill.path ? ` path:${skill.path}` : "";
+    console.log(`${score}  ${skill.name}${location}`);
+  }
+  if (!suggestedSkills.length) console.log("(none)");
+  console.log("");
   console.log("Final additionalContext:");
   console.log(scheduled.additionalContext || "(empty)");
 }
@@ -270,8 +293,14 @@ async function warmEmbeddings(task) {
     dataDir: contextOSDataDir(),
     allowRemote: true
   });
+  const skillResult = await warmSkillEmbeddings({
+    cwd,
+    dataDir: contextOSDataDir(),
+    allowRemote: true
+  });
   console.log(`Warmed ${result.count} embeddings`);
   console.log(`Warmed ${fileResult.count} file path embeddings`);
+  console.log(`Warmed ${skillResult.count} skill embeddings`);
   console.log(`Cache: ${result.cachePath}`);
 }
 
@@ -321,7 +350,20 @@ try {
     if (!task.trim()) throw new Error('Usage: ctx benchmark -- "task"');
     console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
   } else if (command === "sync") {
-    await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
+    if (args.includes("--skills")) {
+      await syncSkills({
+        cwd: process.cwd(),
+        args: args.slice(1),
+        rebuildSkillEmbeddings: async ({ cwd, sourceDir }) => warmSkillEmbeddings({
+          cwd,
+          dataDir: contextOSDataDir(),
+          allowRemote: !isModelCacheReady(contextOSDataDir()),
+          skills: scanSkills({ cwd, roots: [sourceDir] })
+        })
+      });
+    } else {
+      await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
+    }
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "vitest run",
+    "test": "vitest run test",
     "build": "node bin/ctx.js --version",
     "validate:plugin": "node test/validate-plugin.js",
     "test:mcp": "node test/mcp-protocol-smoke.js"

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

@@ -34,7 +34,8 @@ export async function handlePromptPayload(
   if (scored.error) throw new Error(scored.error);
   const scoredRules = scored.scoredRules || [];
   const relevantFiles = (scored.suggestedFiles || []).slice(0, 3);
-  const scheduled = scheduleContext({ rules: scoredRules, relevantFiles });
+  const suggestedSkills = (scored.suggestedSkills || []).slice(0, 3);
+  const scheduled = scheduleContext({ rules: scoredRules, relevantFiles, suggestedSkills });
 
   const runtime = {
     at: now.toISOString(),
@@ -46,10 +47,12 @@ export async function handlePromptPayload(
       mcp: scored.telemetry || {}
     },
     relevantFiles,
+    suggestedSkills,
     telemetry: {
       ...(scored.telemetry || {}),
       rulesInjected: (scheduled.highRules?.length || 0) + (scheduled.midRules?.length || 0),
-      filesSuggested: relevantFiles.length
+      filesSuggested: relevantFiles.length,
+      skillsSuggested: suggestedSkills.length
     },
     scheduled,
     injected: injectContext,

package/plugins/ctx/lib/scheduler.js

@@ -1,6 +1,6 @@
 const MAX_CONTEXT_CHARS = 4000;
 
-export function scheduleContext({ rules = [], relevantFiles = [], maxChars = MAX_CONTEXT_CHARS } = {}) {
+export function scheduleContext({ rules = [], relevantFiles = [], suggestedSkills = [], maxChars = MAX_CONTEXT_CHARS } = {}) {
   const high = rules.filter((rule) => rule.score >= 0.5);
   const mid = rules.filter((rule) => rule.score >= 0.1 && rule.score < 0.5);
   const dropped = rules.filter((rule) => rule.score < 0.1);
@@ -12,6 +12,9 @@ export function scheduleContext({ rules = [], relevantFiles = [], maxChars = MAX
   if (relevantFiles.length) {
     sections.push(section("Suggested files to check", relevantFiles.map((file) => `- ${file.path}`)));
   }
+  if (suggestedSkills.length) {
+    sections.push(section("Skills to activate for this task", suggestedSkills.map(formatSkill)));
+  }
   if (mid.length) {
     sections.push(section("Additional relevant rules", mid.slice(0, 8).map(formatRule)));
   }
@@ -25,6 +28,7 @@ export function scheduleContext({ rules = [], relevantFiles = [], maxChars = MAX
     midRules: mid,
     droppedRules: dropped,
     relevantFiles,
+    suggestedSkills,
     additionalContext
   };
 }
@@ -39,6 +43,12 @@ function formatRule(rule) {
   return `- ${rule.content}${source}`;
 }
 
+function formatSkill(skill) {
+  const description = skill.description ? `: ${skill.description}` : "";
+  const location = skill.path ? ` (${skill.path})` : "";
+  return `- ${skill.name}${description}${location}`;
+}
+
 function trimToLimit(value, maxChars) {
   if (value.length <= maxChars) return value;
   return `${value.slice(0, Math.max(0, maxChars - 80)).trimEnd()}\n\n[ContextOS truncated context to ${maxChars} chars]`;

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

@@ -3,6 +3,7 @@ import path from "node:path";
 import { readAgentsChain } from "./reader.js";
 import { filterActionableRules, parseRules, scoreRules, findRelevantFiles } from "./analyzer.js";
 import { enhanceRuleScoresWithEmbeddings } from "./embedding-scorer.js";
+import { scanSkills, suggestSkills } from "./skill-discoverer.js";
 
 export async function scoreContext({
   cwd = process.cwd(),
@@ -10,6 +11,8 @@ export async function scoreContext({
   openFiles = [],
   dataDir,
   maxFiles = 5,
+  maxSkills = 3,
+  skills = null,
   embeddingTimeoutMs = 5000,
   fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 80)
 } = {}) {
@@ -36,12 +39,20 @@ export async function scoreContext({
       allowRemote: false
     }
   });
+  const skillCatalog = Array.isArray(skills) ? skills : scanSkills({ cwd });
+  const suggestedSkills = await suggestSkills({
+    prompt,
+    skills: skillCatalog,
+    dataDir,
+    limit: maxSkills
+  });
 
   return {
     cwd,
     prompt,
     scoredRules,
     suggestedFiles,
+    suggestedSkills,
     telemetry: {
       elapsedMs: Date.now() - started,
       modelStatus: embedding.status,
@@ -51,6 +62,8 @@ export async function scoreContext({
       rulesFiltered: rawRules.length - parsedRules.length,
       rulesInjected: scoredRules.filter((rule) => Number(rule.score || 0) >= 0.1).length,
       filesSuggested: suggestedFiles.length,
+      skillsScanned: skillCatalog.length,
+      skillsSuggested: suggestedSkills.length,
       sources: merged.sources.map((source) => path.relative(cwd, source))
     }
   };

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

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { enhanceRuleScoresWithEmbeddings, warmRuleEmbeddings } from "./embedding-scorer.js";
+
+const DEFAULT_LIMIT = 3;
+const DEFAULT_MAX_SKILLS = 2000;
+const DEFAULT_EMBEDDING_CANDIDATES = 120;
+const DEFAULT_SEMANTIC_CATALOG_LIMIT = 300;
+
+export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return [
+    path.join(cwd, ".codex", "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, ".config", "skillshare", "skills"),
+    path.join(home, ".codex", "skills"),
+    path.join(home, ".claude", "skills"),
+    path.join(home, ".gemini", "skills"),
+    path.join(home, ".gemini", "antigravity", "skills"),
+    path.join(home, ".gemini", "antigravity-cli", "skills")
+  ];
+}
+
+export function parseSkillFrontmatter(content = "", { fallbackName = "", skillPath = "" } = {}) {
+  const text = String(content || "");
+  const frontmatter = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
+  const fields = frontmatter ? parseYamlishFields(frontmatter[1]) : {};
+  const body = frontmatter ? text.slice(frontmatter[0].length) : text;
+  const fallbackDescription = firstParagraph(body);
+  return {
+    name: fields.name || fallbackName || path.basename(path.dirname(skillPath)),
+    description: fields.description || fallbackDescription,
+    path: skillPath
+  };
+}
+
+function parseYamlishFields(frontmatter) {
+  const fields = {};
+  const lines = String(frontmatter || "").split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    value = value.replace(/^["']|["']$/g, "");
+    fields[key] = value;
+  }
+  return fields;
+}
+
+function firstParagraph(body) {
+  return String(body || "")
+    .split(/\n\s*\n/)
+    .map((part) => part.replace(/^#+\s*/gm, "").replace(/\s+/g, " ").trim())
+    .find(Boolean) || "";
+}
+
+export function scanSkills({ cwd = process.cwd(), roots = skillSearchRoots({ cwd }), maxSkills = DEFAULT_MAX_SKILLS } = {}) {
+  const skills = [];
+  const seen = new Set();
+  for (const root of roots) {
+    for (const skillPath of findSkillFiles(root)) {
+      if (skills.length >= maxSkills) return skills;
+      const realPath = safeRealpath(skillPath) || skillPath;
+      if (seen.has(realPath)) continue;
+      seen.add(realPath);
+      let content = "";
+      try {
+        content = fs.readFileSync(skillPath, "utf8");
+      } catch {
+        continue;
+      }
+      const skill = parseSkillFrontmatter(content, {
+        fallbackName: path.basename(path.dirname(skillPath)),
+        skillPath
+      });
+      if (!skill.name || !skill.description) continue;
+      skills.push({
+        ...skill,
+        root,
+        scope: isInsidePath(skillPath, cwd) ? "project" : "global",
+        relativePath: path.relative(cwd, skillPath)
+      });
+    }
+  }
+  return skills;
+}
+
+function findSkillFiles(root) {
+  const files = [];
+  walk(root, 0, files);
+  return files;
+}
+
+function walk(directory, depth, files) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      walk(fullPath, depth + 1, files);
+    } else if (entry.isFile() && entry.name === "SKILL.md") {
+      files.push(fullPath);
+    }
+  }
+}
+
+function safeRealpath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(path.resolve(parentPath), path.resolve(filePath));
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export async function suggestSkills({
+  prompt = "",
+  skills = [],
+  dataDir,
+  limit = DEFAULT_LIMIT,
+  timeoutMs = Number(process.env.CONTEXTOS_SKILL_EMBEDDING_TIMEOUT_MS || process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || 800)
+} = {}) {
+  if (!String(prompt || "").trim() || !skills.length) return [];
+  const base = scoreSkillsByKeyword({ prompt, skills });
+  if (skills.length > DEFAULT_SEMANTIC_CATALOG_LIMIT) {
+    return finalizeSkillScores(base, limit);
+  }
+
+  const embeddingCandidates = selectEmbeddingCandidates(base);
+  if (!embeddingCandidates.length) return [];
+
+  const embedding = await enhanceRuleScoresWithEmbeddings(embeddingCandidates, prompt, {
+    dataDir,
+    sources: embeddingCandidates.map((skill) => skill.path).filter(Boolean),
+    timeoutMs,
+    allowRemote: false
+  });
+
+  return finalizeSkillScores(embedding.rules, limit);
+}
+
+function finalizeSkillScores(skills, limit) {
+  return skills
+    .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,
+      reasons: rule.reasons || []
+    }))
+    .filter((skill) => Number(skill.keywordScore || 0) >= 0.35 || Number(skill.embeddingScore || 0) >= 0.62)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, limit);
+}
+
+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,
+  allowRemote = true,
+  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",
+    dataDir,
+    sources: skills.map((skill) => skill.path).filter(Boolean),
+    allowRemote
+  });
+}
+
+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 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 nameHit = normalizedPrompt.includes(normalizedName);
+    const nameTokenHit = nameTokens.length > 1 && nameTokens.every((token) => promptTokens.has(token));
+    const scopeBonus = skill.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,
+      content,
+      score,
+      keywordScore: score,
+      reasons: [
+        ...(matches.length ? [`keyword:${matches.slice(0, 4).join(",")}`] : []),
+        ...(nameHit || nameTokenHit ? ["name-match"] : [])
+      ],
+      originalOrder: index
+    };
+  });
+}
+
+function normalize(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}

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

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync, execSync } from "node:child_process";
+
+const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
+const INSTALL_SH_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.sh";
+const INSTALL_PS_URL = "https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1";
+
+function statusLine(label, value) {
+  return `[ctx] ${label.padEnd(38)} ${value}`;
+}
+
+function runCommand(command, args = [], { cwd = process.cwd(), stdio = "pipe", dryRun = false } = {}) {
+  if (dryRun) return { stdout: "", skipped: true };
+  const stdout = execFileSync(command, args, { cwd, stdio, encoding: "utf8" });
+  return { stdout: stdout || "" };
+}
+
+function runShell(command, { cwd = process.cwd(), stdio = "inherit", dryRun = false } = {}) {
+  if (dryRun) return { stdout: "", skipped: true };
+  const stdout = execSync(command, { cwd, stdio, encoding: "utf8" });
+  return { stdout: stdout || "" };
+}
+
+export function parseSyncSkillsArgs(args = []) {
+  const agentsFlag = args.indexOf("--agents");
+  const agents = agentsFlag >= 0
+    ? String(args[agentsFlag + 1] || "").split(",").map((item) => item.trim()).filter(Boolean)
+    : DEFAULT_AGENTS;
+  return {
+    skills: args.includes("--skills"),
+    agents,
+    dryRun: args.includes("--dry-run"),
+    noCollect: args.includes("--no-collect"),
+    yes: args.includes("--yes") || args.includes("-y")
+  };
+}
+
+export function detectOS(platform = process.platform) {
+  if (platform === "darwin") return "mac";
+  if (platform === "win32") return "windows";
+  return "linux";
+}
+
+export function skillshareConfigDir({ home = os.homedir() } = {}) {
+  return path.join(home, ".config", "skillshare");
+}
+
+export function skillshareSourceDir({ home = os.homedir() } = {}) {
+  return path.join(skillshareConfigDir({ home }), "skills");
+}
+
+export function checkSkillshareInstalled({ run = runCommand } = {}) {
+  try {
+    const result = run("skillshare", ["--version"]);
+    return { installed: true, version: result.stdout.trim() || "installed" };
+  } catch {
+    return { installed: false, version: "" };
+  }
+}
+
+async function shouldInstallSkillshare({ yes = false } = {}) {
+  if (yes) return true;
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("[ctx] skillshare is not installed. Install now? [Y/n] ");
+    return !/^n(o)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function installSkillshare({
+  run = runCommand,
+  runShellCommand = runShell,
+  yes = false,
+  dryRun = false,
+  platform = process.platform
+} = {}) {
+  const accepted = dryRun || await shouldInstallSkillshare({ yes });
+  if (!accepted) {
+    throw new Error("skillshare is required for ctx sync --skills. Install it manually with `curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh` or rerun with --yes.");
+  }
+
+  const osName = detectOS(platform);
+  if (osName === "windows") {
+    run("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", `irm ${INSTALL_PS_URL} | iex`], { stdio: "inherit", dryRun });
+  } else {
+    runShellCommand(`curl -fsSL ${INSTALL_SH_URL} | sh`, { stdio: "inherit", dryRun });
+  }
+
+  const check = checkSkillshareInstalled({ run });
+  if (!dryRun && !check.installed) {
+    throw new Error("skillshare install finished but `skillshare --version` still failed. Check PATH or install skillshare manually.");
+  }
+  return check;
+}
+
+export function detectExistingSkills({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return skillRoots({ cwd, home })
+    .map((root) => ({ path: root, count: countSkillFiles(root) }))
+    .filter((entry) => entry.count > 0);
+}
+
+function skillRoots({ cwd, home }) {
+  return [
+    path.join(home, ".claude", "skills"),
+    path.join(home, ".codex", "skills"),
+    path.join(home, ".gemini", "antigravity", "skills"),
+    path.join(home, ".gemini", "antigravity-cli", "skills"),
+    path.join(cwd, ".claude", "skills"),
+    path.join(cwd, ".codex", "skills"),
+    path.join(cwd, ".gemini", "antigravity", "skills"),
+    path.join(cwd, ".gemini", "antigravity-cli", "skills")
+  ];
+}
+
+function countSkillFiles(root) {
+  return findSkillFiles(root).length;
+}
+
+function findSkillFiles(root) {
+  const files = [];
+  walk(root, 0, files);
+  return files;
+}
+
+function walk(directory, depth, files) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) {
+      const stat = safeStat(fullPath);
+      if (stat?.isDirectory()) walk(fullPath, depth + 1, files);
+    } else if (entry.isDirectory()) {
+      walk(fullPath, depth + 1, files);
+    } else if (entry.isFile() && entry.name === "SKILL.md") {
+      files.push(fullPath);
+    }
+  }
+}
+
+function safeStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export function isSkillshareInitialized({ home = os.homedir() } = {}) {
+  return fs.existsSync(skillshareConfigDir({ home }));
+}
+
+export async function syncSkills({
+  cwd = process.cwd(),
+  home = os.homedir(),
+  args = [],
+  run = runCommand,
+  runShellCommand = runShell,
+  logger = console.log,
+  rebuildSkillEmbeddings = async () => ({ count: 0, cachePath: null })
+} = {}) {
+  const options = parseSyncSkillsArgs(args);
+  if (!options.skills) throw new Error("Usage: ctx sync --skills [--dry-run] [--no-collect] [--agents codex,claude,antigravity]");
+
+  const installed = checkSkillshareInstalled({ run });
+  logger(statusLine("Checking skillshare installation...", installed.installed ? `✓ ${installed.version}` : "not found"));
+  if (!installed.installed) {
+    logger("");
+    logger("skillshare is required to sync skills across agents.");
+    const postInstall = await installSkillshare({
+      run,
+      runShellCommand,
+      yes: options.yes,
+      dryRun: options.dryRun,
+      platform: process.platform
+    });
+    logger(statusLine("Installing skillshare...", options.dryRun ? "dry-run" : `✓ ${postInstall.version}`));
+  }
+
+  const initialized = isSkillshareInitialized({ home });
+  logger(statusLine("Checking skillshare config...", initialized ? "✓ initialized" : "not initialized"));
+
+  if (!initialized) {
+    const existing = detectExistingSkills({ cwd, home });
+    if (existing.length) {
+      logger("[ctx] Found existing skills:");
+      for (const entry of existing) {
+        logger(`      ${entry.path.padEnd(44)} ${entry.count} skills`);
+      }
+    } else {
+      logger("[ctx] No existing skills found.");
+    }
+
+    run("skillshare", ["init"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+    logger(statusLine("Initializing skillshare...", options.dryRun ? "dry-run" : "✓ initialized"));
+
+    if (existing.length && !options.noCollect) {
+      run("skillshare", ["backup"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+      logger(statusLine("Backing up...", options.dryRun ? "dry-run" : "✓ backup created"));
+      run("skillshare", ["collect", "--all"], { cwd, stdio: "inherit", dryRun: options.dryRun });
+      const collected = countSkillFiles(skillshareSourceDir({ home }));
+      logger(statusLine("Collecting from all agents...", options.dryRun ? "dry-run" : `✓ ${collected} skills collected`));
+    }
+  }
+
+  const syncArgs = ["sync"];
+  if (options.dryRun) syncArgs.push("--dry-run");
+  if (options.agents.length) syncArgs.push("--agents", options.agents.join(","));
+  run("skillshare", syncArgs, { cwd, stdio: "inherit", 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) {
+    embeddings = await rebuildSkillEmbeddings({ cwd, home, sourceDir: skillshareSourceDir({ home }) });
+    logger(statusLine("Rebuilding skill embeddings...", `✓ ${embeddings.count || 0} skills indexed`));
+  } else {
+    logger(statusLine("Rebuilding skill embeddings...", "skipped in dry-run"));
+  }
+
+  logger("");
+  logger("Done. Skills are now synced.");
+  logger(`Source: ${skillshareSourceDir({ home })}`);
+  return { options, initialized, sourceDir: skillshareSourceDir({ home }), syncedCount, embeddings };
+}

package/plugins/ctx/mcp/contextos-server.js

@@ -11,16 +11,23 @@ export function createContextOSMcpServer({ dataDir }) {
 
   server.registerTool("ctx_score_context", {
     title: "Score ContextOS prompt context",
-    description: "Scores AGENTS.md rules and suggests files for a Codex prompt.",
+    description: "Scores AGENTS.md rules and suggests files/skills for an agent prompt.",
     inputSchema: {
       cwd: z.string().optional(),
       prompt: z.string(),
       openFiles: z.array(z.string()).optional(),
-      maxFiles: z.number().int().positive().max(20).optional()
+      maxFiles: z.number().int().positive().max(20).optional(),
+      maxSkills: z.number().int().positive().max(10).optional(),
+      skills: z.array(z.object({
+        name: z.string(),
+        description: z.string(),
+        path: z.string().optional()
+      })).optional()
     },
     outputSchema: {
       scoredRules: z.array(z.any()),
       suggestedFiles: z.array(z.any()),
+      suggestedSkills: z.array(z.any()),
       telemetry: z.record(z.string(), z.any())
     }
   }, async (args) => {
@@ -29,7 +36,9 @@ export function createContextOSMcpServer({ dataDir }) {
       prompt: args.prompt || "",
       openFiles: args.openFiles || [],
       dataDir,
-      maxFiles: args.maxFiles || 5
+      maxFiles: args.maxFiles || 5,
+      maxSkills: args.maxSkills || 3,
+      skills: args.skills
     });
     return {
       content: [
@@ -41,6 +50,7 @@ export function createContextOSMcpServer({ dataDir }) {
       structuredContent: {
         scoredRules: result.scoredRules,
         suggestedFiles: result.suggestedFiles,
+        suggestedSkills: result.suggestedSkills,
         telemetry: result.telemetry
       }
     };

package/plugins/ctx/mcp/server.js

@@ -68,7 +68,9 @@ async function handleBridgeRequest(socket, raw) {
       prompt: payload.prompt || "",
       openFiles: payload.openFiles || [],
       dataDir,
-      maxFiles: payload.maxFiles || 5
+      maxFiles: payload.maxFiles || 5,
+      maxSkills: payload.maxSkills || 3,
+      skills: payload.skills
     });
     socket.end(JSON.stringify(result));
   } catch (error) {
@@ -76,6 +78,7 @@ async function handleBridgeRequest(socket, raw) {
       error: error?.message || String(error),
       scoredRules: [],
       suggestedFiles: [],
+      suggestedSkills: [],
       telemetry: { elapsedMs: 0, modelStatus: "error" }
     }));
   }