skillshop 2.2.0 → 4.0.0

package/src/legacy-cli.js

@@ -14,6 +14,19 @@ import {
   composeAgentsInstructions,
   hasProjectInstructions
 } from './agents-instructions.js';
+import {
+  PersonalLibraryError,
+  importTrackedPersonalSkill,
+  inspectPersonalLibrary,
+  initPersonalLibrary,
+  librarySelectionFileName,
+  listPersonalSkills,
+  resolvePersonalSkill,
+  resolveRecordedPersonalSkill,
+  selectedLibraryRoot,
+  validatePersonalSkillDirectory
+} from './personal-library.js';
+import { downloadPersonalSkill, GitHubLibraryError } from './github-library.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const skillsContentRoot = path.join(packageRoot, 'skills-content');
@@ -33,6 +46,7 @@ const projectTemplateName = 'AGENTS.template.md';
 const defaultProjectTemplate = '# Project instructions\n\n{{ blocks }}\n';
 const internalUpgradeRefreshCommand = '__skillshop_upgrade_refresh';
 const internalUpgradeRefreshToken = 'skillshop-managed-upgrade-v1';
+const personalLibraryTemplateRoot = path.join(packageRoot, 'templates', 'skillshop-library');
 const globalAgentsTargets = [
   path.join('.codex', 'AGENTS.md'),
   path.join('.agents', 'AGENTS.md'),
@@ -129,9 +143,16 @@ function printHelp() {
   skillshop update [name]
   skillshop update --push
   skillshop migrate [root ...]
+  skillshop library init [directory]
+  skillshop library list
+  skillshop download @<owner>/<skill> [--force]
+  skillshop install @<owner>/<skill> [--global]
+  skillshop sync
   skillshop list
 
 Install, uninstall, and update skills from the local registry.
+Personal folder libraries are the source of truth for user-authored skills. Initialize or select one with skillshop library init [directory], list it with skillshop library list, download a source with skillshop download @owner/skill, and install it with skillshop install @owner/skill. Bare names install from the selected library.
+skillshop sync propagates personal source edits and removals without fetching upstream. It can also adopt tracked legacy bundled copies into the selected library when all surviving copies agree; init itself never migrates.
 
 Agent instructions:
   skillshop agents init creates a neutral .agents/instructions/AGENTS.template.md and renders it into a separate managed region in the project-root AGENTS.md. Existing text and prior managed guidance are preserved. Edit the template and sibling *.block.md sources, not the generated region.
@@ -341,7 +362,8 @@ function readLock(root) {
     throw new CliError(`cannot parse ${lockPath}: ${error.message}`);
   }
 
-  if (![1, 2].includes(lock?.lockfileVersion) || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+  if (![1, 2].includes(lock?.lockfileVersion) || lock.registry !== 'local' ||
+      !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills)) {
     throw new CliError(`${lockPath} is not a supported skillshop lockfile`);
   }
 
@@ -392,8 +414,9 @@ function writeLock(root, lock) {
     Object.entries(lock.skills)
       .sort(([left], [right]) => left.localeCompare(right))
       .map(([name, entry]) => [name, {
-        version: entry.version,
-        author: entry.author,
+        ...(typeof entry.version === 'string' ? { version: entry.version } : {}),
+        ...(typeof entry.author === 'string' ? { author: entry.author } : {}),
+        ...(entry.source ? { source: entry.source } : {}),
         paths: lockedTargets(root, name, entry).map((target) => relativePath(root, target)).sort()
       }])
   );
@@ -663,7 +686,8 @@ function readGlobalSkills() {
   } catch (error) {
     throw new CliError(`cannot parse ${filePath}: ${error.message}`);
   }
-  if (lock?.lockfileVersion !== 2 || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+  if (lock?.lockfileVersion !== 2 || lock.registry !== 'local' ||
+      !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills)) {
     throw new CliError(`${filePath} is not a supported skillshop global manifest`);
   }
   return lock;
@@ -688,7 +712,13 @@ function writeGlobalSkills(lock) {
   const skills = Object.fromEntries(Object.entries(lock.skills).sort(([left], [right]) => left.localeCompare(right))
     .map(([name, entry]) => {
       const paths = globalTargets(name, entry).sort();
-      return [name, { paths, copies: Object.fromEntries(paths.map((target) => [target, entry.copies?.[target] ?? {}])) }];
+      return [name, {
+        ...(typeof entry.version === 'string' ? { version: entry.version } : {}),
+        ...(typeof entry.author === 'string' ? { author: entry.author } : {}),
+        ...(entry.source ? { source: entry.source } : {}),
+        paths,
+        copies: Object.fromEntries(paths.map((target) => [target, entry.copies?.[target] ?? {}]))
+      }];
     }));
   const filePath = path.join(skillshopHome(), globalSkillsFileName);
   const contents = `${JSON.stringify({ ...emptyLock(), skills }, null, 2)}\n`;
@@ -709,7 +739,12 @@ function repairTrackedSkills(root, lock) {
       delete lock.skills[name];
       continue;
     }
+    if (root && entry.source?.kind === 'personal-library') {
+      entry.paths = targets.map((target) => relativePath(root, target));
+      continue;
+    }
     for (const target of targets) {
+      if (!root && entry.copies?.[target]?.source?.kind === 'personal-library') continue;
       const manifestPath = path.join(target, 'SKILL.md');
       assertLocalDestination(root ?? os.homedir(), manifestPath, `manifest for ${name}`);
       const installation = root ? entry : entry.copies?.[target] ?? {};
@@ -753,35 +788,480 @@ function reconcileCurrentRepository() {
 
 function replaceSkillDirectory(sourceDir, targetDir) {
   const temporaryDir = `${targetDir}.skillshop-tmp-${process.pid}`;
+  const backupDir = `${targetDir}.skillshop-backup-${process.pid}`;
   fs.mkdirSync(path.dirname(targetDir), { recursive: true });
   fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.rmSync(backupDir, { recursive: true, force: true });
   fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
-  fs.rmSync(targetDir, { recursive: true, force: true });
-  fs.renameSync(temporaryDir, targetDir);
+  const hadTarget = fs.existsSync(targetDir);
+  try {
+    if (hadTarget) fs.renameSync(targetDir, backupDir);
+    fs.renameSync(temporaryDir, targetDir);
+    fs.rmSync(backupDir, { recursive: true, force: true });
+  } catch (error) {
+    if (hadTarget && !fs.existsSync(targetDir) && fs.existsSync(backupDir)) fs.renameSync(backupDir, targetDir);
+    throw error;
+  } finally {
+    fs.rmSync(temporaryDir, { recursive: true, force: true });
+  }
 }
 
-function installAt(name, requestedVersion, targetDir) {
-  const metadata = skillMetadata(name);
+function personalTreeSnapshot(root, label) {
+  const entries = [];
+  const visit = (directory, relative = '') => {
+    const stat = fs.lstatSync(directory);
+    if (stat.isSymbolicLink()) throw new CliError(`${label} contains a symlink: ${directory}`);
+    if (stat.isDirectory()) {
+      entries.push({ path: relative, kind: 'directory', mode: stat.mode & 0o777 });
+      for (const name of fs.readdirSync(directory).sort()) {
+        visit(path.join(directory, name), relative ? `${relative}/${name}` : name);
+      }
+      return;
+    }
+    if (!stat.isFile()) throw new CliError(`${label} contains a non-regular entry: ${directory}`);
+    entries.push({
+      path: relative,
+      kind: 'file',
+      mode: stat.mode & 0o777,
+      contents: fs.readFileSync(directory).toString('base64')
+    });
+  };
+  visit(root);
+  return entries;
+}
+
+function replaceSyncedSkillDirectory(sourceDir, targetDir) {
+  const parent = path.dirname(targetDir);
+  const transaction = fs.mkdtempSync(path.join(parent, `.skillshop-sync-${process.pid}-`));
+  const staged = path.join(transaction, 'skill');
+  const backup = path.join(transaction, 'previous-skill');
+  let backedUp = false;
+  let installed = false;
+  try {
+    fs.cpSync(sourceDir, staged, { recursive: true, errorOnExist: true, force: false });
+    personalTreeSnapshot(staged, 'staged personal skill');
+    fs.renameSync(targetDir, backup);
+    backedUp = true;
+    fs.renameSync(staged, targetDir);
+    installed = true;
+  } catch (error) {
+    if (installed) fs.rmSync(targetDir, { recursive: true, force: true });
+    if (backedUp && fs.existsSync(backup)) fs.renameSync(backup, targetDir);
+    throw error;
+  } finally {
+    // Once the new directory is installed, backup cleanup cannot invalidate
+    // that successful replacement or remove its only surviving content.
+    try { fs.rmSync(transaction, { recursive: true, force: true }); } catch {}
+  }
+}
+
+function recordedPersonalSkill(name, source) {
+  try {
+    const resolved = resolveRecordedPersonalSkill(source);
+    if (!resolved) throw new CliError(`recorded personal source for ${name} is missing from ${source.root}`);
+    return resolved;
+  } catch (error) {
+    if (/personal skill .* does not exist|\/SKILL\.md is missing/.test(error.message)) {
+      throw new CliError(`recorded personal source for ${name} is missing from ${source.root}`);
+    }
+    throw error;
+  }
+}
+
+function isLegacyBundleSource(source) {
+  return source == null || ['bundle', 'bundled'].includes(source.kind);
+}
+
+function syncPersonalCopy(name, source, target, boundary) {
+  assertNoManagedSymlink(boundary, target, `sync destination for ${name}`);
+  assertInstallPathsDoNotOverlap(source.sourceDir, target);
+  let targetStat;
+  try {
+    targetStat = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'missing';
+    throw error;
+  }
+  if (!targetStat.isDirectory() || targetStat.isSymbolicLink()) {
+    throw new CliError(`sync destination for ${name} is not a regular skill directory: ${target}`);
+  }
+  const sourceTree = personalTreeSnapshot(source.sourceDir, `personal source for ${name}`);
+  const targetTree = personalTreeSnapshot(target, `sync destination for ${name}`);
+  if (JSON.stringify(sourceTree) === JSON.stringify(targetTree)) return 'current';
+  replaceSyncedSkillDirectory(source.sourceDir, target);
+  return 'updated';
+}
+
+function syncPersonalCopies(cwd) {
+  const failures = [];
+  const roots = new Map();
+  const currentRoot = findLockRoot(cwd, { required: false });
+  if (currentRoot) roots.set(canonicalPath(currentRoot), canonicalPath(currentRoot));
+  let ownershipComplete = true;
+  try {
+    for (const registeredRoot of readRegistry().repositories) {
+      const canonical = canonicalPath(registeredRoot);
+      roots.set(canonical, canonical);
+    }
+  } catch (error) {
+    failures.push(`project registry: ${error.message}`);
+    ownershipComplete = false;
+  }
+
+  const contexts = [];
+  for (const root of roots.values()) {
+    if (!hasLock(root)) continue;
+    try {
+      const lock = readLock(root);
+      contexts.push({ kind: 'project', root, lock, original: JSON.stringify(lock) });
+    } catch (error) {
+      failures.push(`project ${root}: ${error.message}`);
+      ownershipComplete = false;
+    }
+  }
+  let globalLock = null;
+  try {
+    globalLock = readGlobalSkills();
+  } catch (error) {
+    failures.push(`global manifest: ${error.message}`);
+    ownershipComplete = false;
+  }
+  if (globalLock) contexts.push({ kind: 'global', lock: globalLock, original: JSON.stringify(globalLock) });
+
+  let updated = 0;
+  let current = 0;
+  let pruned = 0;
+  let selectedRoot = null;
+  try {
+    selectedRoot = selectedLibraryRoot(skillshopHome());
+  } catch (error) {
+    failures.push(`selected personal library: ${error.message}`);
+  }
+  const libraryInfo = new Map();
+  const getLibrarySkill = (name) => {
+    if (!selectedRoot) return null;
+    if (!libraryInfo.has(name)) {
+      libraryInfo.set(name, resolvePersonalSkill(name, skillshopHome(), selectedRoot));
+    }
+    return libraryInfo.get(name);
+  };
+  const isUnknownSource = (source) => source != null && source.kind !== 'personal-library' && !isLegacyBundleSource(source);
+  const legacyGroups = new Map();
+  const personalItems = [];
+  const unknownSourceNames = new Set();
+
+  for (const context of contexts) {
+    for (const [name, entry] of Object.entries(context.lock.skills)) {
+      if (context.kind === 'project') {
+        let targets;
+        try { targets = lockedTargets(context.root, name, entry); }
+        catch (error) { failures.push(`project ${name}: ${error.message}`); ownershipComplete = false; continue; }
+        if (entry.source?.kind === 'personal-library') {
+          personalItems.push({ kind: 'project', context, name, entry, sourceRecord: entry.source, targets });
+        } else if (isLegacyBundleSource(entry.source)) {
+          legacyGroups.set(name, [...(legacyGroups.get(name) ?? []), { kind: 'project', context, name, entry, targets }]);
+        } else if (isUnknownSource(entry.source)) unknownSourceNames.add(name);
+        continue;
+      }
+
+      let targets;
+      try { targets = globalTargets(name, entry); }
+      catch (error) { failures.push(`global ${name}: ${error.message}`); ownershipComplete = false; continue; }
+      for (const target of targets) {
+        const copy = entry.copies?.[target] ?? {};
+        const sourceRecord = copy.source ?? entry.source;
+        if (sourceRecord?.kind === 'personal-library') {
+          personalItems.push({ kind: 'global', context, name, entry, copy, target, sourceRecord });
+        } else if (isLegacyBundleSource(sourceRecord)) {
+          legacyGroups.set(name, [...(legacyGroups.get(name) ?? []), { kind: 'global', context, name, entry, copy, target }]);
+        } else if (isUnknownSource(sourceRecord)) unknownSourceNames.add(name);
+      }
+    }
+  }
+
+  const updateLocalOwnership = (context, name, entry, source, targets) => {
+    const kept = targets.filter((target) => target.present).map(({ target }) => relativePath(context.root, target)).sort();
+    if (!kept.length) {
+      delete context.lock.skills[name];
+      return;
+    }
+    entry.paths = kept;
+    entry.source = source.source;
+    if (typeof source.author === 'string') entry.author = source.author;
+    else delete entry.author;
+    if (typeof source.version === 'string') entry.version = source.version;
+    else delete entry.version;
+  };
+  const updateGlobalOwnership = (entry, copy, target, source) => {
+    copy.source = source.source;
+    if (typeof source.author === 'string') copy.author = source.author;
+    else delete copy.author;
+    if (typeof source.version === 'string') copy.version = source.version;
+    else delete copy.version;
+    entry.copies ??= {};
+    entry.copies[target] = copy;
+  };
+  const pruneMissing = (item) => {
+    pruned += 1;
+    if (item.kind === 'project') {
+      const targets = lockedTargets(item.context.root, item.name, item.entry).filter((target) => target !== item.target);
+      if (targets.length) item.entry.paths = targets.map((target) => relativePath(item.context.root, target));
+      else delete item.context.lock.skills[item.name];
+      console.log(`Pruned missing project copy ${item.target}`);
+    } else {
+      delete item.entry.copies[item.target];
+      const paths = item.entry.paths.filter((target) => target !== item.target);
+      if (paths.length) item.entry.paths = paths;
+      else delete item.context.lock.skills[item.name];
+      console.log(`Pruned missing global copy ${item.target}`);
+    }
+  };
+
+  for (const item of personalItems) {
+    const { name, sourceRecord } = item;
+    let source;
+    try { source = recordedPersonalSkill(name, sourceRecord); }
+    catch (error) { failures.push(`${item.kind} ${name}: ${error.message}`); continue; }
+    const targets = item.kind === 'project' ? item.targets : [item.target];
+    const prepared = [];
+    let failed = false;
+    for (const target of targets) {
+      try {
+        const boundary = item.kind === 'project' ? item.context.root : os.homedir();
+        assertNoManagedSymlink(boundary, target, `sync destination for ${name}`);
+        assertInstallPathsDoNotOverlap(source.sourceDir, target);
+        let stat;
+        try { stat = fs.lstatSync(target); }
+        catch (error) { if (error.code === 'ENOENT') { prepared.push({ target, present: false }); continue; } throw error; }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) throw new CliError(`sync destination for ${name} is not a regular skill directory: ${target}`);
+        personalTreeSnapshot(target, `sync destination for ${name}`);
+        prepared.push({ target, present: true });
+      } catch (error) { failures.push(`${item.kind} ${name} at ${target}: ${error.message}`); failed = true; }
+    }
+    if (failed) continue;
+    for (const target of prepared) {
+      if (!target.present) { pruneMissing({ ...item, target: target.target }); continue; }
+      try {
+        const result = syncPersonalCopy(name, source, target.target, item.kind === 'project' ? item.context.root : os.homedir());
+        if (result === 'updated') { updated += 1; console.log(`Synced ${item.kind} copy ${target.target}`); }
+        else current += 1;
+      } catch (error) { failures.push(`${item.kind} ${name} at ${target.target}: ${error.message}`); failed = true; }
+    }
+    if (failed) continue;
+    if (item.kind === 'project') updateLocalOwnership(item.context, name, item.entry, source, prepared);
+    else updateGlobalOwnership(item.entry, item.copy, item.target, source);
+  }
+
+  for (const [name, group] of legacyGroups) {
+    const root = selectedRoot;
+    if (!root) {
+      failures.push(`${name}: select a personal library with "skillshop library init" before adopting legacy copies`);
+      continue;
+    }
+    let source;
+    try { source = getLibrarySkill(name); }
+    catch (error) { failures.push(`${name}: selected library source is unsafe or invalid: ${error.message}`); continue; }
+    if (!source && unknownSourceNames.has(name)) {
+      failures.push(`${name}: an ownership record has an unknown source kind; legacy copies were left unchanged`);
+      continue;
+    }
+
+    const prepared = [];
+    let failed = false;
+    for (const item of group) {
+      const boundary = item.kind === 'project' ? item.context.root : os.homedir();
+      const target = item.kind === 'project' ? item.targets : [item.target];
+      for (const destination of target) {
+        try {
+          assertNoManagedSymlink(boundary, destination, `legacy copy for ${name}`);
+          if (source) assertInstallPathsDoNotOverlap(source.sourceDir, destination);
+          else assertInstallPathsDoNotOverlap(destination, path.join(root, 'skills', name));
+          let stat;
+          try { stat = fs.lstatSync(destination); }
+          catch (error) { if (error.code === 'ENOENT') { prepared.push({ item, target: destination, present: false }); continue; } throw error; }
+          if (!stat.isDirectory() || stat.isSymbolicLink()) throw new CliError(`legacy copy for ${name} is not a regular skill directory: ${destination}`);
+          validatePersonalSkillDirectory(boundary, destination, name);
+          const snapshot = personalTreeSnapshot(destination, `legacy copy for ${name}`);
+          prepared.push({ item, target: destination, present: true, snapshot });
+        } catch (error) { failures.push(`${name} at ${destination}: ${error.message}`); failed = true; }
+      }
+    }
+    if (failed) continue;
+
+    const present = prepared.filter(({ present: exists }) => exists);
+    if (!present.length) {
+      for (const item of group) {
+        if (item.kind === 'project') {
+          const existing = item.targets.filter((target) => fs.existsSync(target));
+          const missing = item.targets.filter((target) => !fs.existsSync(target));
+          for (const target of missing) {
+            pruned += 1;
+            console.log(`Pruned missing project copy ${target}`);
+          }
+          if (missing.length) {
+            item.entry.paths = existing.map((target) => relativePath(item.context.root, target));
+            if (!existing.length) delete item.context.lock.skills[name];
+          }
+        } else if (!fs.existsSync(item.target)) pruneMissing(item);
+      }
+      continue;
+    }
+
+    if (!source) {
+      if (!ownershipComplete) {
+        failures.push(`${name}: cannot import a missing source because one or more ownership manifests could not be read`);
+        continue;
+      }
+      const expected = JSON.stringify(present[0].snapshot);
+      if (present.some(({ snapshot }) => JSON.stringify(snapshot) !== expected)) {
+        failures.push(`${name}: tracked legacy copies diverge; resolve them before adoption`);
+        continue;
+      }
+      try {
+        const skillDirectory = path.join(inspectPersonalLibrary(root).skillsDirectory, name);
+        for (const copy of present) assertInstallPathsDoNotOverlap(copy.target, skillDirectory);
+        importTrackedPersonalSkill(root, present[0].target, name);
+        source = resolvePersonalSkill(name, skillshopHome(), root);
+      } catch (error) { failures.push(`${name}: could not import agreeing legacy copies: ${error.message}`); continue; }
+      for (const copy of present.slice(1)) {
+        if (JSON.stringify(copy.snapshot) !== JSON.stringify(present[0].snapshot)) {
+          failures.push(`${name}: tracked legacy copies changed during adoption`);
+          failed = true;
+          break;
+        }
+      }
+      if (failed) continue;
+      console.log(`Adopted ${name} from ${present.length} agreeing tracked copy/copies into ${root}`);
+    }
+
+    const localEntryResults = new Map();
+    for (const copy of prepared) {
+      if (!copy.present) { pruneMissing({ ...copy.item, target: copy.target }); continue; }
+      let result;
+      try {
+        result = source ? syncPersonalCopy(name, source, copy.target, copy.item.kind === 'project' ? copy.item.context.root : os.homedir()) : 'current';
+      } catch (error) {
+        failures.push(`${copy.item.kind} ${name} at ${copy.target}: ${error.message}`);
+        failed = true;
+        if (copy.item.kind === 'project') {
+          const state = localEntryResults.get(copy.item) ?? { successes: [], failed: false };
+          state.failed = true;
+          localEntryResults.set(copy.item, state);
+        }
+        continue;
+      }
+      if (result === 'updated') { updated += 1; console.log(`Synced adopted ${name} copy ${copy.target}`); }
+      else current += 1;
+      if (copy.item.kind === 'project') {
+        const state = localEntryResults.get(copy.item) ?? { successes: [], failed: false };
+        state.successes.push(copy.target);
+        localEntryResults.set(copy.item, state);
+      } else updateGlobalOwnership(copy.item.entry, copy.item.copy, copy.target, source);
+    }
+    for (const [item, state] of localEntryResults) {
+      if (state.failed) continue;
+      if (!state.successes.length) continue;
+      item.entry.source = source.source;
+      if (typeof source.author === 'string') item.entry.author = source.author;
+      else delete item.entry.author;
+      if (typeof source.version === 'string') item.entry.version = source.version;
+      else delete item.entry.version;
+      item.entry.paths = state.successes.map((target) => relativePath(item.context.root, target)).sort();
+    }
+  }
+
+  for (const context of contexts) {
+    if (context.kind === 'project' && JSON.stringify(context.lock) !== context.original) {
+      try { writeLock(context.root, context.lock); }
+      catch (error) { failures.push(`project ${context.root} state: ${error.message}`); }
+    }
+  }
+
+  if (globalLock && JSON.stringify(globalLock) !== contexts.find(({ kind }) => kind === 'global')?.original) {
+    try { writeGlobalSkills(globalLock); }
+    catch (error) { failures.push(`global state: ${error.message}`); }
+  }
+  console.log(`Personal sync: ${updated} updated, ${current} current, ${pruned} missing destination(s) pruned.`);
+  if (failures.length) {
+    for (const failure of failures) console.error(`skillshop: ${failure}`);
+    throw new CliError(`sync completed with ${failures.length} failure(s); ${updated} copy/copies updated, ${current} current, ${pruned} missing destination(s) pruned`);
+  }
+}
+
+function installAt(name, requestedVersion, targetDir, metadata = skillMetadata(name), boundary = path.dirname(targetDir)) {
   if (requestedVersion && requestedVersion !== metadata.version) {
-    throw new CliError(
-      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${metadata.version}`
-    );
+    throw new CliError(metadata.kind === 'personal'
+      ? `${name}@${requestedVersion} is unavailable in the personal library${metadata.version ? `; library version is ${metadata.version}` : ''}`
+      : `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${metadata.version}`);
   }
 
+  if (metadata.kind === 'personal') {
+    assertNoManagedSymlink(boundary, targetDir, `install destination for ${name}`);
+    assertInstallPathsDoNotOverlap(metadata.sourceDir, targetDir);
+  }
   const updating = fs.existsSync(targetDir);
   replaceSkillDirectory(metadata.sourceDir, targetDir);
   return { ...metadata, targetDir, updating };
 }
 
+function assertInstallPathsDoNotOverlap(sourceDir, targetDir) {
+  const source = path.resolve(sourceDir);
+  const target = path.resolve(targetDir);
+  const within = (parent, child) => {
+    const relative = path.relative(parent, child);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+  };
+  if (within(source, target) || within(target, source)) {
+    throw new CliError(`install destination overlaps personal source directory: ${source}`);
+  }
+}
+
 function lockEntry(root, results) {
   const [result] = results;
   return {
-    version: result.version,
-    author: result.author,
+    ...(typeof result.version === 'string' ? { version: result.version } : {}),
+    ...(typeof result.author === 'string' ? { author: result.author } : {}),
+    ...(result.source ? { source: result.source } : {}),
     paths: results.map(({ targetDir }) => relativePath(root, targetDir)).sort()
   };
 }
 
+function resolvedInstallSource(name, stateHome, { existing = null, requested = false, selectedRoot = undefined, personalOnly = false } = {}) {
+  const allRecordedSources = [existing?.source, ...Object.values(existing?.copies ?? {}).map((copy) => copy?.source)]
+    .filter((source) => source != null);
+  if (personalOnly && allRecordedSources.some((source) => source.kind !== 'personal-library' && !isLegacyBundleSource(source))) {
+    throw new CliError(`${name} has an ownership record with an unknown source kind; refusing to replace it`);
+  }
+  const recordedSources = allRecordedSources
+    .filter((source) => source?.kind === 'personal-library');
+  if (requested) {
+    const selected = resolvePersonalSkill(name, stateHome, selectedRoot ?? null);
+    if (selected) {
+      if (recordedSources.some((source) => path.resolve(source.root) !== path.resolve(selected.source.root) || source.skillDirectory !== selected.source.skillDirectory)) {
+        throw new CliError(`${name} is already owned by a different personal library; uninstall it before changing sources`);
+      }
+      return selected;
+    }
+    if (personalOnly && selectedRoot && !recordedSources.length) {
+      throw new CliError(`${name} is not present in the selected personal library`);
+    }
+  }
+  if (recordedSources.length) {
+    const identities = new Set(recordedSources.map((source) => `${path.resolve(source.root)}\0${source.skillDirectory ?? ''}\0${source.skill ?? name}`));
+    if (identities.size !== 1) throw new CliError(`${name} has multiple personal library sources; refusing to choose one implicitly`);
+    const source = recordedSources[0];
+    const recorded = recordedPersonalSkill(name, source);
+    if (recorded.name !== name) throw new CliError(`recorded personal source for ${name} is unavailable`);
+    return recorded;
+  }
+  if (requested && selectedRoot === undefined) {
+    const selected = resolvePersonalSkill(name, stateHome);
+    if (selected) return selected;
+  }
+  if (personalOnly) throw new CliError(`${name} is not present in the selected or recorded personal library`);
+  return skillMetadata(name);
+}
+
 function installGlobal(name, requestedVersion) {
   const config = readConfig();
   const skillDirectories = config
@@ -789,16 +1269,37 @@ function installGlobal(name, requestedVersion) {
     : [path.join(os.homedir(), '.agents', 'skills')];
 
   const globalSkills = readGlobalSkills();
-  for (const skillDirectory of skillDirectories) {
+  const selectedRoot = selectedLibraryRoot(skillshopHome());
+  const existing = globalSkills.skills[name];
+  const recordedPersonal = [existing?.source, ...Object.values(existing?.copies ?? {}).map((copy) => copy?.source)]
+    .some((source) => source?.kind === 'personal-library');
+  const personalOnly = Boolean(selectedRoot) || recordedPersonal;
+  const metadata = resolvedInstallSource(name, skillshopHome(), { existing, requested: true, selectedRoot, personalOnly });
+  const managedTargets = existing ? new Set(globalTargets(name, existing).map(canonicalDestination)) : new Set();
+  const targetPairs = skillDirectories.map((skillDirectory) => {
     const targetDir = path.join(skillDirectory, name);
     assertLocalDestination(os.homedir(), targetDir, `global installation for ${name}`);
-    const result = installAt(name, requestedVersion, targetDir);
+    if (metadata.kind === 'personal') {
+      assertNoManagedSymlink(os.homedir(), targetDir, `global install destination for ${name}`);
+      assertInstallPathsDoNotOverlap(metadata.sourceDir, targetDir);
+    }
+    if (metadata.kind === 'personal' && fs.existsSync(targetDir) && !managedTargets.has(canonicalDestination(targetDir))) {
+      throw new CliError(`${targetDir} exists and is not a Skillshop-managed copy of ${name}`);
+    }
+    return { skillDirectory, targetDir };
+  });
+  for (const { skillDirectory, targetDir } of targetPairs) {
+    const result = installAt(name, requestedVersion, targetDir, metadata, os.homedir());
     const entry = globalSkills.skills[name] ?? { paths: [], copies: {} };
     entry.paths = [...new Set([...entry.paths, targetDir])];
-    entry.copies[targetDir] = { author: result.author, version: result.version };
+    entry.copies[targetDir] = {
+      ...(typeof result.author === 'string' ? { author: result.author } : {}),
+      ...(typeof result.version === 'string' ? { version: result.version } : {}),
+      ...(result.source ? { source: result.source } : {})
+    };
     globalSkills.skills[name] = entry;
     writeGlobalSkills(globalSkills);
-    console.log(`${result.updating ? 'Updated' : 'Installed'} ${name}@${result.version} at ${targetDir}`);
+    console.log(`${result.updating ? 'Updated' : 'Installed'} ${name}@${result.version ?? 'personal'} at ${targetDir}`);
   }
 }
 
@@ -1004,10 +1505,22 @@ function installLocal(name, requestedVersion, cwd) {
   const root = findLockRoot(cwd) ?? projectRoot(cwd);
   const lock = readLock(root);
   const config = readConfig();
+  const selectedRoot = selectedLibraryRoot(skillshopHome());
   const skillDirectories = localSkillDirectories(root, lock, cwd);
-  const names = [...new Set([...Object.keys(lock.skills), name, 'skillshop'])].sort();
+  const existing = lock.skills[name];
+  const recordedPersonal = existing?.source?.kind === 'personal-library';
+  const personalOnly = Boolean(selectedRoot) || recordedPersonal;
+  if (personalOnly && existing?.source && existing.source.kind !== 'personal-library' && !isLegacyBundleSource(existing.source)) {
+    throw new CliError(`${name} has an ownership record with an unknown source kind; refusing to replace it`);
+  }
+  const names = personalOnly ? [name] : [...new Set([...Object.keys(lock.skills), name, 'skillshop'])].sort();
   const installs = names.map((skillName) => {
-    const metadata = skillMetadata(skillName);
+    const metadata = resolvedInstallSource(skillName, skillshopHome(), {
+      existing: lock.skills[skillName],
+      requested: skillName === name,
+      selectedRoot,
+      personalOnly: skillName === name && personalOnly
+    });
     const targetDirs = config || !lock.skills[skillName]
       ? skillDirectories.map((directory) => path.join(directory, skillName))
       : lockedTargets(root, skillName, lock.skills[skillName]);
@@ -1019,23 +1532,29 @@ function installLocal(name, requestedVersion, cwd) {
   const requestedMetadata = installs.find(({ metadata }) => metadata.name === name).metadata;
   if (requestedVersion && requestedVersion !== requestedMetadata.version) {
     throw new CliError(
-      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${requestedMetadata.version}`
+      `${name}@${requestedVersion} is unavailable; personal skills must declare that exact version or use a bundled skill`
     );
   }
   for (const { metadata, targetDirs, previousTargets } of installs) {
     assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+    for (const targetDir of targetDirs) {
+      if (metadata.kind === 'personal') {
+        assertNoManagedSymlink(root, targetDir, `install destination for ${metadata.name}`);
+        assertInstallPathsDoNotOverlap(metadata.sourceDir, targetDir);
+      }
+    }
   }
 
   for (const { metadata, targetDirs, previousTargets } of installs) {
     const version = metadata.name === name ? requestedVersion : null;
-    const results = targetDirs.map((targetDir) => installAt(metadata.name, version, targetDir));
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, version, targetDir, metadata, root));
     for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
       fs.rmSync(staleTarget, { recursive: true, force: true });
     }
     lock.skills[metadata.name] = lockEntry(root, results);
     for (const result of results) {
       console.log(
-        `${result.updating ? 'Updated' : 'Installed'} ${result.name}@${result.version} at ${result.targetDir}`
+        `${result.updating ? 'Updated' : 'Installed'} ${result.name}@${result.version ?? 'personal'} at ${result.targetDir}`
       );
     }
   }
@@ -1102,7 +1621,10 @@ function updateLocal(requestedName, cwd, options = {}) {
   const skillDirectories = localSkillDirectories(root, lock, cwd);
 
   const updates = [...new Set(names)].sort().map((name) => {
-    const metadata = skillMetadata(name);
+    let metadata;
+    if (lock.skills[name]?.source?.kind === 'personal-library') {
+      metadata = recordedPersonalSkill(name, lock.skills[name].source);
+    } else metadata = skillMetadata(name);
     const targetDirs = config
       ? skillDirectories.map((directory) => path.join(directory, name))
       : lockedTargets(root, name, lock.skills[name]);
@@ -1111,16 +1633,22 @@ function updateLocal(requestedName, cwd, options = {}) {
   });
   for (const { metadata, targetDirs, previousTargets } of updates) {
     assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+    for (const targetDir of targetDirs) {
+      if (metadata.kind === 'personal') {
+        assertNoManagedSymlink(root, targetDir, `update destination for ${metadata.name}`);
+        assertInstallPathsDoNotOverlap(metadata.sourceDir, targetDir);
+      }
+    }
   }
 
   for (const { metadata, targetDirs, previousTargets } of updates) {
-    const results = targetDirs.map((targetDir) => installAt(metadata.name, null, targetDir));
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, null, targetDir, metadata, root));
     for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
       fs.rmSync(staleTarget, { recursive: true, force: true });
     }
     lock.skills[metadata.name] = lockEntry(root, results);
     for (const result of results) {
-      console.log(`Updated ${result.name}@${result.version} at ${result.targetDir}`);
+      console.log(`Updated ${result.name}@${result.version ?? 'personal'} at ${result.targetDir}`);
     }
   }
 
@@ -1238,8 +1766,18 @@ function refreshManagedLock(root, lock, { global = false, summary }) {
   for (const name of Object.keys(lock.skills).sort()) {
     const entry = lock.skills[name];
     try {
+      if (root && entry.source?.kind === 'personal-library') {
+        summary.unchanged += (Array.isArray(entry.paths) ? entry.paths.length : 1);
+        continue;
+      }
+      if (global && entry.paths?.length && entry.paths.every((target) => entry.copies?.[target]?.source?.kind === 'personal-library')) {
+        summary.unchanged += entry.paths.length;
+        continue;
+      }
       const metadata = skillMetadata(name);
-      const targets = global ? globalTargets(name, entry) : lockedTargets(root, name, entry);
+      const allTargets = global ? globalTargets(name, entry) : lockedTargets(root, name, entry);
+      const personalTargets = global ? allTargets.filter((target) => entry.copies?.[target]?.source?.kind === 'personal-library') : [];
+      const targets = global ? allTargets.filter((target) => !personalTargets.includes(target)) : allTargets;
       const base = global ? os.homedir() : root;
       const existingTargets = [];
       for (const target of targets) {
@@ -1248,8 +1786,13 @@ function refreshManagedLock(root, lock, { global = false, summary }) {
       }
 
       if (!existingTargets.length) {
-        delete lock.skills[name];
-        changed = true;
+        if (personalTargets.length) {
+          entry.paths = personalTargets;
+          changed = true;
+        } else {
+          delete lock.skills[name];
+          changed = true;
+        }
         continue;
       }
 
@@ -1273,7 +1816,7 @@ function refreshManagedLock(root, lock, { global = false, summary }) {
       }
 
       if (global) {
-        const keptTargets = skillFailed ? targets : successfulTargets;
+        const keptTargets = [...personalTargets, ...(skillFailed ? targets : successfulTargets)];
         entry.paths = keptTargets;
         entry.copies ??= {};
         for (const target of successfulTargets) {
@@ -1498,6 +2041,12 @@ function parseArgs(argv) {
 }
 
 function listSkills() {
+  const personalRoot = selectedLibraryRoot(skillshopHome());
+  if (personalRoot) {
+    const library = inspectPersonalLibrary(personalRoot);
+    for (const skill of library.skills) console.log(`${skill.name} — ${skill.description}`);
+    return;
+  }
   for (const name of availableSkills()) {
     const metadata = skillMetadata(name);
     console.log(`${name}@${metadata.version} — ${metadata.author}`);
@@ -1638,8 +2187,13 @@ async function main(argv) {
     return;
   }
 
-  const { positional, globalInstall, pushUpdate, requestedVersion, selectedProject, checkProject, agentsTargets } = parseArgs(argv);
+  const forceCount = argv.filter((argument) => argument === '--force').length;
+  if (forceCount > 1) throw new CliError('--force may only be specified once');
+  const parsedArgv = forceCount ? argv.filter((argument) => argument !== '--force') : argv;
+  const { positional, globalInstall, pushUpdate, requestedVersion, selectedProject, checkProject, agentsTargets } = parseArgs(parsedArgv);
   const command = positional[0];
+  const forceDownload = forceCount === 1;
+  if (forceDownload && command !== 'download') throw new CliError('--force is only valid with download');
 
   if ((selectedProject || checkProject) && command !== 'agents') {
     throw new CliError('--project and --check are only valid with agents');
@@ -1681,6 +2235,53 @@ async function main(argv) {
     return;
   }
 
+  if (command === 'library') {
+    if (requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('library commands do not accept install or update options');
+    }
+    if (positional[1] === 'init' && positional.length <= 3) {
+      const directory = positional[2] ? path.resolve(process.cwd(), positional[2]) : undefined;
+      const result = initPersonalLibrary(directory, skillshopHome(), personalLibraryTemplateRoot);
+      console.log(`Initialized personal skill library at ${result.root}`);
+      console.log(`Skills directory: ${result.skillsDirectory}`);
+      return;
+    }
+    if (positional[1] === 'list' && positional.length === 2) {
+      const result = listPersonalSkills(skillshopHome());
+      console.log(`Personal skill library: ${result.root}`);
+      if (!result.skills.length) console.log('No personal skills found.');
+      for (const skill of result.skills) console.log(`${skill.name}: ${skill.description}`);
+      return;
+    }
+    throw new CliError('use "skillshop library init [directory]" or "skillshop library list"');
+  }
+
+  if (command === 'download') {
+    if (positional.length !== 2 || requestedVersion || globalInstall || pushUpdate || selectedProject || checkProject || agentsTargets.length) {
+      throw new CliError('download expects @<owner>/<skill> [--force] and does not accept install or update options');
+    }
+    const result = downloadPersonalSkill(positional[1], {
+      stateHome: skillshopHome(),
+      templateRoot: personalLibraryTemplateRoot,
+      force: forceDownload
+    });
+    if (result.alreadyPresent) {
+      console.log(`${result.name} is already downloaded from ${result.origin.repository} at ${result.root}`);
+    } else {
+      console.log(`Downloaded ${positional[1]} from ${result.origin.repository} at ${result.origin.commit}`);
+      console.log(`Personal source: ${result.target}`);
+    }
+    return;
+  }
+
+  if (command === 'sync') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || selectedProject || checkProject || agentsTargets.length) {
+      throw new CliError('sync does not accept a skill name or install options');
+    }
+    syncPersonalCopies(process.cwd());
+    return;
+  }
+
   if (command === 'upgrade') {
     if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
       throw new CliError('upgrade does not accept arguments or options');
@@ -1763,6 +2364,17 @@ async function main(argv) {
   }
   if (pushUpdate) throw new CliError('--push is only valid with update');
 
+  if (installAliases.has(command) && (spec.includes('/') || spec.startsWith('@'))) {
+    if (requestedVersion) throw new CliError('qualified GitHub installs do not accept --version');
+    const result = downloadPersonalSkill(spec, {
+      stateHome: skillshopHome(),
+      templateRoot: personalLibraryTemplateRoot
+    });
+    if (globalInstall) installGlobal(result.name, null);
+    else installLocal(result.name, null, process.cwd());
+    return;
+  }
+
   const { name, version } = parseSkillSpec(spec, requestedVersion);
   validateSkillName(name);
   if (globalInstall) installGlobal(name, version);
@@ -1799,10 +2411,54 @@ function isUpgradeFlowInvocation(argv) {
   }
 }
 
+function isPersonalLibraryInvocation(argv) {
+  if (argv[0] === '--help' || argv[0] === '-h') return false;
+  try {
+    const args = argv.filter((argument) => argument !== '--help' && argument !== '-h' && argument !== '--force');
+    const positional = parseArgs(args).positional;
+    const command = positional[0];
+    if (command === 'library' || command === 'download' || command === 'sync') return true;
+    const remoteInstall = ['install', 'i', 'add'].includes(command) && positional.length === 2 &&
+      (positional[1].includes('/') || positional[1].startsWith('@'));
+    // Remote-reference attempts may download before installing. Do not reconcile
+    // unrelated project/global state around that operation: a failed fetch
+    // or validation error must leave those managed copies untouched as well.
+    if (remoteInstall) return true;
+    const stateHome = skillshopHome();
+    const selectionPath = path.join(stateHome, librarySelectionFileName);
+    let selectionIntent = false;
+    try {
+      // A saved selection expresses personal-mode intent even when the file is
+      // malformed, symlinked, or points at a library that has since vanished.
+      // main() remains responsible for reporting the validation error.
+      fs.lstatSync(selectionPath);
+      selectionIntent = true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') selectionIntent = true;
+    }
+    if (selectionIntent && (
+      (['list', 'ls'].includes(command) && positional.length === 1) ||
+      (['install', 'i', 'add'].includes(command) && positional.length === 2)
+    )) return true;
+    const activePersonalRoot = selectedLibraryRoot(stateHome);
+    if (!activePersonalRoot && !selectionIntent) return false;
+    if (['list', 'ls'].includes(command) && positional.length === 1) return true;
+    if (['install', 'i', 'add'].includes(command) && positional.length === 2) return true;
+    const legacyCommands = new Set([
+      'init', 'config', 'list', 'ls', 'upgrade', 'update', 'up', 'uninstall', 'remove', 'rm',
+      'agents', 'migrate', 'library', 'download', 'sync', 'help'
+    ]);
+    return positional.length === 1 && !legacyCommands.has(command);
+  } catch {
+    return false;
+  }
+}
+
 export async function runLegacyCli(argv) {
   const isolatedAgentsCommand = isIsolatedAgentsInvocation(argv);
   const upgradeFlow = isUpgradeFlowInvocation(argv);
-  const skipLegacyReconciliation = isolatedAgentsCommand || upgradeFlow;
+  const isolatedLibraryCommand = isPersonalLibraryInvocation(argv);
+  const skipLegacyReconciliation = isolatedAgentsCommand || upgradeFlow || isolatedLibraryCommand;
   try {
     if (!skipLegacyReconciliation) reconcileCurrentRepository();
     try {
@@ -1811,7 +2467,7 @@ export async function runLegacyCli(argv) {
       if (!skipLegacyReconciliation) reconcileCurrentRepository();
     }
   } catch (error) {
-    if (!(error instanceof CliError) && !(error instanceof AgentsInstructionsError)) throw error;
+    if (!(error instanceof CliError) && !(error instanceof AgentsInstructionsError) && !(error instanceof PersonalLibraryError) && !(error instanceof GitHubLibraryError)) throw error;
     console.error(`skillshop: ${error.message}`);
     process.exitCode = 1;
   }