hypomnema 1.6.2 → 1.7.0

package/scripts/capture.mjs

@@ -8,9 +8,16 @@
  * so they propagate to other machines via the existing forward-sync ("register on
  * A → sync on B").
  *
- * Scope: commands + agents (pure file copy, no settings.json) and hooks (settings
- * reverse-capture, lossless round-trip only). skills (directory support) are
- * deferred to a separate PR.
+ * Scope: commands + agents (pure file copy, no settings.json), hooks (settings
+ * reverse-capture, lossless round-trip only), and skills (a DIRECTORY: SKILL.md
+ * plus an arbitrary subtree, stored as `extensions/skills/hypo-ext-<name>/`).
+ *
+ * Skills (skills-capture design): the same subtree walker forward-sync uses is run
+ * in `strict` mode here, so anything that cannot round-trip through the wiki
+ * (symlink, hardlink, empty directory, VCS control dir, reserved manifest name)
+ * refuses the WHOLE skill rather than capturing a lossy subset — what lands in the
+ * wiki is exactly what the far machine installs. Cumulative ceilings abort the walk
+ * early so a vendored skill (14k files, 1.1GB) never gets enumerated in full.
  *
  * Naming (capture design §3): the wiki STORAGE name is `hypo-ext-<name>.<ext>` (keeps
  * the discovery whitelist), and a sidecar `hypo-ext-<name>.manifest.json` records
@@ -31,11 +38,16 @@ import {
   readdirSync,
   writeFileSync,
   mkdirSync,
+  rmdirSync,
   unlinkSync,
   renameSync,
   realpathSync,
+  lstatSync,
+  openSync,
+  closeSync,
 } from 'fs';
-import { join, dirname } from 'path';
+import { randomBytes } from 'crypto';
+import { join, dirname, relative, sep } from 'path';
 import { homedir } from 'os';
 import { pathToFileURL, fileURLToPath } from 'url';
 import {
@@ -46,13 +58,23 @@ import {
   writePkgJsonAtomic,
 } from './lib/pkg-json.mjs';
 import { resolveHypoRoot } from './lib/hypo-root.mjs';
+import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
 import {
   syncExtensions,
   readExtensionPkgStateNoMutate,
   isValidInstallStem,
+  isValidSkillDirSegment,
+  parseSkillKey,
+  parseSkillShaValue,
+  walkSkillSubtree,
+  emptyShaMap,
+  isRealDir,
+  isContainedUnder,
+  hasSymlinkAncestor,
   scanSettingsHooks,
   parseCapturableHookCommand,
   HOOK_EVENT_ALLOWLIST,
+  SKILL_ROOT_FILE,
   EXT_PREFIX,
 } from './lib/extensions.mjs';
 import { readCoreHooksConfig, deriveCoreHookBasenames } from './lib/core-hooks.mjs';
@@ -66,11 +88,27 @@ const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 // Captured types and their singular manifest `type` value. commands/agents install
 // as top-level `.md` files; hooks install as `.mjs` and additionally register a
-// settings.json entry (reverse of forward-sync).
-const CAPTURE_TYPES = ['commands', 'agents', 'hooks'];
-const TYPE_SINGULAR = { commands: 'command', agents: 'agent', hooks: 'hook' };
+// settings.json entry (reverse of forward-sync); skills install as a DIRECTORY.
+const CAPTURE_TYPES = ['commands', 'agents', 'hooks', 'skills'];
+// The flat, single-file types. `TYPE_EXT` has no `skills` entry on purpose: a skill
+// has no install extension, and letting it through a flat helper would silently
+// build paths with an `undefined` suffix. Every flat helper keys off this list.
+const FLAT_TYPES = ['commands', 'agents', 'hooks'];
+// The flat types enumerated by readdir. hooks are enumerated from the settings.json
+// registration instead, and skills have their own directory scanner.
+const READDIR_TYPES = ['commands', 'agents'];
+const TYPE_SINGULAR = { commands: 'command', agents: 'agent', hooks: 'hook', skills: 'skill' };
 const TYPE_EXT = { commands: '.md', agents: '.md', hooks: '.mjs' };
 
+// Ceilings for a captured skill subtree (skills-capture design §3). A hand-authored
+// skill is a handful of files; a vendored one (gstack: 14,311 files / 1.1GB, mostly
+// node_modules) must be refused, not copied into a git-tracked vault. Enforced as
+// cumulative counters DURING the walk, from lstat sizes, so the verdict lands before
+// anything is read and the candidate listing never enumerates a vendored tree.
+const SKILL_MAX_FILES = 500;
+const SKILL_MAX_BYTES = 5 * 1024 * 1024;
+const SKILL_LIMITS = { strict: true, maxFiles: SKILL_MAX_FILES, maxBytes: SKILL_MAX_BYTES };
+
 function pkgJsonPath() {
   return join(HOME, '.claude', 'hypo-pkg.json');
 }
@@ -168,6 +206,90 @@ export function planCapture({ wantManifest, srcSha, existingFileSha, existingMan
   return { status: 'ready', manifest: wantManifest };
 }
 
+/**
+ * The set of install directories the wiki VALIDLY owns as directory skills.
+ *
+ * Ownership must be read through the same schema the rest of the module trusts, not
+ * raw property truthiness (skills-capture design §8). A corrupt hypo-pkg.json that
+ * parks a string under `skills/mine` would otherwise read as "already managed" and
+ * lock that skill out of capture forever, and it would also poison the "keys this
+ * run newly recorded" bookkeeping the failed-adopt purge depends on.
+ */
+export function ownedSkillDirs(recorded) {
+  const out = new Set();
+  for (const [key, value] of Object.entries(recorded)) {
+    const parsed = parseSkillKey(key);
+    if (!parsed) continue;
+    const nested = parseSkillShaValue(value);
+    if (nested === null || Object.keys(nested).length === 0) continue;
+    out.add(parsed.installDir);
+  }
+  return out;
+}
+
+/**
+ * Plan the capture of one directory skill. Same three outcomes as the flat planner,
+ * but `ready` is deliberately narrow: it means the wiki skill directory is WHOLLY
+ * ABSENT (skills-capture design §4). That narrowness is what makes the rollback safe
+ * — every path the rollback removes is a path this run created.
+ *
+ * `wikiShas` is null when the wiki directory does not exist, and a rel→sha map when
+ * it does. A wiki path that exists but cannot be read as a clean skill (a file, a
+ * symlink, a crash-truncated directory with no SKILL.md) arrives here as
+ * `wikiPresent: true, wikiShas: null` and is a conflict — never a crash, never a
+ * silent overwrite.
+ */
+export function planSkillCapture({
+  wantManifest,
+  srcShas,
+  wikiPresent,
+  wikiShas,
+  existingManifestRaw,
+}) {
+  if (!isValidSkillDirSegment(wantManifest.installName)) {
+    return { status: 'invalid', reason: `invalid installName "${wantManifest.installName}"` };
+  }
+
+  if (wikiPresent) {
+    if (wikiShas === null) {
+      return {
+        status: 'conflict',
+        reason: 'wiki target exists but is not a readable skill directory',
+      };
+    }
+    if (!deepEqual(wikiShas, srcShas)) {
+      return { status: 'conflict', reason: 'wiki skill directory exists with different content' };
+    }
+    if (existingManifestRaw == null) {
+      return { status: 'conflict', reason: 'wiki skill exists without its installName manifest' };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(existingManifestRaw);
+    } catch {
+      return { status: 'conflict', reason: 'wiki manifest is not valid JSON' };
+    }
+    if (!deepEqual(parsed, wantManifest)) {
+      return { status: 'conflict', reason: 'wiki manifest declares a different mapping' };
+    }
+    return { status: 'already', manifest: wantManifest };
+  }
+
+  // No wiki directory yet. A stray sidecar with a different mapping is still a conflict.
+  if (existingManifestRaw != null) {
+    let parsed;
+    try {
+      parsed = JSON.parse(existingManifestRaw);
+    } catch {
+      return { status: 'conflict', reason: 'stray wiki manifest is not valid JSON' };
+    }
+    if (!deepEqual(parsed, wantManifest)) {
+      return { status: 'conflict', reason: 'stray wiki manifest declares a different mapping' };
+    }
+  }
+  return { status: 'ready', manifest: wantManifest };
+}
+
 /**
  * Reverse-generate the sidecar manifest for a capture candidate. commands/agents
  * carry only `{ type, installName }`; hooks additionally carry the settings
@@ -188,9 +310,91 @@ function buildWantManifest(c) {
 
 // ── filesystem orchestration ─────────────────────────────────────────────────
 
+/**
+ * Enumerate capturable DIRECTORY skills under `~/.claude/skills/`.
+ *
+ * Every rejected entry gets a visible reason (never a silent drop): the strict walker
+ * refuses the whole skill for anything that cannot round-trip, and the ceilings abort
+ * the walk as soon as they are crossed. Returns `{ candidates, skipped }`.
+ *
+ * A flat `.md` under `skills/` is not a candidate: the directory is the real Claude
+ * Code layout, and the flat form only exists as a backward-compatible wiki storage
+ * shape. A symlinked directory is not a candidate either (never followed).
+ *
+ * `vault` is `{ hypoDir, patterns }` — the vault's `.hypoignore`. Capture must judge a
+ * source file by the rule that will apply to it AFTER it lands in the wiki: forward-sync
+ * discovers the wiki subtree through that filter, so a file the vault ignores (a `.pdf`
+ * reference, a `.cache/` directory) would be written here and then dropped from
+ * discovery, leaving the adopt check short one relpath and failing with no reason a user
+ * could act on. Refuse it up front instead, with the pattern named.
+ */
+export function scanSkillCandidates(claudeHome, ownedDirs, vault = null) {
+  const candidates = [];
+  const skipped = [];
+  const dir = join(claudeHome, 'skills');
+  if (!existsSync(dir)) return { candidates, skipped };
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return { candidates, skipped };
+  }
+  for (const name of entries) {
+    const srcPath = join(dir, name);
+    if (!isRealDir(srcPath)) continue; // flat .md, symlinked dir, or junk: not a skill dir
+    const lower = name.toLowerCase();
+    if (lower === 'hypo' || lower.startsWith('hypo-')) continue; // reserved namespace
+    if (ownedDirs.has(name)) continue; // already managed by the wiki
+    const label = `skills/${name}`;
+    if (!isValidSkillDirSegment(name)) {
+      skipped.push({ type: 'skills', file: name, reason: `unsafe skill directory name "${name}"` });
+      continue;
+    }
+    // The SOURCE walk applies no ignore filter (the patterns are the vault's, and the
+    // source lives under ~/.claude). The dir argument still has to be a string: isIgnored()
+    // calls relative() on it before it ever looks at the (empty) patterns.
+    const walked = walkSkillSubtree(srcPath, label, dir, [], SKILL_LIMITS);
+    if (walked.skip) {
+      skipped.push({
+        type: 'skills',
+        file: name,
+        reason: walked.fatal || `no regular ${SKILL_ROOT_FILE} at the skill root`,
+      });
+      continue;
+    }
+    // Would any of these files be invisible to forward-sync once they are in the wiki?
+    if (vault && vault.patterns.length > 0) {
+      const wikiRootForSkill = join(vault.hypoDir, 'extensions', 'skills', `${EXT_PREFIX}${name}`);
+      const ignored = walked.files.find((f) =>
+        isIgnored(join(wikiRootForSkill, ...f.rel.split('/')), vault.hypoDir, vault.patterns),
+      );
+      if (ignored) {
+        skipped.push({
+          type: 'skills',
+          file: name,
+          reason: `${ignored.rel} matches the vault .hypoignore and would not sync back`,
+        });
+        continue;
+      }
+    }
+    candidates.push({
+      type: 'skills',
+      file: name,
+      stem: name,
+      srcPath,
+      isDir: true,
+      files: walked.files,
+    });
+  }
+  return { candidates, skipped };
+}
+
 function scanCandidates(claudeHome, recorded, types) {
   const out = [];
   for (const type of types) {
+    // hooks come from the settings registration, skills from their own directory
+    // scanner. Letting either through here would double-enumerate them.
+    if (!READDIR_TYPES.includes(type)) continue;
     const dir = join(claudeHome, type);
     if (!existsSync(dir)) continue;
     let entries;
@@ -373,9 +577,19 @@ function log(msg) {
 
 // Write via a sibling temp + rename so the final replace is atomic and, crucially,
 // never follows a symlink already sitting at `dest` (rename swaps the link itself).
+//
+// The temp path is randomized and opened with `wx` (O_CREAT|O_EXCL). The old
+// `${dest}.tmp.${pid}` name was predictable, and writeFileSync on a path someone had
+// already planted a symlink at would follow it straight out of the wiki. O_EXCL fails
+// on an existing path of any kind, symlink included.
 function writeAtomic(dest, buf) {
-  const tmp = `${dest}.tmp.${process.pid}`;
-  writeFileSync(tmp, buf);
+  const tmp = `${dest}.tmp.${process.pid}.${randomBytes(6).toString('hex')}`;
+  const fd = openSync(tmp, 'wx');
+  try {
+    writeFileSync(fd, buf);
+  } finally {
+    closeSync(fd);
+  }
   try {
     renameSync(tmp, dest);
   } catch (err) {
@@ -386,11 +600,41 @@ function writeAtomic(dest, buf) {
   }
 }
 
-// Undo one capture's wiki writes: drop the storage file (.md or .mjs), and either
-// restore the manifest bytes we overwrote (a pre-existing same-mapping sidecar) or
-// remove the manifest we created. Used on a failed/aborted adopt so a capture never
-// half-lands.
+// Undo one capture's wiki writes: drop the storage file(s), and either restore the
+// manifest bytes we overwrote (a pre-existing same-mapping sidecar) or remove the
+// manifest we created. Used on a failed/aborted adopt so a capture never half-lands.
+//
+// A skill's rollback walks the ledger of paths this run actually created, newest
+// first: files, then the directories that held them. It never removes a tree
+// wholesale. The plan only says `ready` when the wiki directory was absent, and the
+// root is claimed with an exclusive mkdir, so everything in the ledger is ours — but
+// deleting only what we recorded is what makes that true by construction rather than
+// by trusting a check made earlier in time.
 function rollbackRec(rec) {
+  // A skill ledger is AUTHORITATIVE: only paths this run actually created are removed,
+  // and the manifest is touched only if we actually wrote it. The flat branch below
+  // unlinks `manifestPath` unconditionally, which is wrong for a skill whose write
+  // failed BEFORE the manifest was written — a dangling sidecar symlink is invisible to
+  // existsSync, so the guard refuses the write and the rollback would then delete a
+  // path the run never touched (codex pre-commit BLOCKER, with a repro).
+  if (rec.createdFiles) {
+    for (const p of [...rec.createdFiles].reverse()) {
+      try {
+        unlinkSync(p);
+      } catch {}
+    }
+    for (const d of [...(rec.createdDirs || [])].reverse()) {
+      try {
+        rmdirSync(d); // fails on a non-empty dir, which is the point: never a tree wipe
+      } catch {}
+    }
+    if (rec.manifestOverwritten && rec.manifestPrevBuf != null) {
+      try {
+        writeFileSync(rec.manifestPath, rec.manifestPrevBuf);
+      } catch {}
+    }
+    return;
+  }
   try {
     unlinkSync(rec.filePath);
   } catch {}
@@ -405,6 +649,81 @@ function rollbackRec(rec) {
   }
 }
 
+/**
+ * Write one directory skill into the wiki, recording every path created so a failed
+ * adopt can be undone exactly (skills-capture design §5/§7).
+ *
+ * Order: the sidecar manifest first, then the subtree with SKILL.md LAST. A crash at
+ * any point therefore leaves a directory with no SKILL.md, which discovery skips —
+ * never a half-skill that the far machine would partially install.
+ *
+ * `guard` re-checks the destination against the wiki boundary immediately before each
+ * mutation. Lexical containment cannot see a symlinked ancestor, and the boundary has
+ * to be the wiki root itself: rooting the walk at `extensions/skills` would lstat
+ * straight through a symlinked `extensions/`.
+ */
+function writeSkill({ rec, skillRoot, manifestPath, manifest, files, guard, wikiRoot }) {
+  const prev = readFileIfRegular(manifestPath);
+  rec.manifestExisted = prev != null;
+  rec.manifestPrevBuf = prev;
+
+  if (!guard(manifestPath) || !guard(skillRoot)) {
+    throw new Error('wiki path is not inside the vault or crosses a symlinked directory');
+  }
+  // Build the chain down to the type directory segment by segment, so a directory this
+  // run creates (a fresh `extensions/skills/`) lands in the ledger and can be undone.
+  // A recursive mkdir would create them silently and leak them on rollback.
+  const typeDir = dirname(skillRoot);
+  const chain = relative(wikiRoot, typeDir).split(sep).filter(Boolean);
+  let cur = wikiRoot;
+  for (const seg of chain) {
+    cur = join(cur, seg);
+    if (existsSync(cur)) continue;
+    if (!guard(cur)) throw new Error('wiki path crosses a symlinked directory');
+    mkdirSync(cur);
+    rec.createdDirs.push(cur);
+  }
+  // Exclusive: EEXIST here means the "absent" verdict the plan made is already stale,
+  // and the rollback must not be handed a directory it did not create.
+  mkdirSync(skillRoot);
+  rec.createdDirs.push(skillRoot);
+
+  writeAtomic(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  // Record what the write actually did, not what we predicted it would do: the rollback
+  // must never remove or restore a manifest it did not touch.
+  if (rec.manifestExisted) rec.manifestOverwritten = true;
+  else rec.createdFiles.push(manifestPath);
+
+  // SKILL.md last: it is the file that makes the directory discoverable.
+  const ordered = [
+    ...files.filter((f) => f.rel !== SKILL_ROOT_FILE),
+    ...files.filter((f) => f.rel === SKILL_ROOT_FILE),
+  ];
+  const madeDirs = new Set([skillRoot]);
+  for (const f of ordered) {
+    const destPath = join(skillRoot, ...f.rel.split('/'));
+    if (!guard(destPath)) {
+      throw new Error(`unsafe wiki destination for ${f.rel}`);
+    }
+    const parent = dirname(destPath);
+    if (!madeDirs.has(parent)) {
+      // Build the chain segment by segment so every new directory lands in the ledger.
+      const segs = f.rel.split('/').slice(0, -1);
+      let cur = skillRoot;
+      for (const s of segs) {
+        cur = join(cur, s);
+        if (madeDirs.has(cur)) continue;
+        if (!guard(cur)) throw new Error(`unsafe wiki destination for ${f.rel}`);
+        mkdirSync(cur);
+        rec.createdDirs.push(cur);
+        madeDirs.add(cur);
+      }
+    }
+    writeAtomic(destPath, readFileSync(f.srcPath));
+    rec.createdFiles.push(destPath);
+  }
+}
+
 // Remove specific per-target ownership keys from hypo-pkg.json (codex pre-commit
 // CONCERN). A partial adopt can leave forward-sync having recorded SOME of a
 // capture's install keys (e.g. the byte-identical `.mjs` was owned but its sidecar
@@ -429,19 +748,155 @@ function purgeOwnedKeys(pkgPath, target, keys) {
   if (changed) writePkgJsonAtomic(pkgPath, pkg);
 }
 
+/**
+ * Plan + write one directory skill. Pushes into the caller's captured/skipped/created
+ * lists so the shared adopt + rollback machinery downstream treats it like any other
+ * capture.
+ *
+ * The wiki side is read with the SAME strict walker as the source, so a wiki directory
+ * that is unreadable, symlink-poisoned, or crash-truncated (no SKILL.md) surfaces as
+ * `wikiShas: null` and lands on the conflict branch instead of being silently treated
+ * as absent and then blown away by a rollback.
+ */
+function captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped, created }) {
+  const wikiStem = `${EXT_PREFIX}${c.stem}`;
+  const typeDir = join(extDir, 'skills');
+  const skillRoot = join(typeDir, wikiStem);
+  const manifestPath = join(typeDir, `${wikiStem}.manifest.json`);
+  const label = `skills/${c.file}`;
+
+  // Null-prototype: a skill file legitimately named `__proto__` would otherwise assign
+  // through the prototype setter instead of creating an own key, so it would vanish from
+  // the comparison and from the adopt check (forward-sync keeps its SHA maps this way for
+  // the same reason). codex pre-commit CONCERN.
+  const srcShas = emptyShaMap();
+  for (const f of c.files) srcShas[f.rel] = sha256(readFileSync(f.srcPath));
+
+  const wikiPresent = existsSync(skillRoot);
+  let wikiShas = null;
+  if (wikiPresent && isRealDir(skillRoot)) {
+    const walked = walkSkillSubtree(skillRoot, label, args.hypoDir, [], SKILL_LIMITS);
+    if (!walked.skip) {
+      wikiShas = emptyShaMap();
+      for (const f of walked.files) wikiShas[f.rel] = sha256(readFileSync(f.srcPath));
+    }
+  }
+  if (existsSync(manifestPath) && !isRegularFile(manifestPath)) {
+    const reason = 'wiki manifest exists but is not a regular file';
+    log(`⊘ ${label}: ${reason} — skipped`);
+    skipped.push({ ...c, reason, status: 'conflict' });
+    return;
+  }
+  const existingManifestBuf = readFileIfRegular(manifestPath);
+  const existingManifestRaw = existingManifestBuf ? existingManifestBuf.toString('utf-8') : null;
+
+  const wantManifest = { type: TYPE_SINGULAR.skills, installName: c.stem };
+  const plan = planSkillCapture({
+    wantManifest,
+    srcShas,
+    wikiPresent,
+    wikiShas,
+    existingManifestRaw,
+  });
+
+  // The install key is the whole directory; forward-sync records one nested map under
+  // it, one entry per relpath (skills-dir design).
+  const rec = { ...c, installKey: `skills/${c.stem}`, srcShas };
+
+  if (plan.status === 'invalid' || plan.status === 'conflict') {
+    log(`⊘ ${label}: ${plan.reason} — skipped`);
+    skipped.push({ ...rec, reason: plan.reason, status: plan.status });
+    return;
+  }
+  if (plan.status === 'already') {
+    log(`= ${label}: already captured`);
+    captured.push({ ...rec, status: 'already' });
+    return;
+  }
+
+  // Content round-trips; the executable bit does not (forward-sync writes with the
+  // default mode). Say so rather than let a captured `scripts/run.sh` arrive
+  // non-executable on the far machine without a word.
+  const execFiles = c.files.filter((f) => {
+    try {
+      return (lstatSync(f.srcPath).mode & 0o111) !== 0;
+    } catch {
+      return false;
+    }
+  });
+  if (execFiles.length > 0) {
+    log(
+      `! ${label}: ${execFiles.length} executable file(s) — content is captured, but the executable bit is not carried by sync`,
+    );
+  }
+
+  if (!args.dryRun) {
+    // The ledger is owned by the caller so a throw MID-write is still recoverable: the
+    // paths created before the failure are already recorded in it.
+    const ledger = {
+      type: 'skills',
+      stem: c.stem,
+      manifestPath,
+      manifestExisted: false,
+      manifestOverwritten: false,
+      manifestPrevBuf: null,
+      createdFiles: [],
+      createdDirs: [],
+    };
+    try {
+      writeSkill({
+        rec: ledger,
+        skillRoot,
+        manifestPath,
+        manifest: plan.manifest,
+        files: c.files,
+        guard,
+        wikiRoot,
+      });
+    } catch (err) {
+      rollbackRec(ledger);
+      const reason = `wiki write failed (${err.message})`;
+      log(`⊘ ${label}: ${reason} — skipped`);
+      skipped.push({ ...rec, reason, status: 'conflict' });
+      return;
+    }
+    created.push(ledger);
+  }
+  captured.push({ ...rec, status: 'ready' });
+}
+
 function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
-  const extDir = join(args.hypoDir, 'extensions');
+  // Resolve the vault root through realpath. Every wiki mutation below is boundary-
+  // checked against it, and a symlinked ancestor INSIDE the vault must be caught while
+  // a vault root that is itself a symlink (a perfectly normal setup) still works. Doing
+  // it here means extDir and the sync call see the same real root.
+  let wikiRoot = args.hypoDir;
+  try {
+    wikiRoot = realpathSync(args.hypoDir);
+  } catch {
+    // Not created yet: fall back to the lexical path; the guard below still applies.
+  }
+  const extDir = join(wikiRoot, 'extensions');
   const settingsPath = join(claudeHome, 'settings.json');
   const recorded = readExtensionPkgStateNoMutate(pkgJsonPath(), 'claude');
-  // commands/agents enumerate by readdir; hooks enumerate from settings.json.
-  const dirTypes = args.types.filter((t) => t !== 'hooks');
-  const candidates = scanCandidates(claudeHome, recorded, dirTypes);
+  // commands/agents enumerate by readdir; hooks enumerate from settings.json; skills
+  // enumerate as directories under ~/.claude/skills.
+  const candidates = scanCandidates(claudeHome, recorded, args.types);
+
+  const scanSkipped = [];
+  if (args.types.includes('skills')) {
+    const skillScan = scanSkillCandidates(claudeHome, ownedSkillDirs(recorded), {
+      hypoDir: wikiRoot,
+      patterns: loadHypoIgnore(wikiRoot),
+    });
+    candidates.push(...skillScan.candidates);
+    scanSkipped.push(...skillScan.skipped);
+  }
 
   // Hooks are captured from the settings registration. Reserve the core hook
   // basenames deterministically from hooks.json; if that load is not ok (read,
   // parse, or shape failure) skip the whole hooks type rather than risk capturing
   // a core hook (T1 fail-closed contract: gate on ok, not on cfg presence).
-  const scanSkipped = [];
   if (args.types.includes('hooks')) {
     const core = readCoreHooksConfig(PKG_ROOT);
     if (!core.ok) {
@@ -457,7 +912,10 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   // Surface every scan-time skip with its reason (never a silent drop, F4). Printed
   // before any early return so observability holds even when nothing is capturable.
   for (const s of scanSkipped) {
-    const label = s.basename ? `hooks/${s.basename}` : `hooks (${s.command})`;
+    let label;
+    if (s.type === 'skills') label = `skills/${s.file}`;
+    else if (s.basename) label = `hooks/${s.basename}`;
+    else label = `hooks (${s.command})`;
     log(`⊘ ${label}: ${s.reason} — skipped`);
   }
 
@@ -481,22 +939,37 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
     };
   }
 
-  // Resolve the selection.
+  // Resolve the selection. A bare name can now be ambiguous (`commands/mine.md` and
+  // `skills/mine/` can both exist), and the old map silently let the last candidate
+  // win. Collect every match per name and refuse when there is more than one: the
+  // caller must say which by qualifying with the type.
   let selected;
   if (args.all) {
     selected = candidates;
   } else {
     const byName = new Map();
+    const add = (key, c) => {
+      if (!byName.has(key)) byName.set(key, []);
+      byName.get(key).push(c);
+    };
     for (const c of candidates) {
-      byName.set(c.file, c);
-      byName.set(c.stem, c);
-      byName.set(`${c.type}/${c.file}`, c);
+      add(c.file, c);
+      if (c.stem !== c.file) add(c.stem, c);
+      add(`${c.type}/${c.file}`, c);
     }
     selected = [];
     for (const name of args.names) {
-      const c = byName.get(name);
-      if (c) selected.push(c);
-      else log(`⊘ ${name}: no capturable candidate by that name — skipped`);
+      const matches = byName.get(name) || [];
+      if (matches.length === 0) {
+        log(`⊘ ${name}: no capturable candidate by that name — skipped`);
+        continue;
+      }
+      if (matches.length > 1) {
+        const qualified = matches.map((c) => `${c.type}/${c.file}`).join(', ');
+        log(`⊘ ${name}: ambiguous (matches ${qualified}) — qualify with the type — skipped`);
+        continue;
+      }
+      selected.push(matches[0]);
     }
   }
 
@@ -505,7 +978,15 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   const failed = [];
   const created = []; // files written THIS run, for rollback on adopt failure
 
+  // Every wiki mutation is checked against the vault root, not the type directory: a
+  // symlinked `extensions/` would otherwise be walked straight through.
+  const guard = (dest) => isContainedUnder(wikiRoot, dest) && !hasSymlinkAncestor(wikiRoot, dest);
+
   for (const c of selected) {
+    if (c.type === 'skills') {
+      captureOneSkill({ c, extDir, guard, wikiRoot, args, captured, skipped, created });
+      continue;
+    }
     const fileExt = TYPE_EXT[c.type];
     const wikiStem = `${EXT_PREFIX}${c.stem}`;
     const typeDir = join(extDir, c.type);
@@ -594,7 +1075,7 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   try {
     sync = syncExtensions({
       extDir,
-      hypoDir: args.hypoDir,
+      hypoDir: wikiRoot,
       target: 'claude',
       settingsPath: join(claudeHome, 'settings.json'),
       pkgPath: pkgJsonPath(),
@@ -623,14 +1104,17 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   // this run is preserved (never touched here).
   const strayOwnedKeys = new Set();
   for (const c of toAdopt) {
-    if (c.requiredKeys.every((k) => newSHAs[k])) {
+    const ok =
+      c.type === 'skills' ? skillAdopted(c, sync) : c.requiredKeys.every((k) => newSHAs[k]);
+    if (ok) {
       c.status = 'captured';
     } else {
       c.status = 'failed';
       failed.push(c);
       const rec = created.find((r) => r.type === c.type && r.stem === c.stem);
       if (rec) rollbackRec(rec);
-      for (const k of c.requiredKeys) {
+      const keys = c.type === 'skills' ? [c.installKey] : c.requiredKeys;
+      for (const k of keys) {
         if (recorded[k] === undefined && newSHAs[k] !== undefined) strayOwnedKeys.add(k);
       }
     }
@@ -639,7 +1123,8 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   // stems make this impossible in practice, but the guard keeps the rollback
   // strictly scoped to failed captures).
   for (const c of toAdopt) {
-    if (c.status === 'captured') for (const k of c.requiredKeys) strayOwnedKeys.delete(k);
+    if (c.status !== 'captured') continue;
+    for (const k of c.type === 'skills' ? [c.installKey] : c.requiredKeys) strayOwnedKeys.delete(k);
   }
   purgeOwnedKeys(pkgJsonPath(), 'claude', strayOwnedKeys);
   const okCaptured = captured.filter((c) => c.status === 'captured' || c.status === 'already');
@@ -648,12 +1133,43 @@ function run(args, { claudeHome = join(HOME, '.claude') } = {}) {
   return { selected, captured, skipped, failed, sync };
 }
 
+/**
+ * Did forward-sync actually adopt this skill, file for file?
+ *
+ * Presence of the key is not enough. A skill's recorded value is a NESTED map, so the
+ * `newSHAs[key]` truthiness test the flat types use passes as soon as a single relpath
+ * lands — a skill missing half its files would count as adopted and the wiki would own
+ * a lossy install. Worse, copyOne hands back the previously recorded SHA on its drift
+ * and skip paths, so even a per-relpath presence check can be satisfied by a file sync
+ * refused to touch.
+ *
+ * So: every captured relpath must be recorded with EXACTLY the SHA we captured, the
+ * recorded map must hold nothing else, and sync must not have reported drift or a
+ * conflict against this skill. A first capture is source == install target, so every
+ * file is expected to land on the up-to-date branch.
+ */
+function skillAdopted(c, sync) {
+  const nested = (sync.newSHAs || {})[c.installKey];
+  if (!nested || typeof nested !== 'object' || Array.isArray(nested)) return false;
+  const wikiName = `${EXT_PREFIX}${c.stem}`;
+  const touched = (list) => (list || []).some((e) => e.name === wikiName);
+  if (touched(sync.drifts) || touched(sync.conflicts)) return false;
+  const relpaths = Object.keys(c.srcShas);
+  if (Object.keys(nested).length !== relpaths.length) return false;
+  return relpaths.every((rel) => nested[rel] === c.srcShas[rel]);
+}
+
 function report(captured, skipped, failed, dryRun) {
   log('');
   if (captured.length > 0) {
     log(`${dryRun ? 'Would capture' : 'Captured'} ${captured.length} extension(s):`);
-    for (const c of captured)
-      log(`  ${c.type}/${c.file} → extensions/${c.type}/${EXT_PREFIX}${c.stem}${TYPE_EXT[c.type]}`);
+    for (const c of captured) {
+      const dest =
+        c.type === 'skills'
+          ? `extensions/skills/${EXT_PREFIX}${c.stem}/`
+          : `extensions/${c.type}/${EXT_PREFIX}${c.stem}${TYPE_EXT[c.type]}`;
+      log(`  ${c.type}/${c.file} → ${dest}`);
+    }
   }
   if (skipped.length > 0) log(`Skipped ${skipped.length} (conflict/invalid — see above).`);
   if (failed.length > 0)
@@ -667,11 +1183,14 @@ function report(captured, skipped, failed, dryRun) {
 function main() {
   const args = parseArgs(process.argv);
   if (args.help) {
-    log('Usage: hypomnema capture [names…] [--all] [--type=commands,agents,hooks] [--dry-run]');
-    log('  Pull ~/.claude/{commands,agents} extensions and canonical settings.json');
-    log('  hooks into the wiki for cross-machine sync. Hooks are captured only when');
-    log('  they round-trip losslessly to the canonical form; others are skipped with');
-    log('  a reason.');
+    log(
+      'Usage: hypomnema capture [names…] [--all] [--type=commands,agents,hooks,skills] [--dry-run]',
+    );
+    log('  Pull ~/.claude/{commands,agents,skills} extensions and canonical');
+    log('  settings.json hooks into the wiki for cross-machine sync. Hooks and skills');
+    log('  are captured only when they round-trip losslessly; others are skipped with');
+    log('  a reason. A skill is a directory (SKILL.md + subtree); one holding symlinks,');
+    log(`  hardlinks, empty dirs, or more than ${SKILL_MAX_FILES} files is refused.`);
     return 0;
   }
   const res = run(args);