amalgm 0.1.129 → 0.1.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.129",
+  "version": "0.1.130",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/agent-bundles/bundles.js

@@ -5,6 +5,7 @@ const crypto = require('crypto');
 const { getAgentConfig, upsertAgentConfig, agentFieldsFromConfig } = require('../agent-config/store');
 const { normalizeAgentConfig } = require('../agent-config/schema');
 const { createAgent, getAllAgentsWithBuiltins, resolveAgent } = require('../agents/store');
+const { hydrateConfigSkills } = require('../skills/store');
 const { defaultToolboxService } = require('../toolbox/service');
 
 const BUNDLE_KIND = 'amalgm.agent.bundle';
@@ -411,7 +412,7 @@ function collectAgentGraph(rootAgentId) {
     seen.add(agentId);
     const agent = resolveAgent(agentId);
     if (!agent) throw new Error(`Agent not found: ${agentId}`);
-    const config = getAgentConfig(agent);
+    const config = hydrateConfigSkills(getAgentConfig(agent));
     ordered.push({
       sourceAgentId: agent.id,
       agent: portableAgent(agent),

package/runtime/scripts/amalgm-mcp/agent-config/compiler/instructions.js

@@ -32,8 +32,7 @@ function compileSkillsSection(skills) {
     const path = sourcePath(skill.source);
     const details = [
       path ? `Path: ${path}` : '',
-      skill.content && path ? 'Read the skill file when the task matches this skill.' : '',
-      skill.content && !path ? skill.content.trim() : '',
+      skill.content ? skill.content.trim() : path ? 'Read the skill file when the task matches this skill.' : '',
     ];
     lines.push(markdownListItem(title, details));
   }

package/runtime/scripts/amalgm-mcp/agent-config/schema.js

@@ -207,7 +207,7 @@ function agentFieldsFromConfig(config = {}) {
     systemPrompt: normalized.instructions,
     skills: normalized.skills
       .filter((skill) => skill.enabled !== false)
-      .map((skill) => skill.content || skill.name)
+      .map((skill) => skill.name || skill.id || skill.content)
       .filter(Boolean),
     loadout: normalized.loadout,
     hooks: normalized.hooks,

package/runtime/scripts/amalgm-mcp/agent-config/store.js

@@ -7,6 +7,7 @@ const {
   configFromAgent,
   normalizeAgentConfig,
 } = require('./schema');
+const { hydrateConfigSkills } = require('../skills/store');
 
 function nowIso() {
   return new Date().toISOString();
@@ -119,9 +120,11 @@ function listAgentConfigs(db = openLocalDb()) {
     .filter(Boolean);
 }
 
-function agentWithConfig(agent) {
+function agentWithConfig(agent, options = {}) {
   if (!agent) return null;
-  const config = getAgentConfig(agent);
+  const config = options.hydrateSkills
+    ? hydrateConfigSkills(getAgentConfig(agent))
+    : getAgentConfig(agent);
   return {
     ...agent,
     ...agentFieldsFromConfig(config),

package/runtime/scripts/amalgm-mcp/agents/rest.js

@@ -67,7 +67,7 @@ async function handleGet(body, sendJson) {
   const { agent_id } = body;
   const agent = resolveAgent(agent_id);
   if (!agent) return sendJson(404, { error: `Agent not found: ${agent_id}` });
-  sendJson(200, { agent: agentWithConfig(agent) });
+  sendJson(200, { agent: agentWithConfig(agent, { hydrateSkills: true }) });
 }
 
 async function handleCreate(body, sendJson) {

package/runtime/scripts/amalgm-mcp/agents/talk.js

@@ -41,6 +41,7 @@ const {
 const { agentFieldsFromConfig, getAgentConfig } = require('../agent-config/store');
 const { renderAgentInstructions } = require('../agent-config/renderers/instructions');
 const { loadoutToolIds } = require('../agent-config/loadout');
+const { hydrateConfigSkills } = require('../skills/store');
 const credentialAdapter = require('../../credential-adapter');
 const { buildLocalMcpServerConfigs } = require('../lib/mcp-resolver');
 const {
@@ -599,7 +600,7 @@ async function handleTalkToAgent(args, context = {}) {
     agent.baseHarnessId,
     agent.authMethod || preferredAuthMethod,
   );
-  const agentConfig = getAgentConfig(agent);
+  const agentConfig = hydrateConfigSkills(getAgentConfig(agent));
   const agentFields = agentFieldsFromConfig(agentConfig);
   const agentFiles = normalizeStringList(agent.files);
   const agentSkills = normalizeStringList(agentFields.skills);

package/runtime/scripts/amalgm-mcp/fs/search.js

@@ -203,6 +203,64 @@ async function collectSkillEntries(root) {
   return skills;
 }
 
+function pathStartsWithParent(filePath, parentPath) {
+  const normalizedFile = toPosix(path.resolve(filePath));
+  const normalizedParent = toPosix(path.resolve(parentPath));
+  return normalizedFile === normalizedParent || normalizedFile.startsWith(`${normalizedParent}/`);
+}
+
+function includeRegisteredSkillForRoots(skill, roots) {
+  if (!skill || typeof skill !== 'object') return false;
+  if (!Array.isArray(roots) || roots.length === 0) return true;
+  const scope = String(skill.source?.scope || '');
+  if (scope === 'global') return true;
+  const skillPath = String(skill.source?.path || '');
+  const rootPath = String(skill.source?.rootPath || '');
+  return roots.some((root) => (
+    pathStartsWithParent(skillPath, root)
+    || pathStartsWithParent(rootPath, root)
+  ));
+}
+
+function rankedRegistrySkill(query, skill) {
+  const skillPath = String(skill?.source?.path || '');
+  if (!skillPath) return null;
+  const title = String(skill.name || '').trim() || pathBasename(skillPath.replace(/\/SKILL\.md$/i, ''));
+  const description = typeof skill.description === 'string' && skill.description.trim()
+    ? skill.description.trim()
+    : undefined;
+  const score = Math.max(
+    fuzzyScorePath(query, skillPath),
+    fuzzyScore(query, title) + 8,
+    description ? fuzzyScore(query, description) : 0,
+  );
+  if (score <= 0) return null;
+  return {
+    id: `skill:${skillPath}`,
+    kind: 'skill',
+    title,
+    subtitle: skillPath,
+    path: skillPath,
+    isDirectory: false,
+    isSkill: true,
+    description,
+    score,
+  };
+}
+
+function collectRegisteredSkillItems(query, roots) {
+  try {
+    const { listSkills } = require('../skills/store');
+    const skills = listSkills({ source: 'fs:search' });
+    return skills
+      .filter((skill) => includeRegisteredSkillForRoots(skill, roots))
+      .map((skill) => rankedRegistrySkill(query, skill))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 function searchKindForEntry(entry) {
   if (isSkillFile(entry.relativePath)) return 'skill';
   return entry.isDirectory ? 'folder' : 'file';
@@ -330,6 +388,7 @@ function createFsSearchHandler({ resolveSafePath }) {
       }
     }
 
+    const registrySkillItems = collectRegisteredSkillItems(query, roots);
     const kindOrder = { skill: 0, file: 1, folder: 2 };
     const seenItems = new Set();
     const items = [];
@@ -343,6 +402,13 @@ function createFsSearchHandler({ resolveSafePath }) {
       }
     }
 
+    for (const item of registrySkillItems) {
+      const key = `${item.kind}:${item.path}`;
+      if (seenItems.has(key)) continue;
+      seenItems.add(key);
+      items.push(item);
+    }
+
     items.sort((left, right) => {
       if (right.score !== left.score) return right.score - left.score;
       if (kindOrder[left.kind] !== kindOrder[right.kind]) return kindOrder[left.kind] - kindOrder[right.kind];
@@ -367,7 +433,7 @@ function createFsSearchHandler({ resolveSafePath }) {
       skippedDirs: 0,
       errors: errors.length,
       collectedEntries: 0,
-      skillEntries: 0,
+      skillEntries: registrySkillItems.length,
       timedOut: performance.now() > deadline,
       truncated: false,
     });

package/runtime/scripts/amalgm-mcp/server/routes/agents.js

@@ -3,6 +3,7 @@
 const agentsRest = require('../../agents/rest');
 const agentConfigRest = require('../../agent-config/rest');
 const agentBundlesRest = require('../../agent-bundles/rest');
+const skillsRest = require('../../skills/rest');
 
 async function handleAgentRoutes(ctx) {
   if (ctx.pathname === '/agent-config/get' && ctx.method === 'POST') {
@@ -25,6 +26,18 @@ async function handleAgentRoutes(ctx) {
     agentBundlesRest.handleInstall(await ctx.readJsonBody(), ctx.sendJson);
     return true;
   }
+  if (ctx.pathname === '/skills/list' && ctx.method === 'GET') {
+    skillsRest.handleList(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/skills/refresh' && ctx.method === 'POST') {
+    skillsRest.handleRefresh(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/skills/public/install' && ctx.method === 'POST') {
+    skillsRest.handleInstallPublic(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
   if (ctx.pathname === '/agents/list' && ctx.method === 'GET') {
     agentsRest.handleList(ctx.sendJson);
     return true;

package/runtime/scripts/amalgm-mcp/skills/public.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const { syncInstalledSkills } = require('./store');
+
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 10 * 1024 * 1024;
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function isSupportedInstallSource(value) {
+  const source = cleanString(value);
+  if (!source) return false;
+  if (/^https?:\/\/[^\s]+$/i.test(source)) return true;
+  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(source);
+}
+
+function buildInstallSkillArgs({ installUrl, slug }) {
+  const source = cleanString(installUrl);
+  const skillSlug = cleanString(slug);
+  if (!isSupportedInstallSource(source)) {
+    throw new Error('installUrl must be an https URL or owner/repo reference');
+  }
+  if (!skillSlug) {
+    throw new Error('slug is required');
+  }
+  return [
+    'exec',
+    '--yes',
+    '--package=skills',
+    '--',
+    'skills',
+    'add',
+    source,
+    '--skill',
+    skillSlug,
+    '--agent',
+    'codex',
+    '--global',
+    '--yes',
+  ];
+}
+
+function matchesInstalledSlug(skill, slug) {
+  const normalizedSlug = cleanString(slug).toLowerCase();
+  if (!normalizedSlug || !skill || typeof skill !== 'object') return false;
+  const name = cleanString(skill.name).toLowerCase();
+  const directoryPath = cleanString(skill?.source?.directoryPath).toLowerCase();
+  const sourcePath = cleanString(skill?.source?.path).toLowerCase();
+  return name === normalizedSlug
+    || directoryPath.endsWith(`/${normalizedSlug}`)
+    || sourcePath.endsWith(`/${normalizedSlug}/skill.md`);
+}
+
+function findInstalledSkillBySlug(skills, slug) {
+  return (Array.isArray(skills) ? skills : []).find((skill) => matchesInstalledSlug(skill, slug)) || null;
+}
+
+async function installPublicSkill({ installUrl, slug, homeDir, selectedCwd } = {}) {
+  const args = buildInstallSkillArgs({ installUrl, slug });
+  let installError = null;
+
+  try {
+    await execFileAsync(npmCommand(), args, {
+      encoding: 'utf8',
+      maxBuffer: MAX_BUFFER,
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      env: {
+        ...process.env,
+        npm_config_audit: 'false',
+        npm_config_fund: 'false',
+      },
+      timeout: Number(process.env.AMALGM_SKILLS_INSTALL_TIMEOUT_MS || 300000),
+    });
+  } catch (error) {
+    installError = error;
+  }
+
+  const skills = syncInstalledSkills({
+    force: true,
+    includeContent: false,
+    ...(cleanString(homeDir) ? { homeDir } : {}),
+    ...(cleanString(selectedCwd) ? { selectedCwd } : {}),
+    source: 'skills:public-install',
+  });
+  const installedSkill = findInstalledSkillBySlug(skills, slug);
+
+  if (!installError) {
+    return { ok: true, alreadyInstalled: false, installedSkill, skills };
+  }
+
+  if (installedSkill) {
+    return { ok: true, alreadyInstalled: true, installedSkill, skills };
+  }
+
+  const stderr = cleanString(installError.stderr);
+  const stdout = cleanString(installError.stdout);
+  const message = stderr || stdout || installError.message || 'Failed to install public skill';
+  throw new Error(message);
+}
+
+module.exports = {
+  buildInstallSkillArgs,
+  findInstalledSkillBySlug,
+  installPublicSkill,
+};

package/runtime/scripts/amalgm-mcp/skills/rest.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { listSkills, syncInstalledSkills } = require('./store');
+const { installPublicSkill } = require('./public');
+
+async function handleList(query, sendJson) {
+  try {
+    const refresh = String(query?.refresh || '').toLowerCase() === '1' || String(query?.refresh || '').toLowerCase() === 'true';
+    const includeContent = String(query?.include_content || '').toLowerCase() === '1'
+      || String(query?.include_content || '').toLowerCase() === 'true';
+    const skills = refresh
+      ? syncInstalledSkills({ force: true, includeContent, source: 'skills:list' })
+      : listSkills({ includeContent, source: 'skills:list' });
+    sendJson(200, { skills });
+  } catch (error) {
+    sendJson(500, { error: error.message || 'Failed to list skills' });
+  }
+}
+
+async function handleRefresh(sendJson) {
+  try {
+    const skills = syncInstalledSkills({ force: true, source: 'skills:refresh' });
+    sendJson(200, { ok: true, skills });
+  } catch (error) {
+    sendJson(500, { error: error.message || 'Failed to refresh skills' });
+  }
+}
+
+async function handleInstallPublic(body, sendJson) {
+  try {
+    const result = await installPublicSkill({
+      installUrl: body?.installUrl,
+      slug: body?.slug,
+      homeDir: body?.homeDir,
+      selectedCwd: body?.selectedCwd,
+    });
+    sendJson(200, result);
+  } catch (error) {
+    sendJson(500, { error: error.message || 'Failed to install public skill' });
+  }
+}
+
+module.exports = {
+  handleInstallPublic,
+  handleList,
+  handleRefresh,
+};

package/runtime/scripts/amalgm-mcp/skills/roots.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readUserPreferences } = require('../lib/prefs');
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function normalizePath(value) {
+  const clean = cleanString(value);
+  if (!clean) return '';
+  return path.resolve(clean);
+}
+
+function uniquePaths(values) {
+  const seen = new Set();
+  const out = [];
+  for (const value of values) {
+    const normalized = normalizePath(value);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function existingDirectory(dirPath) {
+  const normalized = normalizePath(dirPath);
+  if (!normalized) return '';
+  try {
+    const stat = fs.statSync(normalized);
+    return stat.isDirectory() ? normalized : '';
+  } catch {
+    return '';
+  }
+}
+
+function prefsSelectedCwd() {
+  try {
+    const prefs = readUserPreferences();
+    const cwd = prefs?.last_used?.cwd;
+    return normalizePath(cwd);
+  } catch {
+    return '';
+  }
+}
+
+function walkProjectSkillRoots(selectedCwd) {
+  const roots = [];
+  let current = existingDirectory(selectedCwd);
+  while (current) {
+    const skillRoot = existingDirectory(path.join(current, '.agents', 'skills'));
+    if (skillRoot) roots.push(skillRoot);
+    const parent = path.dirname(current);
+    if (!parent || parent === current) break;
+    current = parent;
+  }
+  return roots;
+}
+
+function homeDir() {
+  return normalizePath(process.env.AMALGM_NATIVE_HOME || os.homedir());
+}
+
+function buildCanonicalSkillRoots(options = {}) {
+  const selectedCwd = normalizePath(options.selectedCwd) || prefsSelectedCwd();
+  const home = normalizePath(options.homeDir) || homeDir();
+  const codeXHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
+  const claudeConfigDir = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
+  return uniquePaths([
+    ...walkProjectSkillRoots(selectedCwd),
+    home ? path.join(home, '.agents', 'skills') : '',
+    codeXHome ? path.join(codeXHome, 'skills') : '',
+    home ? path.join(home, '.codex', 'skills') : '',
+    claudeConfigDir ? path.join(claudeConfigDir, 'skills') : '',
+    home ? path.join(home, '.claude', 'skills') : '',
+    home ? path.join(home, '.config', 'claude', 'skills') : '',
+    home ? path.join(home, '.config', 'opencode', 'skills') : '',
+    home ? path.join(home, '.opencode', 'skills') : '',
+  ]).filter(existingDirectory);
+}
+
+function classifySkillRoot(rootPath, options = {}) {
+  const root = normalizePath(rootPath);
+  const selectedCwd = normalizePath(options.selectedCwd) || prefsSelectedCwd();
+  const home = normalizePath(options.homeDir) || homeDir();
+  const codeXHome = normalizePath(options.codexHome || process.env.CODEX_HOME);
+  const claudeConfigDir = normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
+
+  if (selectedCwd && root.startsWith(path.join(selectedCwd, '.agents', 'skills'))) {
+    return { provider: 'shared', scope: 'project', rootLabel: 'Project skills' };
+  }
+  if (root.endsWith(path.normalize(path.join('.agents', 'skills')))) {
+    return { provider: 'shared', scope: 'project', rootLabel: 'Project skills' };
+  }
+  if (home && root === normalizePath(path.join(home, '.agents', 'skills'))) {
+    return { provider: 'shared', scope: 'global', rootLabel: 'Shared global skills' };
+  }
+  if (
+    (codeXHome && root === normalizePath(path.join(codeXHome, 'skills')))
+    || (home && root === normalizePath(path.join(home, '.codex', 'skills')))
+  ) {
+    return { provider: 'codex', scope: 'global', rootLabel: 'Codex skills' };
+  }
+  if (
+    (claudeConfigDir && root === normalizePath(path.join(claudeConfigDir, 'skills')))
+    || (home && root === normalizePath(path.join(home, '.claude', 'skills')))
+    || (home && root === normalizePath(path.join(home, '.config', 'claude', 'skills')))
+  ) {
+    return { provider: 'claude_code', scope: 'global', rootLabel: 'Claude Code skills' };
+  }
+  if (
+    (home && root === normalizePath(path.join(home, '.config', 'opencode', 'skills')))
+    || (home && root === normalizePath(path.join(home, '.opencode', 'skills')))
+  ) {
+    return { provider: 'opencode', scope: 'global', rootLabel: 'OpenCode skills' };
+  }
+  return { provider: 'shared', scope: 'global', rootLabel: 'Installed skills' };
+}
+
+module.exports = {
+  buildCanonicalSkillRoots,
+  classifySkillRoot,
+  homeDir,
+  normalizePath,
+  prefsSelectedCwd,
+  uniquePaths,
+  walkProjectSkillRoots,
+};

package/runtime/scripts/amalgm-mcp/skills/scanner.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { buildCanonicalSkillRoots, classifySkillRoot, normalizePath } = require('./roots');
+
+const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---/;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function stableId(seed) {
+  return `skill-${crypto.createHash('sha256').update(seed).digest('hex').slice(0, 16)}`;
+}
+
+function trimTrailingSlash(value) {
+  if (value === path.sep) return value;
+  return value.replace(/[\\/]+$/, '');
+}
+
+function parseFrontmatter(markdown) {
+  const text = String(markdown || '');
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) return {};
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const parts = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/);
+    if (!parts) continue;
+    let value = parts[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    fields[parts[1]] = value;
+  }
+  return fields;
+}
+
+function descriptionFromContent(content) {
+  const frontmatter = parseFrontmatter(content);
+  return cleanString(frontmatter.description);
+}
+
+function nameFromContent(content, fallback) {
+  const frontmatter = parseFrontmatter(content);
+  return cleanString(frontmatter.name) || fallback;
+}
+
+function fileDigest(content) {
+  return crypto.createHash('sha256').update(String(content || '')).digest('hex');
+}
+
+function scanSkillDir(rootPath, direntName, options = {}) {
+  const skillDir = path.join(rootPath, direntName);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  let fileStat;
+  try {
+    fileStat = fs.statSync(skillFile);
+  } catch {
+    return null;
+  }
+  if (!fileStat.isFile()) return null;
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const dirLstat = fs.lstatSync(skillDir);
+  const fileLstat = fs.lstatSync(skillFile);
+  const resolvedDirPath = trimTrailingSlash(fs.realpathSync(skillDir));
+  const resolvedPath = normalizePath(fs.realpathSync(skillFile));
+  const classification = classifySkillRoot(rootPath, options);
+  const name = nameFromContent(content, direntName);
+  const description = descriptionFromContent(content);
+  const statMtime = fileStat.mtime instanceof Date ? fileStat.mtime.toISOString() : nowIso();
+  const canonicalPath = normalizePath(skillFile);
+
+  return {
+    id: stableId(canonicalPath),
+    name,
+    description,
+    content,
+    contentHash: fileDigest(content),
+    source: {
+      kind: 'installed',
+      provider: classification.provider,
+      scope: classification.scope,
+      rootLabel: classification.rootLabel,
+      path: canonicalPath,
+      directoryPath: trimTrailingSlash(normalizePath(skillDir)),
+      resolvedPath,
+      resolvedDirectoryPath: resolvedDirPath,
+      rootPath: normalizePath(rootPath),
+      viaSymlink: dirLstat.isSymbolicLink() || fileLstat.isSymbolicLink(),
+    },
+    updatedAt: statMtime,
+    discoveredAt: nowIso(),
+  };
+}
+
+function isDirectoryEntry(rootPath, entry) {
+  if (entry.isDirectory()) return true;
+  if (!entry.isSymbolicLink()) return false;
+  try {
+    return fs.statSync(path.join(rootPath, entry.name)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function scanSkillRoot(rootPath, options = {}) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(rootPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => isDirectoryEntry(rootPath, entry) && !entry.name.startsWith('.'))
+    .map((entry) => scanSkillDir(rootPath, entry.name, options))
+    .filter(Boolean);
+}
+
+function scanInstalledSkills(options = {}) {
+  const roots = buildCanonicalSkillRoots(options);
+  const byPath = new Map();
+  for (const rootPath of roots) {
+    for (const skill of scanSkillRoot(rootPath, options)) {
+      const key = cleanString(skill?.source?.path);
+      if (!key || byPath.has(key)) continue;
+      byPath.set(key, skill);
+    }
+  }
+  return {
+    roots,
+    skills: Array.from(byPath.values()).sort((left, right) => (
+      String(left.name || '').localeCompare(String(right.name || ''))
+      || String(left.source?.path || '').localeCompare(String(right.source?.path || ''))
+    )),
+  };
+}
+
+module.exports = {
+  descriptionFromContent,
+  nameFromContent,
+  parseFrontmatter,
+  scanInstalledSkills,
+};

package/runtime/scripts/amalgm-mcp/skills/store.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent } = require('../state/events');
+const { scanInstalledSkills } = require('./scanner');
+const { homeDir, normalizePath, prefsSelectedCwd } = require('./roots');
+
+const SKILL_SYNC_STALE_MS = 5_000;
+
+let lastSyncedAt = 0;
+let lastSyncKey = '';
+
+function cloneJson(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function includeContent(record, includeContent) {
+  if (includeContent) return cloneJson(record);
+  if (!record || typeof record !== 'object') return record;
+  const copy = cloneJson(record);
+  delete copy.content;
+  delete copy.contentHash;
+  return copy;
+}
+
+function rowToSkill(row, options = {}) {
+  if (!row) return null;
+  try {
+    const parsed = JSON.parse(row.skill_json || '{}');
+    return includeContent(parsed, options.includeContent === true);
+  } catch {
+    return null;
+  }
+}
+
+function listSkillsFromDb(db = openLocalDb(), options = {}) {
+  return db.prepare('SELECT * FROM skills ORDER BY updated_at DESC, name ASC, path ASC')
+    .all()
+    .map((row) => rowToSkill(row, options))
+    .filter(Boolean);
+}
+
+function getSkillById(id, db = openLocalDb(), options = {}) {
+  if (!id) return null;
+  const row = db.prepare('SELECT * FROM skills WHERE id = ?').get(id);
+  return rowToSkill(row, options);
+}
+
+function getSkillByPath(filePath, db = openLocalDb(), options = {}) {
+  const pathValue = cleanString(filePath);
+  if (!pathValue) return null;
+  const row = db.prepare('SELECT * FROM skills WHERE path = ?').get(pathValue);
+  return rowToSkill(row, options);
+}
+
+function publicSkillList(skills) {
+  return (Array.isArray(skills) ? skills : [])
+    .map((skill) => includeContent(skill, false))
+    .filter(Boolean);
+}
+
+function syncKey(options = {}) {
+  return JSON.stringify({
+    selectedCwd: normalizePath(options.selectedCwd) || prefsSelectedCwd(),
+    homeDir: normalizePath(options.homeDir) || homeDir(),
+    codexHome: normalizePath(options.codexHome || process.env.CODEX_HOME),
+    claudeConfigDir: normalizePath(options.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR),
+  });
+}
+
+function replaceSkillRows(db, scannedSkills) {
+  const currentRows = db.prepare('SELECT id, path, skill_json FROM skills').all();
+  const currentById = new Map(currentRows.map((row) => [row.id, row]));
+  const nextIds = new Set(scannedSkills.map((skill) => skill.id));
+  let changed = false;
+
+  for (const skill of scannedSkills) {
+    const existing = currentById.get(skill.id);
+    const serialized = JSON.stringify(skill);
+    if (!existing) {
+      db.prepare(`
+        INSERT INTO skills (id, name, path, provider, scope, root_path, updated_at, discovered_at, skill_json)
+        VALUES (@id, @name, @path, @provider, @scope, @root_path, @updated_at, @discovered_at, @skill_json)
+      `).run({
+        id: skill.id,
+        name: skill.name,
+        path: skill.source.path,
+        provider: skill.source.provider,
+        scope: skill.source.scope,
+        root_path: skill.source.rootPath,
+        updated_at: skill.updatedAt,
+        discovered_at: skill.discoveredAt,
+        skill_json: serialized,
+      });
+      changed = true;
+      continue;
+    }
+    if (existing.skill_json === serialized) continue;
+    db.prepare(`
+      UPDATE skills
+      SET
+        name = @name,
+        path = @path,
+        provider = @provider,
+        scope = @scope,
+        root_path = @root_path,
+        updated_at = @updated_at,
+        discovered_at = @discovered_at,
+        skill_json = @skill_json
+      WHERE id = @id
+    `).run({
+      id: skill.id,
+      name: skill.name,
+      path: skill.source.path,
+      provider: skill.source.provider,
+      scope: skill.source.scope,
+      root_path: skill.source.rootPath,
+      updated_at: skill.updatedAt,
+      discovered_at: skill.discoveredAt,
+      skill_json: serialized,
+    });
+    changed = true;
+  }
+
+  for (const row of currentRows) {
+    if (nextIds.has(row.id)) continue;
+    db.prepare('DELETE FROM skills WHERE id = ?').run(row.id);
+    changed = true;
+  }
+
+  return changed;
+}
+
+function syncInstalledSkills(options = {}) {
+  const now = Date.now();
+  const force = options.force === true;
+  const currentKey = syncKey(options);
+  if (!force && currentKey === lastSyncKey && now - lastSyncedAt < SKILL_SYNC_STALE_MS) {
+    return listSkillsFromDb(openLocalDb(), { includeContent: options.includeContent === true });
+  }
+
+  const db = openLocalDb();
+  const scanned = scanInstalledSkills(options);
+  let nextPublic = [];
+  let changed = false;
+  let event = null;
+
+  db.transaction(() => {
+    changed = replaceSkillRows(db, scanned.skills);
+    nextPublic = publicSkillList(listSkillsFromDb(db, { includeContent: false }));
+    if (!changed) return;
+    event = insertStateEvent(db, {
+      resource: 'skills',
+      op: 'replace',
+      value: nextPublic,
+      source: options.source || 'skills:sync',
+    });
+  })();
+
+  lastSyncedAt = now;
+  lastSyncKey = currentKey;
+  if (event) publishStateEvent(event);
+  return options.includeContent === true
+    ? listSkillsFromDb(db, { includeContent: true })
+    : nextPublic;
+}
+
+function listSkills(options = {}) {
+  return syncInstalledSkills(options);
+}
+
+function skillContentForConfig(skill) {
+  const existingContent = cleanString(skill?.content);
+  if (existingContent) return existingContent;
+
+  const byId = getSkillById(cleanString(skill?.id), openLocalDb(), { includeContent: true });
+  if (byId?.content) return byId.content;
+
+  const sourcePath = cleanString(skill?.source?.path || skill?.path);
+  const byPath = getSkillByPath(sourcePath, openLocalDb(), { includeContent: true });
+  return cleanString(byPath?.content);
+}
+
+function hydrateSkill(skill) {
+  if (!skill || typeof skill !== 'object') return skill;
+  const content = skillContentForConfig(skill);
+  if (!content) return cloneJson(skill);
+  return {
+    ...cloneJson(skill),
+    content,
+  };
+}
+
+function hydrateConfigSkills(config) {
+  if (!config || typeof config !== 'object') return config;
+  return {
+    ...config,
+    skills: Array.isArray(config.skills) ? config.skills.map(hydrateSkill) : [],
+  };
+}
+
+module.exports = {
+  getSkillById,
+  getSkillByPath,
+  hydrateConfigSkills,
+  listSkills,
+  skillContentForConfig,
+  syncInstalledSkills,
+};

package/runtime/scripts/amalgm-mcp/state/db.js

@@ -319,6 +319,24 @@ function migrate(database = openLocalDb()) {
     CREATE INDEX IF NOT EXISTS agent_configs_updated_idx
       ON agent_configs(updated_at DESC);
 
+    CREATE TABLE IF NOT EXISTS skills (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      path TEXT NOT NULL UNIQUE,
+      provider TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      root_path TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      discovered_at TEXT NOT NULL,
+      skill_json TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS skills_updated_idx
+      ON skills(updated_at DESC);
+
+    CREATE INDEX IF NOT EXISTS skills_path_idx
+      ON skills(path);
+
     CREATE TABLE IF NOT EXISTS project_context (
       project_id TEXT PRIMARY KEY,
       project_path TEXT NOT NULL,

package/runtime/scripts/amalgm-mcp/state/snapshot.js

@@ -2,7 +2,7 @@
 
 const { currentSeq } = require('./events');
 
-const DEFAULT_RESOURCES = ['automations', 'triggers', 'workflows', 'automation_runs', 'workflow_cell_runs', 'agents', 'agent_configs', 'apps', 'toolbox', 'tools', 'tool_actions', 'hooks', 'projects', 'workspaces', 'project_context', 'user_preferences', 'chat_payloads', 'mcp_connections', 'browser_profiles', 'browser_auth_bundles', 'browser_login_sessions'];
+const DEFAULT_RESOURCES = ['automations', 'triggers', 'workflows', 'automation_runs', 'workflow_cell_runs', 'agents', 'agent_configs', 'skills', 'apps', 'toolbox', 'tools', 'tool_actions', 'hooks', 'projects', 'workspaces', 'project_context', 'user_preferences', 'chat_payloads', 'mcp_connections', 'browser_profiles', 'browser_auth_bundles', 'browser_login_sessions'];
 
 function normalizeResources(resources) {
   const values = resources ? String(resources).split(',') : DEFAULT_RESOURCES;
@@ -41,6 +41,8 @@ function readResource(resource, cache) {
     }
     case 'agent_configs':
       return require('../agent-config/store').listAgentConfigs();
+    case 'skills':
+      return require('../skills/store').listSkills();
     case 'apps':
       return require('../apps/store').loadApps().apps;
     case 'toolbox':

package/runtime/scripts/amalgm-mcp/tests/agent-bundles.test.js

@@ -5,10 +5,13 @@ process.env.AMALGM_DIR = require('node:fs').mkdtempSync(
 );
 
 const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
 const test = require('node:test');
 
 const { createAgent, resolveAgent } = require('../agents/store');
 const { upsertAgentConfig, getAgentConfig } = require('../agent-config/store');
+const { syncInstalledSkills } = require('../skills/store');
 const { defaultToolboxService } = require('../toolbox/service');
 const { createAgentBundle, installAgentBundle } = require('../agent-bundles/bundles');
 
@@ -243,3 +246,54 @@ test('installing an agent bundle regenerates stale flat graph fields from canoni
   assert.equal(result.ok, true);
   assert.equal(Boolean(resolveAgent(result.rootAgentId)), true);
 });
+
+test('agent bundle snapshots installed skill text from the local registry', () => {
+  const projectRoot = path.join(process.env.AMALGM_DIR, 'bundle-skill-project');
+  const skillDir = path.join(projectRoot, '.agents', 'skills', 'portable-skill');
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), [
+    '---',
+    'name: "portable-skill"',
+    'description: "Portable installed skill"',
+    '---',
+    '',
+    '# Portable skill',
+    '',
+    'Bring this guidance into shared bundles.',
+    '',
+  ].join('\n'));
+
+  const [installedSkill] = syncInstalledSkills({
+    force: true,
+    selectedCwd: projectRoot,
+    homeDir: projectRoot,
+    source: 'agent-bundles:test',
+  }).filter((skill) => skill.name === 'portable-skill');
+
+  const root = createAgent({
+    id: 'bundle-installed-skill-root',
+    name: 'Bundle Installed Skill Root',
+    baseHarnessId: 'codex',
+    baseModelId: 'openai/gpt-5.5',
+    systemPrompt: 'Bundle installed skill root',
+    loadout: { toolIds: [] },
+    authMethod: 'amalgm',
+  });
+  upsertAgentConfig(root.id, {
+    instructions: 'Bundle installed skill root',
+    skills: [{
+      id: installedSkill.id,
+      name: installedSkill.name,
+      description: installedSkill.description,
+      source: installedSkill.source,
+      enabled: true,
+    }],
+    loadout: { toolIds: [] },
+  });
+
+  const { bundle } = createAgentBundle(root.id, { bundleId: 'agent-bundle-installed-skill-test' });
+
+  assert.equal(bundle.skills.length, 1);
+  assert.equal(bundle.skills[0].name, 'portable-skill');
+  assert.match(bundle.skills[0].content, /Bring this guidance into shared bundles/);
+});

package/runtime/scripts/amalgm-mcp/tests/skills.test.js

@@ -0,0 +1,184 @@
+'use strict';
+
+process.env.AMALGM_DIR = require('node:fs').mkdtempSync(
+  require('node:path').join(require('node:os').tmpdir(), 'amalgm-skills-'),
+);
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const { buildInstallSkillArgs, findInstalledSkillBySlug } = require('../skills/public');
+const { scanInstalledSkills } = require('../skills/scanner');
+const { hydrateConfigSkills, listSkills, syncInstalledSkills } = require('../skills/store');
+
+function writeSkill(dirPath, description) {
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(path.join(dirPath, 'SKILL.md'), [
+    '---',
+    `name: "${path.basename(dirPath)}"`,
+    `description: "${description}"`,
+    '---',
+    '',
+    `# ${path.basename(dirPath)}`,
+    '',
+    `Use ${path.basename(dirPath)} when relevant.`,
+    '',
+  ].join('\n'));
+}
+
+test('scanInstalledSkills discovers canonical project/global roots and symlink metadata', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-home-'));
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-project-'));
+  const sourceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-source-'));
+
+  try {
+    const globalSkillDir = path.join(home, '.codex', 'skills', 'global-review');
+    writeSkill(globalSkillDir, 'Global skill');
+
+    const realProjectSkillDir = path.join(sourceRoot, 'project-portability');
+    writeSkill(realProjectSkillDir, 'Project skill');
+    const projectSkillRoot = path.join(project, '.agents', 'skills');
+    fs.mkdirSync(projectSkillRoot, { recursive: true });
+    fs.symlinkSync(realProjectSkillDir, path.join(projectSkillRoot, 'project-portability'));
+
+    const result = scanInstalledSkills({
+      selectedCwd: project,
+      homeDir: home,
+    });
+
+    assert.equal(result.roots.includes(path.join(project, '.agents', 'skills')), true);
+    assert.equal(result.roots.includes(path.join(home, '.codex', 'skills')), true);
+    assert.equal(result.skills.length, 2);
+
+    const projectSkill = result.skills.find((skill) => skill.name === 'project-portability');
+    assert.equal(projectSkill?.source.scope, 'project');
+    assert.equal(projectSkill?.source.viaSymlink, true);
+    assert.equal(projectSkill?.source.resolvedDirectoryPath, fs.realpathSync(realProjectSkillDir));
+
+    const globalSkill = result.skills.find((skill) => skill.name === 'global-review');
+    assert.equal(globalSkill?.source.provider, 'codex');
+    assert.equal(globalSkill?.source.scope, 'global');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(project, { recursive: true, force: true });
+    fs.rmSync(sourceRoot, { recursive: true, force: true });
+  }
+});
+
+test('hydrateConfigSkills loads installed skill content from the registry', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-home-'));
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-project-'));
+
+  try {
+    const skillDir = path.join(project, '.agents', 'skills', 'agent-brief');
+    writeSkill(skillDir, 'Skill used for agent briefing');
+
+    const skills = syncInstalledSkills({
+      force: true,
+      selectedCwd: project,
+      homeDir: home,
+      source: 'skills:test',
+    });
+    const installed = skills.find((skill) => skill.name === 'agent-brief');
+    assert.ok(installed);
+
+    const hydrated = hydrateConfigSkills({
+      version: 1,
+      instructions: '',
+      skills: [{
+        id: installed.id,
+        name: installed.name,
+        source: installed.source,
+        enabled: true,
+      }],
+      loadout: { toolIds: [] },
+      hooks: [],
+      subagents: [],
+    });
+
+    assert.equal(typeof hydrated.skills[0].content, 'string');
+    assert.match(hydrated.skills[0].content, /Use agent-brief when relevant/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('listSkills optionally includes stored skill content', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-home-'));
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-skills-project-'));
+
+  try {
+    const skillDir = path.join(project, '.agents', 'skills', 'portable-review');
+    writeSkill(skillDir, 'Portable review skill');
+
+    syncInstalledSkills({
+      force: true,
+      selectedCwd: project,
+      homeDir: home,
+      includeContent: true,
+      source: 'skills:test',
+    });
+
+    const publicSkills = listSkills({
+      selectedCwd: project,
+      homeDir: home,
+      source: 'skills:test',
+    });
+    const privateSkills = listSkills({
+      selectedCwd: project,
+      homeDir: home,
+      includeContent: true,
+      source: 'skills:test',
+    });
+
+    const publicSkill = publicSkills.find((skill) => skill.name === 'portable-review');
+    const privateSkill = privateSkills.find((skill) => skill.name === 'portable-review');
+    assert.equal(typeof publicSkill?.content, 'undefined');
+    assert.match(String(privateSkill?.content || ''), /Use portable-review when relevant/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('buildInstallSkillArgs targets the global Codex skills install flow', () => {
+  assert.deepEqual(
+    buildInstallSkillArgs({
+      installUrl: 'https://github.com/vercel-labs/skills',
+      slug: 'find-skills',
+    }),
+    [
+      'exec',
+      '--yes',
+      '--package=skills',
+      '--',
+      'skills',
+      'add',
+      'https://github.com/vercel-labs/skills',
+      '--skill',
+      'find-skills',
+      '--agent',
+      'codex',
+      '--global',
+      '--yes',
+    ],
+  );
+});
+
+test('findInstalledSkillBySlug matches installed public skills by name or directory', () => {
+  const installedSkill = {
+    id: 'skill:find-skills',
+    name: 'find-skills',
+    source: {
+      path: '/tmp/.agents/skills/find-skills/SKILL.md',
+      directoryPath: '/tmp/.agents/skills/find-skills',
+    },
+  };
+
+  assert.equal(findInstalledSkillBySlug([installedSkill], 'find-skills'), installedSkill);
+  assert.equal(findInstalledSkillBySlug([installedSkill], 'missing-skill'), null);
+});