diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 69221d5fd1..c39a70a910 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -61,6 +61,7 @@ jobs:
               - ".github/workflows/ci.yml"
             skills:
               - "skills/**"
+              - "skills-manifest.json"
               - "package.json"
               - ".github/workflows/ci.yml"
 
@@ -263,6 +264,23 @@ jobs:
           printf '  * %s\n' "${SKILLS_TESTS[@]}"
           node --test "${SKILLS_TESTS[@]}"
 
+  # Guards that skills-manifest.json (the published freshness fingerprint read
+  # by `hyperframes skills check`) was regenerated when a skill changed. Runs
+  # `gen:skills-manifest --check`, which compares per-skill content hashes; the
+  # manifest carries no version/timestamp, so it only fails on real content
+  # drift. bun runs the TS script directly, no install needed.
+  skills-manifest:
+    name: "Skills: manifest in sync"
+    needs: changes
+    if: needs.changes.outputs.skills == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      - name: Verify skills-manifest.json matches skills/
+        run: bun packages/cli/scripts/gen-skills-manifest.ts --check
+
   cli-npx-shim:
     name: "CLI: npx shim (${{ matrix.os }})"
     needs: changes
diff --git a/lefthook.yml b/lefthook.yml
index bf5a08090e..44e676c7ee 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -10,6 +10,13 @@ pre-commit:
       # Replaces --check which only reports — that left unformatted files in
       # commits when the hook ran after the amend snapshot was taken.
       run: bunx oxfmt --no-error-on-unmatched-pattern {staged_files} && git add {staged_files}
+    skills-manifest:
+      glob: "skills/**"
+      # Regenerate the freshness fingerprint when a skill changes, then re-stage
+      # it so skills-manifest.json (repo root) never drifts from skills/ (CI
+      # enforces the same via the "Skills: manifest in sync" job). Churn-free:
+      # the generator rewrites only when a content hash actually changed.
+      run: bun packages/cli/scripts/gen-skills-manifest.ts && git add skills-manifest.json
     typecheck:
       glob: "*.{ts,tsx}"
       run: cd packages/core && bunx tsc --noEmit && cd ../studio && bunx tsc --noEmit
diff --git a/packages/cli/package.json b/packages/cli/package.json
index ccc01b0aa5..79cbafc4fd 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -22,7 +22,8 @@
     "build:runtime": "tsx scripts/build-runtime.ts",
     "build:beat-analyzer": "node scripts/build-beat-analyzer.mjs",
     "build:copy": "node scripts/build-copy.mjs",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "gen:skills-manifest": "tsx scripts/gen-skills-manifest.ts"
   },
   "dependencies": {
     "@hono/node-server": "^1.8.0",
diff --git a/packages/cli/scripts/gen-skills-manifest.ts b/packages/cli/scripts/gen-skills-manifest.ts
new file mode 100644
index 0000000000..2a508e3c7b
--- /dev/null
+++ b/packages/cli/scripts/gen-skills-manifest.ts
@@ -0,0 +1,86 @@
+// Generate (or verify) skills-manifest.json (repo root) — the published
+// "latest" fingerprint of the HyperFrames skill bundle.
+//
+//   bun run --cwd packages/cli gen:skills-manifest          # write/update
+//   bun run --cwd packages/cli gen:skills-manifest --check  # verify only (CI)
+//
+// The manifest is just per-skill content hashes (no version / timestamp), so it
+// is fully deterministic: same skill content ⇒ byte-identical manifest. `--check`
+// exits non-zero when the committed manifest doesn't match current skill content.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildManifest, MANIFEST_FILE, type SkillsManifest } from "../src/utils/skillsManifest.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(here, "..", "..", ".."); // packages/cli/scripts → repo root
+const skillsRoot = join(repoRoot, "skills");
+const outPath = join(repoRoot, MANIFEST_FILE);
+const isCheck = process.argv.includes("--check");
+
+/** Stable signature of the content hashes (order-independent). */
+function signature(skills: SkillsManifest["skills"]): string {
+  return Object.keys(skills)
+    .sort()
+    .map((name) => `${name}:${skills[name]!.hash}`)
+    .join("\n");
+}
+
+function driftLine(name: string, oldHash?: string, newHash?: string): string | null {
+  if (oldHash === newHash) return null;
+  if (!oldHash) return `  + ${name} (new)`;
+  if (!newHash) return `  - ${name} (removed)`;
+  return `  ~ ${name} (${oldHash} → ${newHash})`;
+}
+
+function hashOf(skills: SkillsManifest["skills"], name: string): string | undefined {
+  return skills[name]?.hash;
+}
+
+function reportDrift(fresh: SkillsManifest, committed: SkillsManifest | null): void {
+  const oldSkills = committed === null ? {} : committed.skills;
+  const names = [...new Set([...Object.keys(fresh.skills), ...Object.keys(oldSkills)])].sort();
+  for (const name of names) {
+    const line = driftLine(name, hashOf(oldSkills, name), hashOf(fresh.skills, name));
+    if (line) console.log(line);
+  }
+}
+
+const fresh = buildManifest(skillsRoot, { source: "heygen-com/hyperframes" });
+
+// Read the committed manifest directly (no existsSync precheck) so there's no
+// check-then-write race on outPath — a missing or unreadable file just means
+// "no committed manifest yet", and we write a fresh one below.
+let committed: SkillsManifest | null = null;
+try {
+  committed = JSON.parse(readFileSync(outPath, "utf8")) as SkillsManifest;
+} catch {
+  committed = null;
+}
+
+const inSync = committed !== null && signature(committed.skills) === signature(fresh.skills);
+const count = Object.keys(fresh.skills).length;
+
+if (isCheck) {
+  if (inSync) {
+    console.log(`✓ ${MANIFEST_FILE} is in sync (${count} skills)`);
+    process.exit(0);
+  }
+  console.error(`✗ ${MANIFEST_FILE} is out of date — a skill changed without regenerating it.`);
+  reportDrift(fresh, committed);
+  console.error(
+    `\nRun: bun run --cwd packages/cli gen:skills-manifest  (then commit ${MANIFEST_FILE})`,
+  );
+  process.exit(1);
+}
+
+// Write mode — churn-free: only rewrite when a content hash actually changed.
+if (inSync) {
+  console.log(`${MANIFEST_FILE} already in sync — no change (${count} skills)`);
+  process.exit(0);
+}
+
+writeFileSync(outPath, JSON.stringify(fresh, null, 2) + "\n");
+console.log(`Wrote ${outPath} (${count} skills)`);
+reportDrift(fresh, committed);
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 6de445aa02..2316977ec4 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -194,6 +194,7 @@ let _trackCommandResult:
   | ((props: { command: string; success: boolean; exitCode: number; durationMs: number }) => void)
   | undefined;
 let _printUpdateNotice: (() => void) | undefined;
+let _printSkillsUpdateNotice: (() => void) | undefined;
 
 // `events` is a telemetry-internal beacon: it self-tracks + self-flushes, so it
 // skips the per-command wrapper (no duplicate cli_command, no first-run notice
@@ -226,6 +227,13 @@ if (!isHelp && !hasJsonFlag && command !== "upgrade" && command !== "events") {
       auto?.scheduleBackgroundInstall(result.latest, result.current);
     }
   });
+
+  // Skills freshness nudge — same gating as the CLI self-update notice. The
+  // check is cached (24h) and best-effort: it never blocks or fails the command.
+  import("./utils/skillsUpdateCheck.js").then(async (mod) => {
+    _printSkillsUpdateNotice = mod.printSkillsUpdateNotice;
+    await mod.checkSkillsForUpdate().catch(() => null);
+  });
 }
 
 const commandStart = Date.now();
@@ -237,7 +245,10 @@ const commandStart = Date.now();
 // detaches after first invocation, which is what we want for both.
 process.once("beforeExit", () => {
   _flush?.().catch(() => {});
-  if (!hasJsonFlag) _printUpdateNotice?.();
+  if (!hasJsonFlag) {
+    _printUpdateNotice?.();
+    _printSkillsUpdateNotice?.();
+  }
 });
 
 // Sync-only: exit handlers cannot await promises or drain microtasks.
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index 02b0dc3bd5..90814d4612 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -573,6 +573,41 @@ async function scaffoldProject(
   }
 }
 
+/**
+ * Ensure the project's AI coding skills are present and current. Checks the
+ * installed skills against the latest published on GitHub and only (re)installs
+ * when something is outdated or missing — so re-running `init` on an already
+ * up-to-date project is a no-op. Best-effort: if the version check can't reach
+ * GitHub, it installs anyway. The install itself (`installAllSkills`) pulls the
+ * full set straight from the GitHub repo.
+ */
+async function ensureSkillsCurrent(destDir: string): Promise<void> {
+  const { installAllSkills } = await import("./skills.js");
+  const { checkSkills } = await import("../utils/skillsManifest.js");
+  // --all pulls every skill (incl. ones not yet installed); --yes keeps it
+  // non-interactive. When Claude Code is driving, target its native dir so
+  // skills land in .claude/skills/.
+  const extraArgs = process.env["CLAUDECODE"]
+    ? ["--all", "--agent", "claude-code", "--yes"]
+    : ["--all", "--yes"];
+
+  console.log();
+  console.log(c.bold("Checking AI coding skills against GitHub..."));
+  let needsInstall = true;
+  try {
+    const result = await checkSkills({ cwd: destDir });
+    needsInstall = result.updateAvailable;
+  } catch {
+    // Couldn't reach GitHub (offline, rate-limited) — install anyway.
+  }
+
+  if (needsInstall) {
+    await installAllSkills({ cwd: destDir, extraArgs });
+  } else {
+    console.log(c.success("AI coding skills are already up to date."));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Exported command
 // ---------------------------------------------------------------------------
@@ -802,12 +837,7 @@ export default defineCommand({
       }
 
       if (!skipSkills) {
-        const { installAllSkills } = await import("./skills.js");
-        // --yes keeps it non-interactive. When Claude Code is driving
-        // (CLAUDECODE env var), target its native dir so skills land in
-        // .claude/skills/ instead of only .agents/skills/.
-        const args = process.env["CLAUDECODE"] ? ["--agent", "claude-code", "--yes"] : ["--yes"];
-        await installAllSkills({ cwd: destDir, extraArgs: args });
+        await ensureSkillsCurrent(destDir);
       }
 
       console.log();
@@ -815,7 +845,7 @@ export default defineCommand({
       console.log();
       if (skipSkills) {
         console.log(`  ${c.accent("1.")} Install AI coding skills (one-time):`);
-        console.log(`     ${c.accent("npx skills add heygen-com/hyperframes --yes")}`);
+        console.log(`     ${c.accent("npx hyperframes skills update")}`);
       } else {
         console.log(
           `  ${c.accent("1.")} Restart your AI agent (new session) so it loads the skills.`,
@@ -1023,20 +1053,10 @@ export default defineCommand({
     const files = readdirSync(destDir);
     clack.note(files.map((f) => c.accent(f)).join("\n"), c.success(`Created ${name}/`));
 
-    // Offer to install AI coding skills
+    // Check skills against GitHub and (re)install only if outdated or missing —
+    // init is the one place the full set is pulled. Opt out with --skip-skills.
     if (!skipSkills) {
-      const installSkills = await clack.confirm({
-        message: "Install AI coding skills? (for Claude Code, Cursor, Codex, etc.)",
-        initialValue: true,
-      });
-      if (clack.isCancel(installSkills)) {
-        clack.cancel("Setup cancelled.");
-        process.exit(0);
-      }
-      if (installSkills) {
-        const { installAllSkills } = await import("./skills.js");
-        await installAllSkills({ cwd: destDir });
-      }
+      await ensureSkillsCurrent(destDir);
     }
 
     // Auto-launch studio preview
diff --git a/packages/cli/src/commands/skills.test.ts b/packages/cli/src/commands/skills.test.ts
index 2c51c38f05..48ee0b3e0d 100644
--- a/packages/cli/src/commands/skills.test.ts
+++ b/packages/cli/src/commands/skills.test.ts
@@ -17,12 +17,17 @@ type ExecCall = {
 };
 
 const originalPlatform = process.platform;
-const state: { execCalls: ExecCall[]; spawnCalls: SpawnCall[] } = {
+const state: { execCalls: ExecCall[]; spawnCalls: SpawnCall[]; spawnExitCode: number } = {
   execCalls: [],
   spawnCalls: [],
+  spawnExitCode: 0,
 };
 
 vi.mock("node:child_process", () => ({
+  // `skillsManifest.ts` does `promisify(execFile)` at module load. These tests
+  // never invoke it (no skills-check path runs here), so a bare stub is enough
+  // to satisfy the named import — we deliberately don't spread the real module.
+  execFile: vi.fn(),
   execFileSync: vi.fn((command: string, args: ReadonlyArray<string>) => {
     state.execCalls.push({ command, args });
     return Buffer.from("11.0.0");
@@ -31,7 +36,7 @@ vi.mock("node:child_process", () => ({
     (command: string, args: ReadonlyArray<string>, opts?: { env?: NodeJS.ProcessEnv }) => {
       state.spawnCalls.push({ command, args, env: opts?.env });
       const fake = new EventEmitter();
-      setImmediate(() => fake.emit("close", 0, null));
+      setImmediate(() => fake.emit("close", state.spawnExitCode, null));
       return fake;
     },
   ),
@@ -54,6 +59,7 @@ describe("hyperframes skills", () => {
   beforeEach(() => {
     state.execCalls = [];
     state.spawnCalls = [];
+    state.spawnExitCode = 0;
     vi.resetModules();
   });
 
@@ -77,13 +83,32 @@ describe("hyperframes skills", () => {
   });
 
   it.each([
-    ["linux", "npx", ["--version"], ["skills", "add", "heygen-com/hyperframes", "--all"]],
-    ["darwin", "npx", ["--version"], ["skills", "add", "heygen-com/hyperframes", "--all"]],
+    [
+      "linux",
+      "npx",
+      ["--version"],
+      ["skills", "add", "https://github.com/heygen-com/hyperframes", "--all"],
+    ],
+    [
+      "darwin",
+      "npx",
+      ["--version"],
+      ["skills", "add", "https://github.com/heygen-com/hyperframes", "--all"],
+    ],
     [
       "win32",
       "cmd.exe",
       ["/d", "/s", "/c", "npx.cmd", "--version"],
-      ["/d", "/s", "/c", "npx.cmd", "skills", "add", "heygen-com/hyperframes", "--all"],
+      [
+        "/d",
+        "/s",
+        "/c",
+        "npx.cmd",
+        "skills",
+        "add",
+        "https://github.com/heygen-com/hyperframes",
+        "--all",
+      ],
     ],
   ] as const)(
     "uses %s-compatible npx command for preflight and skills install",
@@ -99,4 +124,46 @@ describe("hyperframes skills", () => {
       expect(state.spawnCalls[0]?.args).toEqual(expectedInstallArgs);
     },
   );
+
+  // The `skills check || skills update` recovery contract requires update to
+  // fail loudly — a swallowed install failure would let the `||` chain pass
+  // while nothing changed.
+  it("skills update exits non-zero when the install fails", async () => {
+    setPlatform("linux");
+    state.spawnExitCode = 1; // simulate `skills add` exiting non-zero
+
+    const prevExit = process.exitCode;
+    process.exitCode = 0;
+    try {
+      const { default: skillsCmd } = await import("./skills.js");
+      const subs = skillsCmd.subCommands as unknown as Record<string, typeof skillsCmd>;
+      const updateCmd = subs.update;
+      expect(updateCmd).toBeDefined();
+      await updateCmd!.run?.({ args: {}, rawArgs: [], cmd: updateCmd } as never);
+      expect(process.exitCode).toBe(1);
+    } finally {
+      process.exitCode = prevExit;
+    }
+  });
+
+  it("skills update exits zero on a successful install", async () => {
+    setPlatform("linux");
+    state.spawnExitCode = 0;
+
+    const prevExit = process.exitCode;
+    process.exitCode = 0;
+    try {
+      const { default: skillsCmd } = await import("./skills.js");
+      const subs = skillsCmd.subCommands as unknown as Record<string, typeof skillsCmd>;
+      const updateCmd = subs.update;
+      expect(updateCmd).toBeDefined();
+      await updateCmd!.run?.({ args: {}, rawArgs: [], cmd: updateCmd } as never);
+      expect(process.exitCode).toBe(0);
+      // pulls the full set straight from GitHub
+      expect(state.spawnCalls[0]?.args).toContain("https://github.com/heygen-com/hyperframes");
+      expect(state.spawnCalls[0]?.args).toContain("--all");
+    } finally {
+      process.exitCode = prevExit;
+    }
+  });
 });
diff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.ts
index 2894058c90..6a352ed516 100644
--- a/packages/cli/src/commands/skills.ts
+++ b/packages/cli/src/commands/skills.ts
@@ -3,6 +3,16 @@ import { execFileSync, spawn } from "node:child_process";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
 import { buildNpxCommand } from "../utils/npxCommand.js";
+import { withMeta } from "../utils/updateCheck.js";
+import { checkSkills, type SkillsCheckResult } from "../utils/skillsManifest.js";
+import type { Example } from "./_examples.js";
+
+export const examples: Example[] = [
+  ["Install all HyperFrames skills", "hyperframes skills"],
+  ["Check whether installed skills are up to date", "hyperframes skills check"],
+  ["Check, machine-readable (for agents / CI)", "hyperframes skills check --json"],
+  ["Update all skills to the latest (installs any missing)", "hyperframes skills update"],
+];
 
 function hasNpx(): boolean {
   const npx = buildNpxCommand(["--version"]);
@@ -14,41 +24,53 @@ function hasNpx(): boolean {
   }
 }
 
-function runSkillsAdd(
-  repo: string,
-  opts: { cwd?: string; extraArgs?: string[] } = {},
-): Promise<void> {
-  const npx = buildNpxCommand(["skills", "add", repo, ...(opts.extraArgs ?? ["--all"])]);
+function spawnNpx(args: string[], opts: { cwd?: string } = {}): Promise<void> {
+  const npx = buildNpxCommand(args);
   return new Promise((resolve, reject) => {
     const child = spawn(npx.command, npx.args, {
       stdio: "inherit",
       timeout: 120_000,
       cwd: opts.cwd,
       // GH #316 — the upstream `skills` CLI shells out to `git clone`.
-      // When Git's clone-hook protection is active (shipped on by
-      // default in 2.45.1, reverted in 2.45.2, still present on many
-      // corporate and CI setups), any globally-registered
-      // `git lfs install` post-checkout hook aborts the clone. The
-      // `repo` reaching this function is hardcoded in SOURCES below
-      // — no user input reaches the spawn — so opting out here is safe.
+      // When Git's clone-hook protection is active (shipped on by default in
+      // 2.45.1, reverted in 2.45.2, still present on many corporate and CI
+      // setups), a globally-registered `git lfs install` post-checkout hook
+      // aborts the clone. The args reaching this function are hardcoded — no
+      // user input reaches the spawn — so opting out here is safe.
       env: { ...process.env, GIT_CLONE_PROTECTION_ACTIVE: "0" },
     });
     child.on("close", (code, signal) => {
       if (code === 0) resolve();
       else if (signal === "SIGINT" || code === 130) process.exit(0);
-      else reject(new Error(`npx skills add exited with code ${code}`));
+      else reject(new Error(`npx ${args.join(" ")} exited with code ${code}`));
     });
     child.on("error", reject);
   });
 }
 
-const SOURCES = [{ name: "HyperFrames", repo: "heygen-com/hyperframes" }];
+function runSkillsAdd(
+  source: string,
+  opts: { cwd?: string; extraArgs?: string[] } = {},
+): Promise<void> {
+  return spawnNpx(["skills", "add", source, ...(opts.extraArgs ?? ["--all"])], opts);
+}
+
+// Use the full GitHub URL (not the `owner/repo` slug) so `skills add` git-clones
+// the repo directly at latest `main`, bypassing the skills.sh registry — which
+// can lag behind the repo. Our freshness check already resolves "latest"
+// straight from GitHub, so this keeps install/update consistent with check.
+const SOURCES = [{ name: "HyperFrames", url: "https://github.com/heygen-com/hyperframes" }];
 
 export async function installAllSkills(
-  opts: { cwd?: string; extraArgs?: string[] } = {},
+  opts: { cwd?: string; extraArgs?: string[]; strict?: boolean } = {},
 ): Promise<void> {
   if (!hasNpx()) {
-    clack.log.error(c.error("npx not found. Install Node.js and retry."));
+    const msg = "npx not found. Install Node.js and retry.";
+    // strict callers (e.g. `skills update`) need a real failure so a recovery
+    // command can't exit 0 having done nothing; best-effort callers (init) just
+    // warn and carry on.
+    if (opts.strict) throw new Error(msg);
+    clack.log.error(c.error(msg));
     return;
   }
 
@@ -57,20 +79,125 @@ export async function installAllSkills(
     console.log(c.bold(`Installing ${source.name} skills...`));
     console.log();
     try {
-      await runSkillsAdd(source.repo, opts);
-    } catch {
+      await runSkillsAdd(source.url, opts);
+    } catch (err) {
+      if (opts.strict) throw err instanceof Error ? err : new Error(String(err));
       console.log(c.dim(`${source.name} skills skipped`));
     }
   }
 }
 
+// ── check ────────────────────────────────────────────────────────────────────
+
+function renderCheck(result: SkillsCheckResult): void {
+  const { summary } = result;
+  console.log();
+  console.log(c.bold("hyperframes skills"));
+  console.log();
+
+  if (!result.location) {
+    console.log(`  ${c.dim("No HyperFrames skills found in the usual locations.")}`);
+    console.log(`  ${c.accent("Install: npx hyperframes skills")}`);
+    console.log();
+    return;
+  }
+
+  console.log(`  ${c.bold("Location")}  ${c.dim(result.location)} ${c.dim(`(${result.agent})`)}`);
+  console.log();
+
+  const parts = [c.success(`✓ ${summary.current} current`)];
+  if (summary.outdated) parts.push(c.warn(`↑ ${summary.outdated} outdated`));
+  if (summary.missing) parts.push(c.dim(`◦ ${summary.missing} not installed`));
+  console.log(`  ${parts.join("   ")}`);
+
+  const outdated = result.skills.filter((s) => s.status === "outdated");
+  const missing = result.skills.filter((s) => s.status === "missing");
+
+  if (outdated.length) {
+    console.log();
+    console.log(`  ${c.warn("Outdated:")}`);
+    for (const s of outdated) console.log(`    ${c.warn("↑")} ${s.name}`);
+  }
+  if (missing.length) {
+    console.log();
+    console.log(`  ${c.dim("Not installed:")}`);
+    for (const s of missing) console.log(`    ${c.dim("◦ " + s.name)}`);
+  }
+
+  console.log();
+  if (result.updateAvailable) {
+    console.log(`  ${c.accent("Update: npx hyperframes skills update")}`);
+  } else {
+    console.log(`  ${c.success("◇")}  ${c.success("Installed skills are up to date")}`);
+  }
+  console.log();
+}
+
+const checkCommand = defineCommand({
+  meta: { name: "check", description: "Check whether installed skills are the latest version" },
+  args: {
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    dir: { type: "string", description: "Skills directory to check (default: auto-detect)" },
+    source: {
+      type: "string",
+      description: "Where 'latest' comes from: local path, owner/repo, or URL",
+    },
+  },
+  async run({ args }) {
+    const result = await checkSkills({
+      dir: args.dir as string | undefined,
+      source: args.source as string | undefined,
+    });
+
+    if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
+    else renderCheck(result);
+
+    // Exit non-zero when installed skills are stale, so agents and CI can gate:
+    //   hyperframes skills check || npx hyperframes skills update
+    if (result.updateAvailable) process.exitCode = 1;
+  },
+});
+
+// ── update ───────────────────────────────────────────────────────────────────
+
+const updateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: "Update all HyperFrames skills to the latest — installs any not yet present",
+  },
+  args: {},
+  async run() {
+    // `skills add --all` re-fetches every skill to the latest AND installs ones
+    // not yet present — so "update" pulls the full set, not just what is already
+    // installed. This is where `init` and the stale-skills nudge both lead.
+    //
+    // strict: this is the documented recovery path for the agent/CI contract
+    // `hyperframes skills check || hyperframes skills update`. If the install
+    // fails (no npx, `skills add` exits non-zero) it must exit non-zero too —
+    // otherwise the `||` chain passes while nothing actually changed.
+    try {
+      await installAllSkills({ extraArgs: ["--all", "--yes"], strict: true });
+    } catch (err) {
+      clack.log.error(c.error(`Update failed: ${(err as Error).message}`));
+      process.exitCode = 1;
+    }
+  },
+});
+
 export default defineCommand({
   meta: {
     name: "skills",
-    description: "Install HyperFrames skills for AI coding tools",
+    description: "Install, check, and update HyperFrames skills for AI coding tools",
+  },
+  subCommands: {
+    check: checkCommand,
+    update: updateCommand,
   },
   args: {},
-  async run() {
-    await installAllSkills();
+  async run({ args }) {
+    // citty runs this parent handler even when a subcommand matches; guard on
+    // the positional so bare `hyperframes skills` installs, while
+    // `hyperframes skills check|update` does not also re-install.
+    if (!args._?.[0]) await installAllSkills();
   },
 });
diff --git a/packages/cli/src/telemetry/config.ts b/packages/cli/src/telemetry/config.ts
index b0a90cb9e7..0a6d3461c0 100644
--- a/packages/cli/src/telemetry/config.ts
+++ b/packages/cli/src/telemetry/config.ts
@@ -55,6 +55,14 @@ export interface HyperframesConfig {
     /** True after the result has been surfaced once to the user. */
     reported?: boolean;
   };
+  /** ISO timestamp of the last `skills check` freshness check (24h cache). */
+  lastSkillsCheck?: string;
+  /** Whether installed skills were stale at the last check. */
+  skillsUpdateAvailable?: boolean;
+  /** How many installed skills were outdated at the last check. */
+  skillsOutdatedCount?: number;
+  /** How many skills were missing (not installed) at the last check. */
+  skillsMissingCount?: number;
 }
 
 const DEFAULT_CONFIG: HyperframesConfig = {
@@ -96,6 +104,10 @@ export function readConfig(): HyperframesConfig {
       latestVersion: parsed.latestVersion,
       pendingUpdate: parsed.pendingUpdate,
       completedUpdate: parsed.completedUpdate,
+      lastSkillsCheck: parsed.lastSkillsCheck,
+      skillsUpdateAvailable: parsed.skillsUpdateAvailable,
+      skillsOutdatedCount: parsed.skillsOutdatedCount,
+      skillsMissingCount: parsed.skillsMissingCount,
     };
 
     cachedConfig = config;
diff --git a/packages/cli/src/utils/npxCommand.test.ts b/packages/cli/src/utils/npxCommand.test.ts
index 038e9b0d94..35b43d5879 100644
--- a/packages/cli/src/utils/npxCommand.test.ts
+++ b/packages/cli/src/utils/npxCommand.test.ts
@@ -14,13 +14,16 @@ describe("buildNpxCommand", () => {
     });
   });
 
+  // Real npx cold-start on Windows CI routinely exceeds vitest's 5s default,
+  // making this smoke test flaky. Give it generous headroom (it still asserts
+  // a real version string, so it isn't reduced to a tautology by mocking).
   it("executes the host npx version check through the resolved command", () => {
     const npx = buildNpxCommand(["--version"]);
     const version = execFileSync(npx.command, npx.args, {
       encoding: "utf8",
-      timeout: 10_000,
+      timeout: 30_000,
     }).trim();
 
     expect(version).toMatch(/^\d+\.\d+\.\d+/);
-  });
+  }, 60_000);
 });
diff --git a/packages/cli/src/utils/skillsManifest.test.ts b/packages/cli/src/utils/skillsManifest.test.ts
new file mode 100644
index 0000000000..fc1386c272
--- /dev/null
+++ b/packages/cli/src/utils/skillsManifest.test.ts
@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  hashSkillBundle,
+  buildManifest,
+  checkSkills,
+  diffSkills,
+  type SkillsManifest,
+  type SkillEntry,
+} from "./skillsManifest.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "skills-manifest-"));
+});
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function writeSkill(name: string, files: Record<string, string>): string {
+  const dir = join(root, name);
+  for (const [rel, content] of Object.entries(files)) {
+    const p = join(dir, rel);
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, content);
+  }
+  return dir;
+}
+
+describe("hashSkillBundle", () => {
+  it("is deterministic for identical content", () => {
+    const a = writeSkill("a", { "SKILL.md": "hello", "references/x.md": "x" });
+    const b = writeSkill("b", { "SKILL.md": "hello", "references/x.md": "x" });
+    expect(hashSkillBundle(a).hash).toBe(hashSkillBundle(b).hash);
+  });
+
+  it("changes when any file's content changes", () => {
+    const dir = writeSkill("a", { "SKILL.md": "hello", "references/x.md": "x" });
+    const before = hashSkillBundle(dir).hash;
+    writeFileSync(join(dir, "references/x.md"), "CHANGED");
+    expect(hashSkillBundle(dir).hash).not.toBe(before);
+  });
+
+  it("counts every file in the bundle, not just SKILL.md", () => {
+    const dir = writeSkill("a", {
+      "SKILL.md": "hello",
+      "references/x.md": "x",
+      "scripts/y.mjs": "export const y = 1;",
+    });
+    expect(hashSkillBundle(dir).files).toBe(3);
+  });
+
+  it("normalises CRLF so a Windows checkout is not flagged as different", () => {
+    const lf = writeSkill("lf", { "SKILL.md": "line1\nline2\n" });
+    const crlf = writeSkill("crlf", { "SKILL.md": "line1\r\nline2\r\n" });
+    expect(hashSkillBundle(lf).hash).toBe(hashSkillBundle(crlf).hash);
+  });
+});
+
+describe("buildManifest", () => {
+  it("includes only directories that contain a SKILL.md", () => {
+    writeSkill("real", { "SKILL.md": "x" });
+    writeSkill("not-a-skill", { "README.md": "x" });
+    const m = buildManifest(root, { source: "test" });
+    expect(Object.keys(m.skills)).toEqual(["real"]);
+  });
+});
+
+describe("diffSkills", () => {
+  const latest: SkillsManifest = {
+    source: "test",
+    skills: {
+      keep: { hash: "h1", files: 1 },
+      changed: { hash: "h2", files: 1 },
+      gone: { hash: "h3", files: 1 },
+    },
+  };
+
+  it("classifies current / outdated / missing and ignores skills not in the manifest", () => {
+    const installed: Record<string, SkillEntry> = {
+      keep: { hash: "h1", files: 1 }, // current
+      changed: { hash: "DIFFERENT", files: 1 }, // outdated
+      // gone: not installed → missing
+      extra: { hash: "hx", files: 1 }, // not in the manifest → ignored
+    };
+    const diff = diffSkills(installed, latest);
+    const byName = Object.fromEntries(diff.skills.map((s) => [s.name, s.status]));
+    expect(byName).toEqual({
+      keep: "current",
+      changed: "outdated",
+      gone: "missing",
+    });
+    expect(diff.summary).toEqual({ current: 1, outdated: 1, missing: 1 });
+  });
+
+  it("flags updateAvailable when a skill is outdated OR missing", () => {
+    // The full set is the goal, so missing skills now count too.
+    const missingOnly = diffSkills({ keep: { hash: "h1", files: 1 } }, latest);
+    expect(missingOnly.updateAvailable).toBe(true);
+
+    const hasOutdated = diffSkills({ changed: { hash: "X", files: 1 } }, latest);
+    expect(hasOutdated.updateAvailable).toBe(true);
+
+    // Everything present and current → no update.
+    const allCurrent = diffSkills(
+      {
+        keep: { hash: "h1", files: 1 },
+        changed: { hash: "h2", files: 1 },
+        gone: { hash: "h3", files: 1 },
+      },
+      latest,
+    );
+    expect(allCurrent.updateAvailable).toBe(false);
+
+    // A skill installed but not in the manifest is ignored — doesn't trigger one.
+    const withExtra = diffSkills(
+      {
+        keep: { hash: "h1", files: 1 },
+        changed: { hash: "h2", files: 1 },
+        gone: { hash: "h3", files: 1 },
+        extra: { hash: "hx", files: 1 },
+      },
+      latest,
+    );
+    expect(withExtra.updateAvailable).toBe(false);
+  });
+});
+
+describe("checkSkills install detection", () => {
+  // A spread of agent-host conventions across the upstream `skills` universe,
+  // including the XDG-nested OpenCode layout. Detection is structural
+  // (auto-discovered), so this list is illustrative, not exhaustive.
+  const CASES: ReadonlyArray<[string, string]> = [
+    [".claude/skills", "claude-code"],
+    [".agents/skills", "agents"],
+    [".codex/skills", "codex"],
+    [".cursor/skills", "cursor"],
+    [".config/opencode/skills", "opencode"],
+    [".factory/skills", "factory"],
+    [".slate/skills", "slate"],
+    [".kiro/skills", "kiro"],
+    [".hermes/skills", "hermes"],
+    [".gbrain/skills", "gbrain"],
+    [".openclaw/skills", "openclaw"],
+  ];
+
+  function writeManifest(dir: string): string {
+    const p = join(dir, "manifest.json");
+    writeFileSync(
+      p,
+      JSON.stringify({
+        source: "test",
+        skills: { alpha: { hash: "x", files: 1 }, beta: { hash: "y", files: 1 } },
+      }),
+    );
+    return p;
+  }
+
+  function installSkill(skillsDir: string, name: string): void {
+    mkdirSync(join(skillsDir, name), { recursive: true });
+    writeFileSync(join(skillsDir, name, "SKILL.md"), `# ${name}`);
+  }
+
+  it.each(CASES)("locates skills under %s in the project scope", async (rel, agent) => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+    installSkill(join(project, rel), "alpha");
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBe(join(project, rel));
+    expect(res.agent).toBe(agent);
+  });
+
+  it.each(CASES)("locates skills under %s in the global scope", async (rel, agent) => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+    installSkill(join(home, rel), "alpha");
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBe(join(home, rel));
+    expect(res.agent).toBe(agent);
+  });
+
+  it("prefers project scope over global, regardless of convention order", async () => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+    installSkill(join(home, ".claude/skills"), "alpha"); // global, higher-priority host
+    installSkill(join(project, ".hermes/skills"), "alpha"); // project, lower-priority host
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBe(join(project, ".hermes/skills"));
+    expect(res.agent).toBe("hermes");
+  });
+
+  it("reports no location and an available update when nothing is installed", async () => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBeNull();
+    expect(res.summary.missing).toBe(2);
+    expect(res.updateAvailable).toBe(true);
+  });
+
+  it("honors the --dir override and infers the agent from the path", async () => {
+    const dir = join(root, "home", ".kiro/skills");
+    installSkill(dir, "alpha");
+    const source = writeManifest(root);
+
+    const res = await checkSkills({ source, dir });
+    expect(res.location).toBe(dir);
+    expect(res.agent).toBe("kiro");
+  });
+
+  it("auto-discovers an unknown/new agent host (no closed list)", async () => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+    // A host this CLI has never heard of — structural discovery still finds it.
+    installSkill(join(home, ".some-future-agent/skills"), "alpha");
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBe(join(home, ".some-future-agent/skills"));
+    expect(res.agent).toBe("some-future-agent");
+  });
+
+  it("prefers claude-code when multiple hosts in the same scope have skills", async () => {
+    const project = join(root, "project");
+    const home = join(root, "home");
+    mkdirSync(project, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    const source = writeManifest(root);
+    installSkill(join(home, ".factory/skills"), "alpha");
+    installSkill(join(home, ".claude/skills"), "alpha");
+
+    const res = await checkSkills({ source, cwd: project, home });
+    expect(res.location).toBe(join(home, ".claude/skills"));
+    expect(res.agent).toBe("claude-code");
+  });
+});
diff --git a/packages/cli/src/utils/skillsManifest.ts b/packages/cli/src/utils/skillsManifest.ts
new file mode 100644
index 0000000000..2e94c36a13
--- /dev/null
+++ b/packages/cli/src/utils/skillsManifest.ts
@@ -0,0 +1,407 @@
+// Skills freshness: give the HyperFrames skill bundle a content fingerprint so
+// we can answer "are the installed skills the latest version?" across every
+// agent platform (Claude Code, Codex, …) — independent of how they were
+// installed.
+//
+// Why our own hash instead of the `skills-lock.json` `computedHash`: the
+// vercel-labs/skills lock hashes only `SKILL.md` with an algorithm we can't
+// recompute from source. A skill is a whole directory (SKILL.md + references/ +
+// scripts/ + palettes/ + templates/), so we fingerprint the *entire* bundle.
+// The same function hashes the source tree (to build the published manifest)
+// and the installed tree (to compare) — so equal content ⇒ equal hash.
+//
+// The manifest is intentionally minimal — `{ source, skills }`, no version
+// label or timestamp. Per-skill hashes are the source of truth for "current vs
+// outdated", so a top-level version number would only add a second, confusable
+// signal. The published manifest lives at the repo root (`skills-manifest.json`).
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+// File extensions we treat as text — line endings are normalised (CRLF→LF)
+// before hashing so a Windows checkout doesn't read as "outdated". Everything
+// else is hashed as raw bytes.
+const TEXT_EXT = new Set([
+  ".md",
+  ".txt",
+  ".mjs",
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx",
+  ".html",
+  ".css",
+  ".json",
+  ".svg",
+  ".csv",
+  ".yml",
+  ".yaml",
+]);
+
+export interface SkillEntry {
+  /** Short sha256 (16 hex chars) over the skill's whole directory. */
+  hash: string;
+  /** Number of files in the bundle (for a quick human sanity signal). */
+  files: number;
+}
+
+export interface SkillsManifest {
+  /** Source repo, e.g. "heygen-com/hyperframes". */
+  source: string;
+  /** Per-skill fingerprint, keyed by skill name. */
+  skills: Record<string, SkillEntry>;
+}
+
+export type SkillStatus = "current" | "outdated" | "missing";
+
+export interface SkillDiff {
+  name: string;
+  status: SkillStatus;
+  installedHash?: string;
+  latestHash?: string;
+}
+
+export interface SkillsCheckResult {
+  /** Install location that was checked (absolute path), or null if none found. */
+  location: string | null;
+  /** Agent convention inferred from the location (claude-code, codex, …). */
+  agent: string | null;
+  updateAvailable: boolean;
+  summary: { current: number; outdated: number; missing: number };
+  skills: SkillDiff[];
+}
+
+const DEFAULT_REPO_SLUG = "heygen-com/hyperframes";
+/** Manifest filename, published at the repo root. */
+export const MANIFEST_FILE = "skills-manifest.json";
+const FETCH_TIMEOUT_MS = 4000;
+
+// ── Hashing ────────────────────────────────────────────────────────────────
+
+function listFilesSorted(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string): void => {
+    for (const name of readdirSync(d)) {
+      if (name === ".DS_Store") continue;
+      const p = join(d, name);
+      if (statSync(p).isDirectory()) walk(p);
+      else out.push(p);
+    }
+  };
+  walk(dir);
+  // Sorting the full path list once is what guarantees a deterministic,
+  // filesystem-order-independent hash — no need to also sort per directory.
+  return out.sort();
+}
+
+/**
+ * Fingerprint one skill directory. Deterministic: files are sorted by relative
+ * POSIX path, text files are line-ending normalised, and the relative path is
+ * folded into the hash so a moved file changes the fingerprint.
+ */
+export function hashSkillBundle(skillDir: string): SkillEntry {
+  const files = listFilesSorted(skillDir);
+  const h = createHash("sha256");
+  for (const f of files) {
+    const rel = relative(skillDir, f).split(sep).join("/");
+    h.update(rel);
+    h.update("\0");
+    const ext = rel.slice(rel.lastIndexOf("."));
+    const buf = readFileSync(f);
+    if (TEXT_EXT.has(ext)) h.update(buf.toString("utf8").replace(/\r\n/g, "\n"), "utf8");
+    else h.update(buf);
+    h.update("\0");
+  }
+  return { hash: h.digest("hex").slice(0, 16), files: files.length };
+}
+
+/**
+ * Build a manifest from a `skills/` root directory (a folder of
+ * `<name>/SKILL.md` skill bundles). Used by the manifest generator. Output is
+ * fully deterministic — same content in, byte-identical manifest out.
+ */
+export function buildManifest(skillsRoot: string, meta: { source: string }): SkillsManifest {
+  const names = readdirSync(skillsRoot)
+    .filter((n) => existsSync(join(skillsRoot, n, "SKILL.md")))
+    .sort();
+  const skills: Record<string, SkillEntry> = {};
+  for (const name of names) skills[name] = hashSkillBundle(join(skillsRoot, name));
+  return { source: meta.source, skills };
+}
+
+// ── Locating installed skills ────────────────────────────────────────────────
+
+interface SkillRoot {
+  /** Absolute path to a `.../skills` directory. */
+  dir: string;
+  /** Agent convention this directory belongs to. */
+  agent: string;
+  /** project = under cwd, global = under $HOME. */
+  scope: "project" | "global";
+}
+
+/**
+ * Map a host directory name to an agent label: ".claude" → "claude-code",
+ * ".factory" → "factory", "opencode" (under .config) → "opencode".
+ */
+function agentLabel(hostDir: string): string {
+  const name = hostDir.replace(/^\.+/, "");
+  return name === "claude" ? "claude-code" : name || "unknown";
+}
+
+/** Infer the agent from a `.../skills` path by its host segment (the dir above "skills"). */
+function agentFromDir(dir: string): string {
+  const parts = dir.split(sep).filter(Boolean);
+  const i = parts.lastIndexOf("skills");
+  return agentLabel(i > 0 ? parts[i - 1]! : (parts[parts.length - 1] ?? ""));
+}
+
+/** Immediate subdirectory names of `dir` (including symlinked dirs); [] if unreadable. */
+function listSubdirs(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() || e.isSymbolicLink())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Auto-discover candidate `<host>/skills` dirs under a scope base instead of
+ * enumerating a fixed list of agents. The upstream `skills` CLI installs into
+ * 70+ agent conventions; each lands as `<base>/<host>/skills` (or the XDG
+ * `<base>/.config/<host>/skills`), so we find them by structure — future-proof
+ * as upstream adds agents. claude-code is ordered first; the rest
+ * deterministically by agent then path.
+ */
+function discoverSkillRoots(base: string, scope: "project" | "global"): SkillRoot[] {
+  const candidates: SkillRoot[] = [];
+  const add = (hostBase: string, host: string): void => {
+    const dir = join(hostBase, host, "skills");
+    if (existsSync(dir) && statSync(dir).isDirectory())
+      candidates.push({ dir, agent: agentLabel(host), scope });
+  };
+  for (const host of listSubdirs(base)) add(base, host);
+  const xdg = join(base, ".config");
+  for (const host of listSubdirs(xdg)) add(xdg, host);
+  return candidates.sort((a, b) => {
+    if (a.agent !== b.agent) {
+      if (a.agent === "claude-code") return -1;
+      if (b.agent === "claude-code") return 1;
+      return a.agent.localeCompare(b.agent);
+    }
+    return a.dir.localeCompare(b.dir);
+  });
+}
+
+/**
+ * Find the first skill root that actually contains HyperFrames skills. A
+ * `--dir` override (if given) is treated as a `.../skills` directory directly.
+ * Otherwise scan project (cwd) then global ($HOME), auto-discovering hosts.
+ */
+function locateInstall(
+  skillNames: string[],
+  opts: { dir?: string; cwd?: string; home?: string } = {},
+): SkillRoot | null {
+  if (opts.dir) {
+    return existsSync(opts.dir)
+      ? { dir: opts.dir, agent: agentFromDir(opts.dir), scope: "project" }
+      : null;
+  }
+  const roots = [
+    ...discoverSkillRoots(opts.cwd ?? process.cwd(), "project"),
+    ...discoverSkillRoots(opts.home ?? homedir(), "global"),
+  ];
+  for (const root of roots) {
+    if (skillNames.some((n) => existsSync(join(root.dir, n, "SKILL.md")))) return root;
+  }
+  return null;
+}
+
+/** Hash every manifest skill that is installed under `root`. */
+function hashInstalled(root: SkillRoot, skillNames: string[]): Record<string, SkillEntry> {
+  const out: Record<string, SkillEntry> = {};
+  for (const name of skillNames) {
+    const skillDir = join(root.dir, name);
+    if (existsSync(join(skillDir, "SKILL.md"))) out[name] = hashSkillBundle(skillDir);
+  }
+  return out;
+}
+
+// ── Diff ─────────────────────────────────────────────────────────────────────
+
+export function diffSkills(
+  installed: Record<string, SkillEntry>,
+  latest: SkillsManifest,
+): Omit<SkillsCheckResult, "location" | "agent"> {
+  // Report only on skills the manifest knows about. A skill on disk that isn't
+  // in the manifest isn't necessarily ours — `.../skills` is shared across
+  // sources — so it's not something we can meaningfully diff, and is ignored.
+  const skills: SkillDiff[] = [];
+  const summary = { current: 0, outdated: 0, missing: 0 };
+
+  for (const name of Object.keys(latest.skills).sort()) {
+    const latestEntry = latest.skills[name]!;
+    const installedEntry = installed[name];
+    let status: SkillStatus;
+    if (!installedEntry) status = "missing";
+    else if (installedEntry.hash === latestEntry.hash) status = "current";
+    else status = "outdated";
+
+    if (status === "current") summary.current++;
+    else if (status === "outdated") summary.outdated++;
+    else summary.missing++;
+
+    skills.push({
+      name,
+      status,
+      installedHash: installedEntry?.hash,
+      latestHash: latestEntry.hash,
+    });
+  }
+
+  return {
+    // The full skill set is the goal — `init` and `skills update` both pull the
+    // complete set, so anything outdated OR missing means an update is available.
+    updateAvailable: summary.outdated > 0 || summary.missing > 0,
+    summary,
+    skills,
+  };
+}
+
+// ── Resolving the "latest" manifest ──────────────────────────────────────────
+
+/** Walk up from `cwd` to find a repo checkout that ships the manifest. */
+function findRepoManifest(cwd = process.cwd()): string | null {
+  let dir = cwd;
+  // Bounded climb (deep monorepos / nested worktrees) — stops early at the FS root.
+  for (let i = 0; i < 16; i++) {
+    const p = join(dir, MANIFEST_FILE);
+    if (existsSync(p)) return p;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Narrow an untrusted JSON payload to a SkillsManifest, or throw a clear error.
+ * Guards against a CDN serving an error page (or a malformed manifest) as 200 —
+ * without this, a bad shape surfaces later as a cryptic crash in diffSkills.
+ */
+function asSkillsManifest(data: unknown, sourceLabel: string): SkillsManifest {
+  const m = data as Partial<SkillsManifest> | null;
+  if (!m || typeof m !== "object" || typeof m.skills !== "object" || m.skills === null) {
+    throw new Error(`Malformed skills manifest from ${sourceLabel}`);
+  }
+  return m as SkillsManifest;
+}
+
+async function fetchManifest(url: string): Promise<SkillsManifest> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { Connection: "close" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return asSkillsManifest(await res.json(), url);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Resolve main's live HEAD sha via `git ls-remote`. GitHub's branch-raw CDN
+ * (raw.githubusercontent.com/<owner>/<repo>/main/...) can serve stale content
+ * for minutes after a push; a SHA-pinned raw URL is immediately consistent.
+ * Returns null when git/network is unavailable so callers fall back to main.
+ */
+async function remoteHeadSha(repoSlug: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["ls-remote", `https://github.com/${repoSlug}.git`, "refs/heads/main"],
+      { timeout: FETCH_TIMEOUT_MS, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } },
+    );
+    const sha = stdout.split(/\s+/)[0]?.trim() ?? "";
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a manifest from a local path — a manifest file or a repo root. */
+function resolveLocalManifest(source: string): SkillsManifest {
+  const direct = source.endsWith(".json") ? source : join(source, MANIFEST_FILE);
+  if (existsSync(direct)) return JSON.parse(readFileSync(direct, "utf8")) as SkillsManifest;
+  // Fall back to computing from a skills/ tree on disk.
+  const skillsRoot = source.endsWith("skills") ? source : join(source, "skills");
+  if (existsSync(skillsRoot)) return buildManifest(skillsRoot, { source: skillsRoot });
+  throw new Error(`No skills manifest found at: ${source}`);
+}
+
+/**
+ * Fetch the manifest from GitHub. A full URL is fetched directly; an
+ * `owner/repo` slug (or the default repo) is SHA-pinned via `git ls-remote` to
+ * dodge raw-CDN lag, falling back to the branch URL when git is unavailable.
+ */
+async function fetchRemoteManifest(source?: string): Promise<SkillsManifest> {
+  if (source?.startsWith("http")) return fetchManifest(source);
+
+  const repoSlug = source ?? DEFAULT_REPO_SLUG;
+  const sha = await remoteHeadSha(repoSlug);
+  if (sha) {
+    try {
+      return await fetchManifest(
+        `https://raw.githubusercontent.com/${repoSlug}/${sha}/${MANIFEST_FILE}`,
+      );
+    } catch {
+      /* fall through to the branch URL */
+    }
+  }
+  return fetchManifest(`https://raw.githubusercontent.com/${repoSlug}/main/${MANIFEST_FILE}`);
+}
+
+/**
+ * Resolve the latest manifest. `source` may be:
+ *   - undefined → in-repo manifest if present (dev / CI), else fetch from GitHub
+ *   - a local path to a manifest file or a repo root containing `skills/`
+ *   - an `owner/repo` slug or full URL → fetched from GitHub
+ */
+async function resolveLatestManifest(
+  source?: string,
+  cwd = process.cwd(),
+): Promise<SkillsManifest> {
+  // A local path is a relative one (./ ../) or an absolute one — isAbsolute
+  // covers POSIX `/…` and Windows `C:\…` / `\…` on their respective platforms.
+  if (source && (source.startsWith(".") || isAbsolute(source))) {
+    return resolveLocalManifest(source);
+  }
+  if (!source) {
+    const repoManifest = findRepoManifest(cwd);
+    if (repoManifest) return JSON.parse(readFileSync(repoManifest, "utf8")) as SkillsManifest;
+  }
+  return fetchRemoteManifest(source);
+}
+
+/**
+ * End-to-end check: locate the install, hash it, diff against the latest
+ * manifest. Pure-ish (network only via `resolveLatestManifest`).
+ */
+export async function checkSkills(
+  opts: { dir?: string; source?: string; cwd?: string; home?: string } = {},
+): Promise<SkillsCheckResult> {
+  const latest = await resolveLatestManifest(opts.source, opts.cwd);
+  const skillNames = Object.keys(latest.skills);
+  const root = locateInstall(skillNames, { dir: opts.dir, cwd: opts.cwd, home: opts.home });
+  const installed = root ? hashInstalled(root, skillNames) : {};
+  const diff = diffSkills(installed, latest);
+  return { location: root?.dir ?? null, agent: root?.agent ?? null, ...diff };
+}
diff --git a/packages/cli/src/utils/skillsUpdateCheck.ts b/packages/cli/src/utils/skillsUpdateCheck.ts
new file mode 100644
index 0000000000..e3f9a2e36f
--- /dev/null
+++ b/packages/cli/src/utils/skillsUpdateCheck.ts
@@ -0,0 +1,87 @@
+// Passive "your skills are stale" nudge. Mirrors updateCheck.ts: a background
+// check populates a 24h cache; printSkillsUpdateNotice() reads the cache
+// synchronously and prints one line on exit.
+//
+// Why a passive nudge (not just `skills check`): agents don't reliably run a
+// check on their own, but they DO run render/lint/validate — so we piggyback
+// the reminder on the commands they already run.
+
+import { readConfig, writeConfig } from "../telemetry/config.js";
+import { checkSkills } from "./skillsManifest.js";
+import { updateNoticesSuppressed } from "./updateCheck.js";
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+export interface SkillsUpdateMeta {
+  updateAvailable: boolean;
+  outdated: number;
+  missing: number;
+}
+
+/** Synchronous read from cache — never fetches. */
+function getSkillsUpdateMeta(): SkillsUpdateMeta {
+  const config = readConfig();
+  return {
+    updateAvailable: config.skillsUpdateAvailable ?? false,
+    outdated: config.skillsOutdatedCount ?? 0,
+    missing: config.skillsMissingCount ?? 0,
+  };
+}
+
+function cacheFresh(lastSkillsCheck: string | undefined, now: number): boolean {
+  if (!lastSkillsCheck) return false;
+  return now - new Date(lastSkillsCheck).getTime() < CHECK_INTERVAL_MS;
+}
+
+/** Run the real check and persist the result to the cache. */
+async function refreshSkillsCache(): Promise<SkillsUpdateMeta> {
+  const result = await checkSkills();
+  // Only record a meaningful check when skills were actually found.
+  if (result.location) {
+    const config = readConfig();
+    config.lastSkillsCheck = new Date().toISOString();
+    config.skillsUpdateAvailable = result.updateAvailable;
+    config.skillsOutdatedCount = result.summary.outdated;
+    config.skillsMissingCount = result.summary.missing;
+    writeConfig(config);
+  }
+  return {
+    updateAvailable: result.updateAvailable,
+    outdated: result.summary.outdated,
+    missing: result.summary.missing,
+  };
+}
+
+/**
+ * Refresh the skills freshness cache if it is older than 24h. Best-effort:
+ * any failure (offline, no manifest published yet, no skills installed) leaves
+ * the cache untouched and reports "no update".
+ *
+ * @param force - skip the cache and check now
+ */
+export async function checkSkillsForUpdate(force?: boolean): Promise<SkillsUpdateMeta> {
+  if (!force && cacheFresh(readConfig().lastSkillsCheck, Date.now())) return getSkillsUpdateMeta();
+  try {
+    return await refreshSkillsCache();
+  } catch {
+    return getSkillsUpdateMeta();
+  }
+}
+
+/** The stale-skills nudge text, or null when nothing is outdated or missing. */
+function skillsNoticeText(meta: SkillsUpdateMeta): string | null {
+  const total = meta.outdated + meta.missing;
+  if (total < 1) return null;
+  const noun = total === 1 ? "skill" : "skills";
+  return `\n  ${total} HyperFrames ${noun} out of date or missing.\n  Run: npx hyperframes skills update\n\n`;
+}
+
+/**
+ * Print a one-line nudge to stderr if installed skills are stale. Same gating
+ * as the CLI self-update notice (CI, non-TTY, dev, HYPERFRAMES_NO_UPDATE_CHECK).
+ */
+export function printSkillsUpdateNotice(): void {
+  if (updateNoticesSuppressed()) return;
+  const text = skillsNoticeText(getSkillsUpdateMeta());
+  if (text) process.stderr.write(text);
+}
diff --git a/packages/cli/src/utils/updateCheck.ts b/packages/cli/src/utils/updateCheck.ts
index 5bff8b7fd6..a498d810d7 100644
--- a/packages/cli/src/utils/updateCheck.ts
+++ b/packages/cli/src/utils/updateCheck.ts
@@ -102,15 +102,25 @@ export function withMeta<T extends object>(data: T): T & { _meta: UpdateMeta } {
   return { ...data, _meta: getUpdateMeta() };
 }
 
+/**
+ * True when update / freshness notices should stay silent — CI, non-TTY, dev
+ * mode, or the HYPERFRAMES_NO_UPDATE_CHECK opt-out. Shared with the skills
+ * freshness notice so both honour the same gating.
+ */
+export function updateNoticesSuppressed(): boolean {
+  if (isDevMode()) return true;
+  if (process.env["CI"] === "true" || process.env["CI"] === "1") return true;
+  if (!process.stderr.isTTY) return true;
+  if (process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1") return true;
+  return false;
+}
+
 /**
  * Print update notice to stderr if a newer version is available.
  * Skipped in CI, non-TTY, dev mode, or when HYPERFRAMES_NO_UPDATE_CHECK is set.
  */
 export function printUpdateNotice(): void {
-  if (isDevMode()) return;
-  if (process.env["CI"] === "true" || process.env["CI"] === "1") return;
-  if (!process.stderr.isTTY) return;
-  if (process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1") return;
+  if (updateNoticesSuppressed()) return;
 
   const meta = getUpdateMeta();
   if (!meta.updateAvailable || !meta.latestVersion) return;
diff --git a/skills-manifest.json b/skills-manifest.json
new file mode 100644
index 0000000000..303a4a5cb5
--- /dev/null
+++ b/skills-manifest.json
@@ -0,0 +1,81 @@
+{
+  "source": "heygen-com/hyperframes",
+  "skills": {
+    "embedded-captions": {
+      "hash": "d5561ac019e72ed5",
+      "files": 144
+    },
+    "faceless-explainer": {
+      "hash": "d6beeca6029b815a",
+      "files": 17
+    },
+    "general-video": {
+      "hash": "a30225e30ec7b06c",
+      "files": 1
+    },
+    "hyperframes": {
+      "hash": "00ad363cda72268d",
+      "files": 1
+    },
+    "hyperframes-animation": {
+      "hash": "ced7bd16b3cdb376",
+      "files": 108
+    },
+    "hyperframes-cli": {
+      "hash": "ed24d781c2ae462b",
+      "files": 7
+    },
+    "hyperframes-core": {
+      "hash": "6243b6f09c94cce1",
+      "files": 13
+    },
+    "hyperframes-creative": {
+      "hash": "bb248c1bc5cc28b5",
+      "files": 67
+    },
+    "hyperframes-media": {
+      "hash": "ce80c5a15ecaf0fc",
+      "files": 40
+    },
+    "hyperframes-registry": {
+      "hash": "e3b389526834109d",
+      "files": 10
+    },
+    "media-use": {
+      "hash": "f0edb0fd7cd513a5",
+      "files": 19
+    },
+    "motion-graphics": {
+      "hash": "5a256811f730f36e",
+      "files": 23
+    },
+    "music-to-video": {
+      "hash": "abea9101f4322954",
+      "files": 132
+    },
+    "pr-to-video": {
+      "hash": "d7acaeb6281f99ac",
+      "files": 21
+    },
+    "product-launch-video": {
+      "hash": "5669874d3bdd5bd4",
+      "files": 18
+    },
+    "remotion-to-hyperframes": {
+      "hash": "9d959b31fa0fc9d0",
+      "files": 70
+    },
+    "slideshow": {
+      "hash": "ae8d8f3093ef0c04",
+      "files": 2
+    },
+    "talking-head-recut": {
+      "hash": "a3dc251f26be8a3e",
+      "files": 27
+    },
+    "website-to-video": {
+      "hash": "ac39931f9a7da749",
+      "files": 32
+    }
+  }
+}
diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 9a23ba6c0d..409efb5bde 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -83,6 +83,17 @@ Once you've picked a workflow, check it's actually available to you. If the matc
 
 After they run it, re-read the workflow's skill and continue.
 
+## Keeping skills current
+
+HyperFrames skills are versioned. `npx hyperframes init` checks the installed skills against the latest on GitHub and installs/refreshes the **full** set whenever anything is out of date or missing — so a freshly init'd project always has the complete, latest set (and re-running init on an up-to-date project is a no-op). The check is a quick GitHub round-trip; offline (or rate-limited) it falls back to installing after a short timeout, so init never hard-fails on a network hiccup. Opt out entirely with `init --skip-skills`.
+
+If a task is behaving unexpectedly, or before a long build, confirm the installed skills are current:
+
+- **Check:** `npx hyperframes skills check` (add `--json` for a machine-readable verdict; exits non-zero when anything is outdated **or missing**).
+- **Update:** `npx hyperframes skills update` — pulls the full set to the latest, **installing any not yet present** (same as init's install step).
+
+The CLI also surfaces a one-line reminder when a `render` / `lint` / `validate` run detects stale skills.
+
 ## Workflow details
 
 ### `/product-launch-video`