@klhapp/skillmux 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.0](https://github.com/klhq/skillmux/compare/v1.8.0...v1.9.0) (2026-08-30)
+
+
+### Added
+
+* track skill provenance and add outdated/update commands ([#133](https://github.com/klhq/skillmux/issues/133)) ([4d4f8c9](https://github.com/klhq/skillmux/commit/4d4f8c94a7e34e1ad030f9904995d02fa5fa2712))
+
+
+### Fixed
+
+* **install:** guard findSymlinks against a symlinked skill_path directory itself ([#146](https://github.com/klhq/skillmux/issues/146)) ([a264afc](https://github.com/klhq/skillmux/commit/a264afc19710206c4f77c61e3a9dccafb54c2894))
+* **install:** prevent symlink smuggling in skill content ([#136](https://github.com/klhq/skillmux/issues/136)) ([2df318c](https://github.com/klhq/skillmux/commit/2df318cfdc974b0f7b9042c3d68fa4fece9109d9))
+* **provenance:** refuse to hash a symlinked SKILL.md instead of following it ([#141](https://github.com/klhq/skillmux/issues/141)) ([74d1b9c](https://github.com/klhq/skillmux/commit/74d1b9c2f8fb2891ce743ccf09b9632fea58aa84))
+* **provenance:** refuse to read a symlinked .skillmux-origin sidecar ([#144](https://github.com/klhq/skillmux/issues/144)) ([c9c0b32](https://github.com/klhq/skillmux/commit/c9c0b327f8cf26e1a9cd9971263cfa4f35235de3))
+* **scan:** guard readTextFileOrNull against symlinks at every call site ([#143](https://github.com/klhq/skillmux/issues/143)) ([6692060](https://github.com/klhq/skillmux/commit/66920601bb4969911063407afa3dbffcf09c00be))
+* **scan:** refuse to scan a symlinked SKILL.md in single-skill-dir mode ([#142](https://github.com/klhq/skillmux/issues/142)) ([b20cd66](https://github.com/klhq/skillmux/commit/b20cd6621a30067643034dd155383afab3540cf2))
+* **security:** validate provenance sidecar values before they reach git subprocess calls ([#135](https://github.com/klhq/skillmux/issues/135)) ([01d643a](https://github.com/klhq/skillmux/commit/01d643a789e353d0d944b7b467f3c9f0894718ce))
+* **sync:** skip symlinking core skill dirs with internal links ([#137](https://github.com/klhq/skillmux/issues/137)) ([f992b39](https://github.com/klhq/skillmux/commit/f992b39720dcdd3e946c6628817bd11b54380f40))
+* **update:** skip file:// source_url in outdated/update by default ([#147](https://github.com/klhq/skillmux/issues/147)) ([9b127d0](https://github.com/klhq/skillmux/commit/9b127d0a65f89cfd32e6ed8d75155ba388349fae))
+* **vault:** guard against a symlinked skill directory, not just its leaf files ([#145](https://github.com/klhq/skillmux/issues/145)) ([63d34e3](https://github.com/klhq/skillmux/commit/63d34e32bc4d91221f03fbbfdf22d3a0fdc7a492))
+* **vault:** refuse to read a symlinked SKILL.md ([#140](https://github.com/klhq/skillmux/issues/140)) ([3220fe3](https://github.com/klhq/skillmux/commit/3220fe393a81922f76729284d156644662f177f2))
+* **vault:** secure listSupportingFiles against symlinks and traversal ([#138](https://github.com/klhq/skillmux/issues/138)) ([6343a30](https://github.com/klhq/skillmux/commit/6343a30747844c5f83b810cbfe3d19ed569ca7cd))
+
+
+### Changed
+
+* **update:** skip cloning drifted skills before fetching ([1b247b6](https://github.com/klhq/skillmux/commit/1b247b6379b021692c839a77d44a81bd736f2bea))
+
 ## [1.8.0](https://github.com/klhq/skillmux/compare/v1.7.1...v1.8.0) (2026-08-28)
 
 

package/README.md

@@ -213,6 +213,7 @@ Useful management commands:
 
 ```sh
 skillmux scan ~/skills
+skillmux outdated
 skillmux core pin csv-formatter --yes
 skillmux project pin my-project code-context --yes
 skillmux skill which csv-formatter

package/docs/skill-management.md

@@ -55,6 +55,38 @@ With no path, `scan` checks the configured vault. `--json` wraps the result in
 the standard CLI automation envelope, while `--format json` selects the
 scanner's raw JSON rendering.
 
+## Check and pull upstream updates
+
+Every skill `install` places in the vault gets a `.skillmux-origin` sidecar
+recording the source repo, resolved commit, and a content hash. Check which
+installed skills have moved upstream:
+
+```sh
+skillmux outdated
+skillmux outdated --json
+```
+
+Skills you authored by hand, or installed before this sidecar existed, carry
+no `.skillmux-origin` and are silently omitted — `outdated` only reports on
+skills it can trace back to a source. A repo that has become unreachable is
+reported per-skill as `check_failed` with a reason; it does not stop the rest
+of the check.
+
+Pull an update for one skill, or every outdated skill at once:
+
+```sh
+skillmux update csv-formatter --dry-run
+skillmux update csv-formatter --yes
+skillmux update --yes
+```
+
+`--dry-run` reports the old and new commit and whether content actually
+changed, without writing anything. A real update re-runs the same scan
+`install` does (`--fail-on` applies the same way) and refuses to overwrite a
+skill whose on-disk content has drifted from what was last installed —
+someone may have hand-edited it. Pass `--force` to overwrite anyway. Like
+`audit prune`, a non-interactive or `--json` run needs `--yes`.
+
 ## Plan client delivery
 
 Use product names for common clients:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -42,10 +42,14 @@ import {
   cloneToTemp,
   deriveRepoName,
   installIntoVault,
+  resolveCloneCommit,
   resolveRepoSource,
   resolveSkillDir,
   validateSkillCandidate,
 } from "./install";
+import { runOutdated } from "./commands/outdated";
+import { runUpdate } from "./commands/update";
+import { hashSkillContent, writeSkillOrigin } from "./provenance";
 import {
   parseManifest,
   resolveManifestPath,
@@ -129,6 +133,8 @@ const KNOWN_COMMANDS = [
   "audit",
   "scan",
   "install",
+  "outdated",
+  "update",
   "eval",
   "doctor",
   "models",
@@ -142,6 +148,8 @@ function isDockerHostManagementCommand(command: string, subCommand: string): boo
       "init",
       "sync",
       "install",
+      "outdated",
+      "update",
       "project",
       "target",
       "core",
@@ -337,6 +345,12 @@ async function main() {
       case "install":
         await runInstall(rawArgv.slice(1), { isJson });
         break;
+      case "outdated":
+        await runOutdated(rawArgv.slice(1), { isJson });
+        break;
+      case "update":
+        await runUpdate(rawArgv.slice(1), { isJson });
+        break;
       case "eval":
         if (subCommand === "promote") {
           await runEvalPromote(commandArgs, { isJson, dryRun: isDryRun });
@@ -374,7 +388,7 @@ async function main() {
         const suggestion = suggestCorrection(command, KNOWN_COMMANDS);
         const msg = suggestion
           ? `Unknown command "${command}". Did you mean "${suggestion}"?`
-          : `usage: skillmux <serve|index|sync|init|project|target|core pin/unpin|report|audit prune|scan|install|eval|doctor|skill which|local-vault init|config show|models download>`;
+          : `usage: skillmux <serve|index|sync|init|project|target|core pin/unpin|report|audit prune|scan|install|outdated|update|eval|doctor|skill which|local-vault init|config show|models download>`;
         throw new Error(msg);
       }
     }
@@ -559,10 +573,12 @@ Operations:
   skillmux report [--server <url> | --db <path>] --since <window> [--json]
   skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
   skillmux eval promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]
+  skillmux outdated [--allow-local-source] [--json]
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]
 
 Commands:
-  serve, index, sync, init, project, target, core, report, audit, scan, install, eval, doctor,
-  skill, local-vault, config, models, context, completions`);
+  serve, index, sync, init, project, target, core, report, audit, scan, install, outdated, update,
+  eval, doctor, skill, local-vault, config, models, context, completions`);
 }
 
 // ---------------------------------------------------------------------------
@@ -827,6 +843,11 @@ async function runSync(args: string[]): Promise<void> {
     console.log(
       `${targetName}: +${result.added.length} -${result.removed.length}${suffix}`,
     );
+    if (result.skipped.length > 0) {
+      console.log(
+        `  warning: refused to sync ${result.skipped.join(", ")} — skill directory contains a symlink`,
+      );
+    }
 
     if (target.project_groups.length > 0) {
       const allGroups = manifest.project ?? {};
@@ -841,6 +862,11 @@ async function runSync(args: string[]): Promise<void> {
         console.log(
           `  ${projectResult.group} -> ${projectResult.pinDir}: +${projectResult.added.length} -${projectResult.removed.length}${suffix}`,
         );
+        if (projectResult.skipped.length > 0) {
+          console.log(
+            `    warning: refused to sync ${projectResult.skipped.join(", ")} — skill directory contains a symlink`,
+          );
+        }
       }
     }
   }
@@ -1612,12 +1638,20 @@ async function runInstall(
       return;
     }
 
+    const commit = resolveCloneCommit(cloneDir);
     const targetDir = installIntoVault(
       vaultPath,
       resolved.skillId,
       resolved.dir,
       force,
     );
+    writeSkillOrigin(targetDir, {
+      source_url: source.url,
+      skill_path: source.skillPath,
+      commit,
+      installed_at: new Date().toISOString(),
+      content_hash: hashSkillContent(targetDir),
+    });
     emitSuccess(
       { isJson: options.isJson },
       { skill_id: resolved.skillId, installed_at: targetDir },

package/src/commands/outdated.ts

@@ -0,0 +1,112 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { isLocalFileUrl, remoteHeadCommit } from "../install";
+import { emitSuccess } from "../output";
+import { readSkillOrigin } from "../provenance";
+import { SKILL_ID_PATTERN } from "../vault";
+
+export interface OutdatedCheckResult {
+  skill_id: string;
+  source_url: string;
+  recorded_commit: string;
+  remote_commit: string | null;
+  status: "up_to_date" | "outdated" | "check_failed" | "local_source_skipped";
+  reason: string | null;
+}
+
+function vaultSkillIds(vaultPath: string): string[] {
+  return readdirSync(vaultPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && SKILL_ID_PATTERN.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export async function checkOutdated(
+  vaultPath: string,
+  options: { allowLocalSource?: boolean } = {},
+): Promise<OutdatedCheckResult[]> {
+  const results: OutdatedCheckResult[] = [];
+  for (const skillId of vaultSkillIds(vaultPath)) {
+    let origin: ReturnType<typeof readSkillOrigin>;
+    try {
+      origin = readSkillOrigin(join(vaultPath, skillId));
+    } catch (error) {
+      // A corrupt or unreadable sidecar is this skill's problem alone — never
+      // let it abort the check for every other skill in the vault (AC3/AC4's
+      // per-skill isolation applies to local parse failures too, not just
+      // unreachable remotes).
+      results.push({
+        skill_id: skillId,
+        source_url: "",
+        recorded_commit: "",
+        remote_commit: null,
+        status: "check_failed",
+        reason: `.skillmux-origin: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+    if (!origin) continue;
+
+    if (!options.allowLocalSource && isLocalFileUrl(origin.source_url)) {
+      results.push({
+        skill_id: skillId,
+        source_url: origin.source_url,
+        recorded_commit: origin.commit,
+        remote_commit: null,
+        status: "local_source_skipped",
+        reason: "source_url is a local file:// path — skipped by default; pass --allow-local-source to check it",
+      });
+      continue;
+    }
+
+    let remoteCommit: string | null = null;
+    let status: OutdatedCheckResult["status"];
+    let reason: string | null = null;
+    try {
+      remoteCommit = await remoteHeadCommit(origin.source_url);
+      status = remoteCommit === origin.commit ? "up_to_date" : "outdated";
+    } catch (error) {
+      status = "check_failed";
+      reason = error instanceof Error ? error.message : String(error);
+    }
+
+    results.push({
+      skill_id: skillId,
+      source_url: origin.source_url,
+      recorded_commit: origin.commit,
+      remote_commit: remoteCommit,
+      status,
+      reason,
+    });
+  }
+  return results;
+}
+
+export async function runOutdated(args: string[], options: { isJson: boolean }): Promise<void> {
+  let allowLocalSource = false;
+  for (const arg of args) {
+    if (arg === "--json") continue;
+    if (arg === "--allow-local-source") {
+      allowLocalSource = true;
+      continue;
+    }
+    throw new Error(`unknown outdated option: ${arg}`);
+  }
+
+  const vaultPath = expandHome((await loadConfig()).vault_path);
+  const skills = await checkOutdated(vaultPath, { allowLocalSource });
+  const checksFailed = skills.filter((s) => s.status === "check_failed").length;
+  process.exitCode = checksFailed > 0 ? 1 : 0;
+
+  emitSuccess({ isJson: options.isJson }, { skills, checks_failed: checksFailed }, () => {
+    if (skills.length === 0) {
+      console.log("outdated: no vault skills carry provenance");
+      return;
+    }
+    for (const s of skills) {
+      const suffix = s.status === "check_failed" ? ` — ${s.reason}` : "";
+      console.log(`[${s.status}] ${s.skill_id}${suffix}`);
+    }
+  });
+}

package/src/commands/update.ts

@@ -0,0 +1,253 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import {
+  cloneToTemp,
+  installIntoVault,
+  isLocalFileUrl,
+  remoteHeadCommit,
+  resolveCloneCommit,
+  resolveSkillDir,
+  validateSkillCandidate,
+} from "../install";
+import { emitSuccess } from "../output";
+import { hashSkillContent, readSkillOrigin, writeSkillOrigin } from "../provenance";
+import type { SkillOrigin } from "../provenance";
+import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
+import { confirmIfNeeded } from "./shared";
+import { checkOutdated } from "./outdated";
+
+type UpdateKind = "update" | "up_to_date" | "skip_drift" | "skip_scan_failed" | "skip_read_error";
+
+interface UpdatePlanItem {
+  skillId: string;
+  oldCommit: string;
+  newCommit: string;
+  contentChanged: boolean;
+  kind: UpdateKind;
+  findings?: ScanFinding[];
+  reason?: string;
+  cloneDir: string | null;
+  fetchedDir: string | null;
+  origin: SkillOrigin;
+}
+
+async function resolveCandidateOrigins(
+  vaultPath: string,
+  skillId: string | undefined,
+  allowLocalSource: boolean,
+): Promise<{ skillId: string; origin: SkillOrigin }[]> {
+  if (skillId) {
+    let origin: SkillOrigin | null;
+    try {
+      origin = readSkillOrigin(join(vaultPath, skillId));
+    } catch (error) {
+      throw new Error(
+        `"${skillId}" has a corrupt .skillmux-origin sidecar: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    if (!origin) {
+      throw new Error(`"${skillId}" has no origin recorded — was this skill installed via "skillmux install"?`);
+    }
+    if (!allowLocalSource && isLocalFileUrl(origin.source_url)) {
+      throw new Error(`"${skillId}" has a local (file://) source — pass --allow-local-source to update it`);
+    }
+    return [{ skillId, origin }];
+  }
+  const outdated = await checkOutdated(vaultPath, { allowLocalSource });
+  return outdated
+    .filter((result) => result.status === "outdated")
+    .map((result) => ({ skillId: result.skill_id, origin: readSkillOrigin(join(vaultPath, result.skill_id))! }));
+}
+
+async function buildPlan(
+  vaultPath: string,
+  candidates: { skillId: string; origin: SkillOrigin }[],
+  failOn: ScanSeverity | undefined,
+  force: boolean,
+): Promise<UpdatePlanItem[]> {
+  const plan: UpdatePlanItem[] = [];
+  for (const { skillId, origin } of candidates) {
+    const skillDir = join(vaultPath, skillId);
+    let currentHash: string;
+    try {
+      currentHash = hashSkillContent(skillDir);
+    } catch (error) {
+      // A skill whose on-disk content can't be safely read (e.g. SKILL.md was
+      // swapped for a symlink after install — same threat model as AC7's drift
+      // check) is this skill's problem alone, matching checkOutdated's per-skill
+      // isolation: never let it abort the batch for every other candidate.
+      plan.push({
+        skillId,
+        oldCommit: origin.commit,
+        newCommit: origin.commit,
+        contentChanged: false,
+        kind: "skip_read_error",
+        reason: error instanceof Error ? error.message : String(error),
+        cloneDir: null,
+        fetchedDir: null,
+        origin,
+      });
+      continue;
+    }
+
+    // Drift is a purely local comparison — check it before fetching anything,
+    // so a drifted (and therefore skipped) skill never pays for a clone.
+    if (currentHash !== origin.content_hash && !force) {
+      plan.push({
+        skillId,
+        oldCommit: origin.commit,
+        newCommit: await remoteHeadCommit(origin.source_url),
+        contentChanged: false,
+        kind: "skip_drift",
+        cloneDir: null,
+        fetchedDir: null,
+        origin,
+      });
+      continue;
+    }
+
+    const cloneDir = await cloneToTemp(origin.source_url);
+    const resolved = resolveSkillDir(cloneDir, skillId, origin.skill_path);
+    const base = {
+      skillId,
+      oldCommit: origin.commit,
+      newCommit: resolveCloneCommit(cloneDir),
+      cloneDir,
+      fetchedDir: resolved.dir,
+      origin,
+    };
+
+    const { findings } = await validateSkillCandidate(skillId, resolved.dir);
+    if (scanExitCode(findings, failOn) !== 0) {
+      plan.push({ ...base, contentChanged: false, kind: "skip_scan_failed", findings });
+      continue;
+    }
+
+    const contentChanged = hashSkillContent(resolved.dir) !== currentHash;
+    plan.push({
+      ...base,
+      contentChanged,
+      kind: base.newCommit === origin.commit && !contentChanged ? "up_to_date" : "update",
+    });
+  }
+  return plan;
+}
+
+export function buildConfirmPrompt(toWrite: Pick<UpdatePlanItem, "skillId" | "origin">[]): string {
+  const lines = toWrite.map((item) => `  ${item.skillId} <- ${item.origin.source_url}`);
+  return `update:\n${lines.join("\n")}\n?`;
+}
+
+function statusFor(kind: UpdateKind, dryRun: boolean): string {
+  switch (kind) {
+    case "update":
+      return dryRun ? "would_update" : "updated";
+    case "skip_drift":
+      return dryRun ? "would_skip_drift" : "skipped_drift";
+    case "skip_scan_failed":
+      return dryRun ? "would_skip_scan_failed" : "skipped_scan_failed";
+    case "skip_read_error":
+      return "skipped_read_error";
+    default:
+      return "up_to_date";
+  }
+}
+
+function parseUpdateArgs(args: string[]): {
+  skillId?: string;
+  yes: boolean;
+  dryRun: boolean;
+  force: boolean;
+  failOn?: ScanSeverity;
+  allowLocalSource: boolean;
+} {
+  let skillId: string | undefined;
+  let yes = false;
+  let dryRun = false;
+  let force = false;
+  let failOn: ScanSeverity | undefined;
+  let allowLocalSource = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--yes") yes = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--allow-local-source") allowLocalSource = true;
+    else if (arg === "--fail-on") {
+      const value = args[++i];
+      if (value !== "low" && value !== "medium" && value !== "high") {
+        throw new Error("--fail-on must be low, medium, or high");
+      }
+      failOn = value;
+    } else if (arg === "--json") {
+      // handled globally
+    } else if (arg?.startsWith("--")) {
+      throw new Error(`unknown update option: ${arg}`);
+    } else if (skillId !== undefined) {
+      throw new Error("skillmux update accepts at most one <skill-id> argument");
+    } else {
+      skillId = arg;
+    }
+  }
+  return { skillId, yes, dryRun, force, failOn, allowLocalSource };
+}
+
+export async function runUpdate(args: string[], options: { isJson: boolean }): Promise<void> {
+  const { skillId, yes, dryRun, force, failOn, allowLocalSource } = parseUpdateArgs(args);
+  const vaultPath = expandHome((await loadConfig()).vault_path);
+
+  const candidates = await resolveCandidateOrigins(vaultPath, skillId, allowLocalSource);
+  const plan = await buildPlan(vaultPath, candidates, failOn, force);
+  try {
+    const toWrite = plan.filter((item) => item.kind === "update");
+
+    if (!dryRun && toWrite.length > 0) {
+      const proceed = await confirmIfNeeded({
+        confirmed: yes,
+        isJson: options.isJson,
+        prompt: buildConfirmPrompt(toWrite),
+        nonInteractiveError: "skillmux update requires --yes when run non-interactively",
+      });
+      if (!proceed) return;
+
+      for (const item of toWrite) {
+        // toWrite is filtered to kind === "update", which is only ever set after
+        // a successful clone above, so fetchedDir is always populated here.
+        const targetDir = installIntoVault(vaultPath, item.skillId, item.fetchedDir as string, true);
+        writeSkillOrigin(targetDir, {
+          source_url: item.origin.source_url,
+          skill_path: item.origin.skill_path,
+          commit: item.newCommit,
+          installed_at: new Date().toISOString(),
+          content_hash: hashSkillContent(targetDir),
+        });
+      }
+    }
+
+    const skills = plan.map((item) => ({
+      skill_id: item.skillId,
+      source_url: item.origin.source_url,
+      old_commit: item.oldCommit,
+      new_commit: item.newCommit,
+      content_changed: item.contentChanged,
+      status: statusFor(item.kind, dryRun),
+      ...(item.findings ? { findings: item.findings } : {}),
+      ...(item.reason ? { reason: item.reason } : {}),
+    }));
+
+    emitSuccess({ isJson: options.isJson }, { dry_run: dryRun, skills }, () => {
+      if (skills.length === 0) {
+        console.log("update: nothing to do");
+        return;
+      }
+      for (const s of skills) {
+        console.log(`[${s.status}] ${s.skill_id}`);
+      }
+    });
+  } finally {
+    for (const item of plan) {
+      if (item.cloneDir) rmSync(item.cloneDir, { recursive: true, force: true });
+    }
+  }
+}

package/src/install.ts

@@ -1,6 +1,6 @@
-import { cpSync, existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { type ScanFinding, readTextFileOrNull, scanContent } from "./scan";
 import { decodeUtf8Strict, listSupportingFiles, parseSkillMd } from "./vault";
 
@@ -12,10 +12,21 @@ export interface RepoSource {
 const GIT_URL_PREFIXES = ["http://", "https://", "git://", "ssh://", "file://"];
 const SCP_LIKE_URL_PATTERN = /^[^/\s]+@[^/\s]+:/;
 
-function isGitUrl(repo: string): boolean {
+export function isGitUrl(repo: string): boolean {
   return GIT_URL_PREFIXES.some((prefix) => repo.startsWith(prefix)) || SCP_LIKE_URL_PATTERN.test(repo);
 }
 
+/** A `file://` source_url reaches the local filesystem directly, not just a network
+ *  remote. That's fine when the user typed it themselves at `skillmux install` time,
+ *  but a `.skillmux-origin` sidecar is vault content — readable and writable by
+ *  whatever populated the vault (a shared git-backed vault pulled in, or a hand-edit),
+ *  same threat model as every other vault-content read this codebase guards. `skillmux
+ *  outdated`/`update` must not blindly git-clone/ls-remote whatever local path a
+ *  forged sidecar names. */
+export function isLocalFileUrl(url: string): boolean {
+  return url.startsWith("file://");
+}
+
 export function resolveRepoSource(repo: string): RepoSource {
   if (isGitUrl(repo)) return { url: repo };
 
@@ -49,11 +60,70 @@ export async function cloneToTemp(url: string): Promise<string> {
   return dir;
 }
 
+export function resolveCloneCommit(cloneDir: string): string {
+  const proc = Bun.spawnSync(["git", "-C", cloneDir, "rev-parse", "HEAD"], { stdout: "pipe", stderr: "pipe" });
+  if (proc.exitCode !== 0) {
+    throw new Error(`git rev-parse HEAD failed in ${cloneDir}: ${proc.stderr.toString().trim()}`);
+  }
+  return proc.stdout.toString().trim();
+}
+
+export async function remoteHeadCommit(url: string, ref = "HEAD"): Promise<string> {
+  const proc = Bun.spawn(["git", "ls-remote", url, ref], { stdout: "pipe", stderr: "pipe" });
+  const exitCode = await proc.exited;
+  const stdout = await new Response(proc.stdout).text();
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`git ls-remote failed for ${url}: ${stderr.trim()}`);
+  }
+  const line = stdout.split("\n").find((l) => l.trim().length > 0);
+  if (!line) throw new Error(`git ls-remote returned no ref "${ref}" for ${url}`);
+  const sha = line.split("\t")[0]?.trim();
+  if (!sha || !/^[0-9a-f]{40}$/.test(sha)) {
+    throw new Error(`git ls-remote returned an unparseable SHA for ${url}: ${line}`);
+  }
+  return sha;
+}
+
+/** Recursively finds symlinks under `dir` (skipping `.git`), without following them.
+ *  A skill's content must be regular files only — a symlink here is how a malicious
+ *  skill smuggles an escape out of the vault once `skillmux sync` exposes it inside
+ *  an agent's native skill directory. `dir` itself is checked too: a `skill_path`
+ *  can point straight at a directory that git committed *as a symlink* (git supports
+ *  storing symlink blobs) — walking its descendants alone would silently resolve
+ *  through it and report the target's real files as clean. */
+export function findSymlinks(dir: string): string[] {
+  const found: string[] = [];
+  if (lstatSync(dir).isSymbolicLink()) {
+    return ["(the skill directory itself is a symlink)"];
+  }
+  const walk = (current: string) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === ".git") continue;
+      const abs = join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        found.push(relative(dir, abs));
+      } else if (entry.isDirectory()) {
+        walk(abs);
+      }
+    }
+  };
+  walk(dir);
+  return found.sort();
+}
+
 export interface ValidationResult {
   findings: ScanFinding[];
 }
 
 export async function validateSkillCandidate(skillId: string, dir: string): Promise<ValidationResult> {
+  const symlinks = findSymlinks(dir);
+  if (symlinks.length > 0) {
+    throw new Error(
+      `"${skillId}" contains symlink(s), which are not allowed in skill content: ${symlinks.join(", ")}`,
+    );
+  }
+
   const bytes = await Bun.file(join(dir, "SKILL.md")).bytes();
   const body = decodeUtf8Strict(bytes);
   parseSkillMd(skillId, body);
@@ -78,6 +148,12 @@ export async function validateSkillCandidate(skillId: string, dir: string): Prom
 }
 
 export function installIntoVault(vaultPath: string, skillId: string, sourceDir: string, force = false): string {
+  const symlinks = findSymlinks(sourceDir);
+  if (symlinks.length > 0) {
+    throw new Error(
+      `refusing to install "${skillId}": source contains symlink(s), which are not allowed in skill content: ${symlinks.join(", ")}`,
+    );
+  }
   const targetDir = join(vaultPath, skillId);
   if (existsSync(targetDir)) {
     if (!force) {
@@ -96,6 +172,9 @@ export interface ResolvedSkillDir {
 
 export function resolveSkillDir(cloneDir: string, fallbackName: string, skillPath?: string): ResolvedSkillDir {
   if (skillPath) {
+    if (skillPath.startsWith("/") || skillPath.split("/").includes("..")) {
+      throw new Error(`invalid skill_path "${skillPath}": must be a relative path within the repo`);
+    }
     return { skillId: basename(skillPath), dir: join(cloneDir, skillPath) };
   }
   if (existsSync(join(cloneDir, "SKILL.md"))) {

package/src/provenance.ts

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isGitUrl } from "./install";
+import { SKILLMUX_ORIGIN_FILENAME, listSupportingFiles } from "./vault";
+
+export { SKILLMUX_ORIGIN_FILENAME };
+
+export interface SkillOrigin {
+  schema_version: 1;
+  source_url: string;
+  skill_path?: string;
+  commit: string;
+  installed_at: string;
+  content_hash: string;
+}
+
+function validateOrigin(origin: SkillOrigin, path: string): SkillOrigin {
+  if (origin.schema_version !== 1) throw new Error(`${path}: unsupported .skillmux-origin schema_version`);
+  if (typeof origin.source_url !== "string" || origin.source_url.length === 0) {
+    throw new Error(`${path}: .skillmux-origin is missing source_url`);
+  }
+  if (!isGitUrl(origin.source_url)) {
+    throw new Error(`${path}: .skillmux-origin has a source_url that is not a recognized git protocol`);
+  }
+  if (typeof origin.commit !== "string" || !/^[0-9a-f]{40}$/.test(origin.commit)) {
+    throw new Error(`${path}: .skillmux-origin has an invalid commit`);
+  }
+  if (typeof origin.installed_at !== "string") throw new Error(`${path}: .skillmux-origin is missing installed_at`);
+  if (typeof origin.content_hash !== "string" || !/^[a-f0-9]{64}$/.test(origin.content_hash)) {
+    throw new Error(`${path}: .skillmux-origin has an invalid content_hash`);
+  }
+  return origin;
+}
+
+/** Same defense-in-depth as readSkill/hashSkillContent: a tampered vault entry
+ *  (shared git-backed vault pulled in, or a hand-edit) could symlink the sidecar
+ *  itself to an arbitrary host file — refuse to follow it rather than feeding
+ *  that file's bytes into JSON.parse and, on a schema-shaped coincidence, into
+ *  the git commands `outdated`/`update` run against `source_url`. */
+export function readSkillOrigin(dir: string): SkillOrigin | null {
+  // The skill directory itself must be checked separately from the sidecar's own
+  // leaf check below: `lstat` only refuses to follow the *final* path component,
+  // so a symlinked skill directory containing a real, non-symlink sidecar at its
+  // target would otherwise resolve straight through to arbitrary host content.
+  if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) {
+    throw new Error(`${dir}: refusing to read .skillmux-origin — the skill directory is a symlink`);
+  }
+  const path = join(dir, SKILLMUX_ORIGIN_FILENAME);
+  if (!existsSync(path)) return null;
+  if (lstatSync(path).isSymbolicLink()) {
+    throw new Error(`${path}: refusing to read .skillmux-origin — it is a symlink`);
+  }
+  return validateOrigin(JSON.parse(readFileSync(path, "utf-8")), path);
+}
+
+export function writeSkillOrigin(
+  dir: string,
+  params: {
+    source_url: string;
+    skill_path?: string;
+    commit: string;
+    installed_at: string;
+    content_hash: string;
+  },
+): void {
+  const origin: SkillOrigin = { schema_version: 1, ...params };
+  writeFileSync(join(dir, SKILLMUX_ORIGIN_FILENAME), JSON.stringify(origin, null, 2));
+}
+
+/** Deterministic sha256 over every file in a skill directory (SKILL.md plus every
+ *  file listSupportingFiles returns), used for local-drift detection. listSupportingFiles
+ *  already excludes symlinks it finds, but SKILL.md is read separately (same reason
+ *  readSkill/deliverSkill guard it independently in vault.ts/router-core.ts) — this is
+ *  a local, already-installed vault dir, not the freshly cloned candidate that
+ *  validateSkillCandidate has vetted, so a swapped-in symlinked SKILL.md must be
+ *  refused here rather than followed. `dir` itself is checked too: every per-file
+ *  lstat below only refuses to follow a symlinked *leaf*, so a symlinked `dir`
+ *  containing real (non-symlink) files at its target would otherwise resolve
+ *  straight through to arbitrary host content. */
+export function hashSkillContent(dir: string): string {
+  const vaultPath = dirname(dir);
+  const skillId = basename(dir);
+  if (lstatSync(dir).isSymbolicLink()) {
+    throw new Error(`refusing to hash ${skillId}: the skill directory is a symlink`);
+  }
+  const hasher = new Bun.CryptoHasher("sha256");
+  const files = ["SKILL.md", ...listSupportingFiles(vaultPath, skillId)];
+  for (const rel of files) {
+    const path = join(dir, rel);
+    if (lstatSync(path).isSymbolicLink()) {
+      throw new Error(`refusing to hash ${skillId}/${rel}: it is a symlink`);
+    }
+    hasher.update(rel);
+    hasher.update("\0");
+    hasher.update(readFileSync(path));
+    hasher.update("\0");
+  }
+  return hasher.digest("hex");
+}

package/src/router-core.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { existsSync, watch } from "node:fs";
+import { existsSync, lstatSync, watch } from "node:fs";
 import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
@@ -161,8 +161,20 @@ async function deliverSkill(db: Database, config: Config, skillId: string): Prom
   let raw = "";
   for (let i = 0; i < candidates.length; i++) {
     const candidate = candidates[i]!;
-    const file = Bun.file(join(candidate, skillId, "SKILL.md"));
+    const skillDir = join(candidate, skillId);
+    const path = join(skillDir, "SKILL.md");
+    const file = Bun.file(path);
     if (!(await file.exists())) continue;
+    // A symlinked SKILL.md must never be read here: this is the direct "zero-loss
+    // delivery" read path that bypasses the index and readSkill's own symlink guard
+    // (vault.ts), and its `body` is served straight into the agent's context.
+    //
+    // The skill directory itself must be checked too, separately from SKILL.md's
+    // leaf check above: `lstat` only refuses to follow the *final* path component,
+    // so a symlinked skill directory (e.g. a tampered local_vault_paths override)
+    // containing a real, non-symlink SKILL.md at its target silently passes the
+    // leaf check while still resolving straight through to arbitrary host content.
+    if (lstatSync(skillDir).isSymbolicLink() || lstatSync(path).isSymbolicLink()) continue;
     const candidateBytes = await file.bytes();
     const candidateRaw = decodeUtf8Strict(candidateBytes);
     if (i < candidates.length - 1) {

package/src/scan.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { decodeUtf8Strict, listSupportingFiles, scanVault } from "./vault";
 
@@ -162,8 +162,14 @@ interface ScanContentTarget {
   content: string;
 }
 
+/** Refuses (returns null for) a symlinked path instead of following it — every
+ *  caller feeds vault content into scan findings, so a symlink swapped in after
+ *  an earlier symlink-filtering pass (e.g. listSupportingFiles' walk, which runs
+ *  before this read, not at it) must still be caught right here, not trusted to
+ *  have stayed excluded. Same defense-in-depth pattern as readSkill/hashSkillContent. */
 export async function readTextFileOrNull(path: string): Promise<string | null> {
   try {
+    if (lstatSync(path).isSymbolicLink()) return null;
     const bytes = await Bun.file(path).bytes();
     return decodeUtf8Strict(bytes);
   } catch {

package/src/sync.ts

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
+import { findSymlinks } from "./install";
 import { resolveSkillRoot } from "./vault";
 
 export const SKILLMUX_MARKER_FILENAME = ".skillmux";
@@ -101,25 +102,47 @@ export interface SyncTargetParams {
 export interface SyncTargetResult {
   added: string[];
   removed: string[];
+  /** Core skills whose directory contains an internal symlink and were refused —
+   *  syncTarget symlinks the whole skill directory into the target, so an internal
+   *  symlink would otherwise be exposed to the agent regardless of how it got into
+   *  the vault (install/update already reject them, but a shared git-backed vault
+   *  can still be tampered with directly). */
+  skipped: string[];
 }
 
 export interface SyncTargetOptions {
   dryRun?: boolean;
 }
 
+/** Splits `skillIds` into those safe to symlink into a target and those refused
+ *  for containing an internal symlink (see SyncTargetResult.skipped). */
+function partitionSyncable(
+  skillIds: string[],
+  skillSource: (skillId: string) => string,
+): { syncable: string[]; skipped: string[] } {
+  const syncable: string[] = [];
+  const skipped: string[] = [];
+  for (const skillId of skillIds) {
+    if (findSymlinks(join(skillSource(skillId), skillId)).length > 0) skipped.push(skillId);
+    else syncable.push(skillId);
+  }
+  return { syncable, skipped };
+}
+
 export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions = {}): SyncTargetResult {
   const { vaultPath, targetDir, targetName, coreSkillIds, localVaultPaths = [] } = params;
   const { dryRun = false } = options;
   const skillSource = (skillId: string) => resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
 
   if (!existsSync(targetDir)) {
-    if (dryRun) return { added: [...coreSkillIds], removed: [] };
+    const { syncable, skipped } = partitionSyncable(coreSkillIds, skillSource);
+    if (dryRun) return { added: syncable, removed: [], skipped };
     mkdirSync(targetDir, { recursive: true });
-    for (const skillId of coreSkillIds) {
+    for (const skillId of syncable) {
       symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
     }
-    writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds);
-    return { added: [...coreSkillIds], removed: [] };
+    writeTargetMarker(targetDir, targetName, vaultPath, syncable);
+    return { added: syncable, removed: [], skipped };
   }
 
   let marker = readSkillmuxMarker(targetDir);
@@ -167,14 +190,21 @@ export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions
   }
 
   const removed = [...managedEntries].filter((name) => existing.includes(name) && !desired.has(name));
-  const added = coreSkillIds.filter((skillId) => !existing.includes(skillId));
-  if (dryRun) return { added, removed };
+  const addedCandidates = coreSkillIds.filter((skillId) => !existing.includes(skillId));
+  const { syncable: added, skipped } = partitionSyncable(addedCandidates, skillSource);
+  if (dryRun) return { added, removed, skipped };
 
   for (const name of removed) unlinkSync(join(targetDir, name));
   for (const skillId of added) symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
-  writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds, marker.created_at);
+  writeTargetMarker(
+    targetDir,
+    targetName,
+    vaultPath,
+    coreSkillIds.filter((skillId) => !skipped.includes(skillId)),
+    marker.created_at,
+  );
 
-  return { added, removed };
+  return { added, removed, skipped };
 }
 
 export interface AdoptTargetResult {

package/src/vault.ts

@@ -1,8 +1,12 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
 export const SKILL_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,127}$/;
 
+/** Provenance sidecar filename (see provenance.ts). Kept here, not re-imported from
+ *  provenance.ts, so listSupportingFiles can exclude it without a circular import. */
+export const SKILLMUX_ORIGIN_FILENAME = ".skillmux-origin";
+
 export interface VaultSkill {
   skill_id: string;
   title: string;
@@ -45,8 +49,26 @@ export function decodeUtf8Strict(bytes: Uint8Array): string {
   return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
 }
 
+/** SKILL.md itself is read directly (not via listSupportingFiles, which excludes
+ *  it by name) — so its own symlink-ness must be checked here. Without this, a
+ *  symlinked SKILL.md reachable via a shared git-backed vault or a hand-edit would
+ *  have its target's content indexed and delivered to agents as the skill body.
+ *
+ *  The skill directory itself must be checked too, separately from SKILL.md's own
+ *  leaf check: `lstat` only refuses to follow the *final* path component, so a
+ *  symlinked skill directory containing a real (non-symlink) SKILL.md file at its
+ *  target silently passes the leaf check while still resolving straight through
+ *  to arbitrary host content. */
 export async function readSkill(vaultPath: string, skillId: string): Promise<VaultSkill> {
-  const bytes = await Bun.file(join(vaultPath, skillId, "SKILL.md")).bytes();
+  const skillDir = join(vaultPath, skillId);
+  if (lstatSync(skillDir).isSymbolicLink()) {
+    throw new Error(`refusing to read ${skillId}: the skill directory is a symlink`);
+  }
+  const path = join(skillDir, "SKILL.md");
+  if (lstatSync(path).isSymbolicLink()) {
+    throw new Error(`refusing to read ${skillId}/SKILL.md: it is a symlink`);
+  }
+  const bytes = await Bun.file(path).bytes();
   return parseSkillMd(skillId, decodeUtf8Strict(bytes));
 }
 
@@ -124,17 +146,35 @@ export function findShadowedSkills(vaultPath: string, localVaultPaths: string[])
   return shadowed.sort((a, b) => a.skill_id.localeCompare(b.skill_id));
 }
 
-/** Relative paths of everything under the skill dir except SKILL.md itself, sorted. */
+/** Relative paths of everything under the skill dir except SKILL.md and the
+ *  provenance sidecar, sorted. Symlinks are excluded rather than followed —
+ *  install/sync already refuse a skill containing one, but a symlink can still
+ *  reach the vault directly (a shared git-backed vault pulled in, or a hand-edit),
+ *  and this function otherwise feeds skill content straight into content
+ *  scanning (scan.ts) and drift hashing (provenance.ts). `skillId` must be a
+ *  single path segment — not the stricter SKILL_ID_PATTERN, since scanPath's
+ *  ad-hoc single-directory mode legitimately passes an arbitrary, not-yet-
+ *  normalized directory name — so `..`/`.`/a path separator is rejected to
+ *  keep the walk inside `vaultPath` without breaking that mode. */
 export function listSupportingFiles(vaultPath: string, skillId: string): string[] {
+  if (skillId === "" || skillId === "." || skillId === ".." || skillId.includes("/") || skillId.includes("\\")) {
+    return [];
+  }
   const root = join(vaultPath, skillId);
+  // A symlinked skill directory must not be walked into: readdirSync follows a
+  // symlinked path argument (unlike the entry.isSymbolicLink() check below, which
+  // only applies to entries *found by* the walk), so without this a symlinked
+  // `root` would return the target directory's file listing straight through.
+  if (!existsSync(root) || lstatSync(root).isSymbolicLink()) return [];
   const files: string[] = [];
   const walk = (dir: string) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
       const abs = join(dir, entry.name);
       if (entry.isDirectory()) walk(abs);
       else if (statSync(abs).isFile()) {
         const rel = relative(root, abs);
-        if (rel !== "SKILL.md") files.push(rel);
+        if (rel !== "SKILL.md" && rel !== SKILLMUX_ORIGIN_FILENAME) files.push(rel);
       }
     }
   };