skillshop 2.1.0 → 4.0.0

package/src/legacy-cli.js

@@ -3,10 +3,30 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { AgentsInstructionsError, applyInstructions, applyLocalFragments, composeAgentsInstructions } from './agents-instructions.js';
+import {
+  AgentsInstructionsError,
+  applyInstructions,
+  applyLocalFragments,
+  applyProjectInstructions,
+  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');
@@ -21,6 +41,12 @@ const excludeBlockStart = '# >>> skillshop managed dependencies >>>';
 const excludeBlockEnd = '# <<< skillshop managed dependencies <<<';
 const legacyExcludeBlockStart = '# >>> skillz managed dependencies >>>';
 const legacyExcludeBlockEnd = '# <<< skillz managed dependencies <<<';
+const projectTemplateDirectory = path.join('.agents', 'instructions');
+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'),
@@ -107,7 +133,9 @@ function printHelp() {
   console.log(`Usage:
   skillshop init
   skillshop config agents
-  skillshop agents [--global]
+  skillshop agents init [--project <directory>]
+  skillshop agents [--project <directory>] [--check]
+  skillshop agents --global
   skillshop <name> [--version <version>] [--global]
   skillshop install <name> [--version <version>] [--global]
   skillshop uninstall <name> [--global]
@@ -115,12 +143,32 @@ 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.
+  Plain skillshop agents keeps the bounded bundled behavior until project sources exist; afterward it renders project sources. Missing sources in an initialized project are errors.
+  skillshop agents --check reports whether generated output is current and never writes. skillshop agents --global retains user-level instruction updates.
+  The default boundary is the nearest Git/worktree root, or the current directory outside Git. --project selects another directory relative to the current working directory. Nested projects need an explicit selection.
+  Source, block, template, and output paths containing symlink components, including dangling links, are rejected.
+  Templates accept {{ include "name.block.md" }}, {{ include 'name.block.md' }}, legacy {{ fragments["name.block.md"] }}, and {{ blocks }} for unreferenced blocks. Inserted block text is literal.
+
+Upgrade:
+  skillshop upgrade updates the npm installation that supplied the CLI, then refreshes recorded Skillshop-managed copies with the newly installed CLI. skillshop init is optional and upgrade does not generate AGENTS.md files.
 
 Options:
   -g, --global             Use configured system skill directories without a project lockfile
+      --project <directory> Select the agents boundary relative to the current directory
+      --check               Check project-generated instructions without writing
       --push               Update every registered repository
   -v, --version <version>  Require an exact skill version
   -h, --help               Show this help
@@ -314,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`);
   }
 
@@ -365,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()
       }])
   );
@@ -636,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;
@@ -661,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`;
@@ -682,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] ?? {};
@@ -726,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 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) {
-  const metadata = skillMetadata(name);
+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
@@ -762,41 +1269,120 @@ 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}`);
   }
 }
 
-function nearestAgentsFile(cwd) {
-  let directory = path.resolve(cwd);
-  while (true) {
+function instructionProjectRoot(cwd, selectedProject) {
+  if (selectedProject) {
+    const selected = path.resolve(cwd, selectedProject);
+    let stats;
+    try {
+      stats = fs.statSync(selected);
+    } catch {
+      throw new CliError(`project directory does not exist: ${selected}`);
+    }
+    if (!stats.isDirectory()) throw new CliError(`project path is not a directory: ${selected}`);
+    return canonicalPath(selected);
+  }
+
+  return canonicalPath(projectRoot(cwd, { required: false }) ?? cwd);
+}
+
+function isWithinDirectory(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function nearestAgentsFile(cwd, root) {
+  const start = canonicalPath(cwd);
+  let directory = isWithinDirectory(root, start) ? start : root;
+  while (isWithinDirectory(root, directory)) {
     const candidate = path.join(directory, 'AGENTS.md');
     if (fs.existsSync(candidate)) return candidate;
-    const parent = path.dirname(directory);
-    if (parent === directory) return null;
-    directory = parent;
+    if (directory === root) break;
+    directory = path.dirname(directory);
   }
+  return path.join(root, 'AGENTS.md');
 }
 
-function installAgents(cwd, globalInstall) {
+function assertLocalInstructionSources(root, contentDirectory) {
+  assertNoInstructionSymlink(root, contentDirectory, 'local instruction source directory');
+  if (!fs.existsSync(contentDirectory)) return;
+  for (const entry of fs.readdirSync(contentDirectory, { withFileTypes: true })) {
+    if (entry.name.endsWith('.block.md')) {
+      const sourcePath = path.join(contentDirectory, entry.name);
+      const label = `local instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+}
+
+function assertNoInstructionSymlink(root, target, label) {
+  const boundary = path.resolve(root);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside the project`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function installAgents(cwd, globalInstall, selectedProject) {
   const composed = composeAgentsInstructions(agentsContentRoot);
   const targetPaths = [];
+  const root = globalInstall ? null : instructionProjectRoot(cwd, selectedProject);
   if (globalInstall) {
     targetPaths.push(...globalAgentsTargets.map((target) => path.join(os.homedir(), target)));
   } else {
-    const targetPath = nearestAgentsFile(cwd);
-    if (!targetPath) {
-      console.log(`No AGENTS.md found at or above ${cwd}`);
-      return;
-    }
+    const targetPath = nearestAgentsFile(cwd, root);
+    assertLocalDestination(root, targetPath, 'local agents instructions');
+    assertNoInstructionSymlink(root, targetPath, 'local agents instructions');
+    assertLocalInstructionSources(root, path.dirname(targetPath));
     targetPaths.push(targetPath);
   }
 
@@ -824,14 +1410,117 @@ function installAgents(cwd, globalInstall) {
   }
 }
 
+function projectInstructionPaths(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const templatePath = path.join(sourceDirectory, projectTemplateName);
+  const outputPath = path.join(root, 'AGENTS.md');
+  const paths = [
+    [sourceDirectory, 'project instruction source directory'],
+    [templatePath, 'project instruction template'],
+    [outputPath, 'project agents output']
+  ];
+  for (const [target, label] of paths) {
+    assertLocalDestination(root, target, label);
+    assertNoInstructionSymlink(root, target, label);
+  }
+
+  if (fs.existsSync(sourceDirectory) && !fs.statSync(sourceDirectory).isDirectory()) {
+    throw new CliError(`project instruction source path is not a directory: ${sourceDirectory}`);
+  }
+  if (fs.existsSync(templatePath) && !fs.statSync(templatePath).isFile()) {
+    throw new CliError(`project instruction template is not a file: ${templatePath}`);
+  }
+  if (fs.existsSync(outputPath) && !fs.statSync(outputPath).isFile()) {
+    throw new CliError(`project agents output is not a file: ${outputPath}`);
+  }
+  if (fs.existsSync(sourceDirectory)) {
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.name.endsWith('.block.md')) continue;
+      const sourcePath = path.join(sourceDirectory, entry.name);
+      const label = `project instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+
+  return { root, sourceDirectory, templatePath, outputPath };
+}
+
+function renderProjectAgents(cwd, selectedProject, { initialize = false, check = false } = {}) {
+  let paths = projectInstructionPaths(cwd, selectedProject);
+  if (initialize) {
+    fs.mkdirSync(paths.sourceDirectory, { recursive: true });
+    if (!fs.existsSync(paths.templatePath)) {
+      fs.writeFileSync(paths.templatePath, defaultProjectTemplate);
+    }
+    paths = projectInstructionPaths(cwd, selectedProject);
+  }
+
+  if (!fs.existsSync(paths.templatePath)) {
+    throw new CliError(`project instruction template is missing; run "skillshop agents init" first: ${paths.templatePath}`);
+  }
+
+  const composed = composeAgentsInstructions(paths.sourceDirectory, projectTemplateName).content;
+  const existing = fs.existsSync(paths.outputPath) ? fs.readFileSync(paths.outputPath, 'utf8') : '';
+  const planned = applyProjectInstructions(existing, composed, packageJson.version);
+
+  if (check) {
+    if (fs.existsSync(paths.outputPath) && planned.text === existing) {
+      console.log(`Project agents instructions are current at ${paths.outputPath}`);
+      return;
+    }
+    console.error(
+      `Project agents instructions are ${fs.existsSync(paths.outputPath) ? 'stale' : 'missing'} at ${paths.outputPath}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (planned.text === existing) {
+    console.log(`Project agents instructions already current at ${paths.outputPath}`);
+    return;
+  }
+  fs.writeFileSync(paths.outputPath, planned.text);
+  console.log(`${planned.action === 'refreshed' ? 'Refreshed' : 'Rendered'} project agents instructions at ${paths.outputPath}`);
+}
+
+function projectAgentsConfigured(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const outputPath = path.join(root, 'AGENTS.md');
+  for (const candidate of [sourceDirectory, outputPath]) {
+    try {
+      const stat = fs.lstatSync(candidate);
+      if (candidate === sourceDirectory) return true;
+      if (stat.isFile() && hasProjectInstructions(fs.readFileSync(candidate, 'utf8'))) return true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return false;
+}
+
 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]);
@@ -843,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}`
       );
     }
   }
@@ -926,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]);
@@ -935,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}`);
     }
   }
 
@@ -983,6 +1687,223 @@ function updateAllRepositories() {
   console.log(`Updated ${retained.length} registered ${retained.length === 1 ? 'repository' : 'repositories'}`);
 }
 
+function assertNoManagedSymlink(base, target, label) {
+  const boundary = path.resolve(base);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside its managed root`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function replaceManagedSkillDirectory(sourceDir, targetDir) {
+  const temporaryDir = `${targetDir}.skillshop-upgrade-tmp-${process.pid}`;
+  const backupDir = `${targetDir}.skillshop-upgrade-backup-${process.pid}`;
+  fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.rmSync(backupDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
+
+  const hadTarget = fs.existsSync(targetDir);
+  if (hadTarget) fs.renameSync(targetDir, backupDir);
+  try {
+    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 upgradeSummary() {
+  return { updated: 0, unchanged: 0, missing: 0, failed: [] };
+}
+
+function validateManagedCopy(root, target, name) {
+  assertNoManagedSymlink(root, target, `managed ${name} copy`);
+  let targetStats;
+  try {
+    targetStats = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!targetStats.isDirectory()) throw new CliError(`${target} is not a managed skill directory`);
+
+  const manifestPath = path.join(target, 'SKILL.md');
+  assertNoManagedSymlink(root, manifestPath, `managed ${name} manifest`);
+  let manifestStats;
+  try {
+    manifestStats = fs.lstatSync(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new CliError(`${manifestPath} is missing from a recorded skill copy`);
+    throw error;
+  }
+  if (!manifestStats.isFile()) throw new CliError(`${manifestPath} is not a regular skill manifest`);
+  return true;
+}
+
+function refreshManagedLock(root, lock, { global = false, summary }) {
+  let changed = false;
+  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 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) {
+        if (validateManagedCopy(base, target, name)) existingTargets.push(target);
+        else summary.missing += 1;
+      }
+
+      if (!existingTargets.length) {
+        if (personalTargets.length) {
+          entry.paths = personalTargets;
+          changed = true;
+        } else {
+          delete lock.skills[name];
+          changed = true;
+        }
+        continue;
+      }
+
+      const successfulTargets = [];
+      let skillFailed = false;
+      for (const target of existingTargets) {
+        const recordedVersion = global ? entry.copies?.[target]?.version : entry.version;
+        if (recordedVersion === metadata.version) {
+          summary.unchanged += 1;
+          successfulTargets.push(target);
+          continue;
+        }
+        try {
+          replaceManagedSkillDirectory(metadata.sourceDir, target);
+          summary.updated += 1;
+          successfulTargets.push(target);
+        } catch (error) {
+          summary.failed.push(`${name} at ${target}: ${error.message}`);
+          skillFailed = true;
+        }
+      }
+
+      if (global) {
+        const keptTargets = [...personalTargets, ...(skillFailed ? targets : successfulTargets)];
+        entry.paths = keptTargets;
+        entry.copies ??= {};
+        for (const target of successfulTargets) {
+          const previous = entry.copies[target] ?? {};
+          entry.copies[target] = { ...previous, author: metadata.author, version: metadata.version };
+        }
+        if (!skillFailed) changed = true;
+        if (!entry.paths.length) {
+          delete lock.skills[name];
+          changed = true;
+        }
+      } else if (!skillFailed) {
+        entry.paths = successfulTargets.map((target) => relativePath(root, target)).sort();
+        entry.author = metadata.author;
+        entry.version = metadata.version;
+        changed = true;
+      } else if (existingTargets.length !== targets.length) {
+        entry.paths = existingTargets.map((target) => relativePath(root, target)).sort();
+        changed = true;
+      }
+    } catch (error) {
+      summary.failed.push(`${name}: ${error.message}`);
+    }
+  }
+
+  if (changed) {
+    try {
+      if (global) writeGlobalSkills(lock);
+      else writeLock(root, lock);
+    } catch (error) {
+      summary.failed.push(`could not save ${global ? 'global skill manifest' : path.join(root, lockFileName)}: ${error.message}`);
+    }
+  }
+}
+
+function refreshManagedCopies(scope) {
+  const summary = upgradeSummary();
+  if (scope === 'local') {
+    const owner = localPackageOwner();
+    if (!owner) {
+      summary.failed.push('fresh Skillshop package is no longer attached to a local npm dependency');
+    } else {
+      try {
+        const lock = readLock(owner.root);
+        refreshManagedLock(owner.root, lock, { summary });
+      } catch (error) {
+        summary.failed.push(`${owner.root}: ${error.message}`);
+      }
+    }
+  } else if (scope === 'global') {
+    try {
+      const globalLock = readGlobalSkills();
+      refreshManagedLock(null, globalLock, { global: true, summary });
+    } catch (error) {
+      summary.failed.push(`global managed copies: ${error.message}`);
+    }
+
+    try {
+      const registry = readRegistry();
+      for (const root of registry.repositories) {
+        if (!hasLock(root)) continue;
+        try {
+          const lock = readLock(root);
+          refreshManagedLock(root, lock, { summary });
+        } catch (error) {
+          summary.failed.push(`${root}: ${error.message}`);
+        }
+      }
+    } catch (error) {
+      summary.failed.push(`registered project copies: ${error.message}`);
+    }
+  } else {
+    summary.failed.push(`unsupported managed-copy scope: ${scope}`);
+  }
+
+  console.log(
+    `Managed-copy refresh summary: ${summary.updated} updated, ${summary.unchanged} unchanged, ${summary.missing} missing paths pruned, ${summary.failed.length} failed.`
+  );
+  if (summary.failed.length) {
+    for (const failure of summary.failed) console.error(`skillshop: upgrade refresh: ${failure}`);
+    console.error('skillshop: npm upgrade succeeded, but managed-copy refresh was incomplete');
+    process.exitCode = 1;
+  } else {
+    console.log(`Refreshed Skillshop-managed copies for ${scope} scope.`);
+  }
+}
+
 const migrationSkipDirectories = new Set([
   '.git',
   '.skillshop',
@@ -1074,6 +1995,8 @@ function parseArgs(argv) {
   let pushUpdate = false;
   const agentsTargets = [];
   let requestedVersion = null;
+  let selectedProject = null;
+  let checkProject = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
@@ -1081,6 +2004,15 @@ function parseArgs(argv) {
       globalInstall = true;
     } else if (argument === '--push') {
       pushUpdate = true;
+    } else if (argument === '--check') {
+      checkProject = true;
+    } else if (argument === '--project') {
+      selectedProject = argv[index + 1];
+      if (!selectedProject) throw new CliError('--project requires a directory');
+      index += 1;
+    } else if (argument.startsWith('--project=')) {
+      selectedProject = argument.slice('--project='.length);
+      if (!selectedProject) throw new CliError('--project requires a directory');
     } else if (argument === '--codex' || argument === '--copilot') {
       throw new CliError(`${argument} is no longer supported; use agents --global`);
     } else if (argument === '--version' || argument === '-v') {
@@ -1097,18 +2029,152 @@ function parseArgs(argv) {
     }
   }
 
-  return { positional, globalInstall, pushUpdate, requestedVersion, agentsTargets: [...new Set(agentsTargets)] };
+  return {
+    positional,
+    globalInstall,
+    pushUpdate,
+    requestedVersion,
+    selectedProject,
+    checkProject,
+    agentsTargets: [...new Set(agentsTargets)]
+  };
 }
 
 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}`);
   }
 }
 
+function packageDependencySection(manifest) {
+  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    if (Object.hasOwn(manifest?.[section] ?? {}, 'skillshop')) return section;
+  }
+  return null;
+}
+
+function localPackageOwner() {
+  const installedPackageRoot = canonicalPath(packageRoot);
+  let current = path.dirname(installedPackageRoot);
+  while (true) {
+    const manifestPath = path.join(current, 'package.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const section = packageDependencySection(manifest);
+        const declaredInstall = path.join(current, 'node_modules', 'skillshop');
+        if (section && fs.existsSync(declaredInstall) && canonicalPath(declaredInstall) === installedPackageRoot) {
+          return { root: current, section };
+        }
+      } catch (error) {
+        if (error instanceof SyntaxError) throw new CliError(`cannot parse ${manifestPath}: ${error.message}`);
+        throw error;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function npmGlobalRoot() {
+  try {
+    return path.resolve(execFileSync('npm', ['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim());
+  } catch (error) {
+    const detail = error.stderr?.toString().trim();
+    throw new CliError(`cannot determine the active npm global package directory${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+function npmPrefixFromRoot(globalRoot) {
+  const parent = path.dirname(globalRoot);
+  return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
+}
+
+function resolveUpgradeScope() {
+  const localOwner = localPackageOwner();
+  if (localOwner) return { type: 'local', root: localOwner.root, dependencySection: localOwner.section, packageRoot };
+
+  const insideNodeModules = canonicalPath(packageRoot).split(path.sep).includes('node_modules');
+  const activeGlobalRoot = npmGlobalRoot();
+  if (canonicalPath(path.join(activeGlobalRoot, 'skillshop')) === canonicalPath(packageRoot)) {
+    return { type: 'global', prefix: npmPrefixFromRoot(activeGlobalRoot), packageRoot };
+  }
+  if (insideNodeModules) {
+    throw new CliError(
+      `cannot match this installed Skillshop package to the active npm global prefix (${activeGlobalRoot}); no upgrade was run`
+    );
+  }
+
+  // Preserve the historical source-checkout behavior: install the package into
+  // the active npm global prefix without editing the checkout's package files.
+  return { type: 'global-checkout', packageRoot };
+}
+
+function runUpgradeInstall(scope) {
+  const args = scope.type === 'local'
+    ? ['install', `--save-${scope.dependencySection === 'dependencies' ? 'prod' : scope.dependencySection === 'devDependencies' ? 'dev' : scope.dependencySection === 'optionalDependencies' ? 'optional' : 'peer'}`, 'skillshop@latest']
+    : scope.type === 'global'
+      ? ['install', '--global', '--prefix', scope.prefix, 'skillshop@latest']
+      : ['install', '--global', 'skillshop@latest'];
+  try {
+    execFileSync('npm', args, {
+      cwd: scope.type === 'local' ? scope.root : process.cwd(),
+      stdio: 'inherit'
+    });
+  } catch (error) {
+    const status = Number.isInteger(error.status) ? ` (exit ${error.status})` : '';
+    throw new CliError(`npm upgrade failed${status}; managed copies were not refreshed`);
+  }
+}
+
+function freshUpgradePackageRoot(scope) {
+  if (scope.type !== 'global-checkout') return scope.packageRoot;
+  return path.join(npmGlobalRoot(), 'skillshop');
+}
+
 function upgrade() {
-  execFileSync('npm', ['install', '--global', 'skillshop'], { stdio: 'inherit' });
+  const scope = resolveUpgradeScope();
+  const scopeLabel = scope.type === 'local'
+    ? `project dependency in ${scope.root}`
+    : scope.type === 'global'
+      ? `global installation at ${scope.packageRoot}`
+      : 'global installation (source-checkout compatibility mode)';
+  console.log(`Upgrading Skillshop ${scopeLabel}...`);
+  runUpgradeInstall(scope);
+
+  let freshCliPath;
+  try {
+    freshCliPath = path.join(freshUpgradePackageRoot(scope), 'src', 'cli.js');
+    if (!fs.statSync(freshCliPath).isFile()) throw new Error('not a file');
+  } catch {
+    throw new CliError('npm upgrade succeeded, but the newly installed Skillshop CLI could not be found for managed-copy refresh');
+  }
+
+  const child = spawnSync(process.execPath, [freshCliPath, internalUpgradeRefreshCommand], {
+    cwd: scope.type === 'local' ? scope.root : process.cwd(),
+    env: {
+      ...process.env,
+      SKILLSHOP_INTERNAL_UPGRADE_TOKEN: internalUpgradeRefreshToken,
+      SKILLSHOP_INTERNAL_UPGRADE_SCOPE: scope.type === 'local' ? 'local' : 'global'
+    },
+    stdio: 'inherit'
+  });
+  if (child.error) {
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh could not start: ${child.error.message}`);
+  }
+  if (child.status !== 0) {
+    const status = child.status === null ? 'without an exit status' : `with exit ${child.status}`;
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh failed ${status}`);
+  }
 }
 
 async function main(argv) {
@@ -1121,8 +2187,29 @@ async function main(argv) {
     return;
   }
 
-  const { positional, globalInstall, pushUpdate, requestedVersion, 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');
+  }
+
+  if (command === internalUpgradeRefreshCommand) {
+    if (
+      process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN !== internalUpgradeRefreshToken ||
+      positional.length !== 1 ||
+      requestedVersion || globalInstall || pushUpdate || selectedProject || checkProject || agentsTargets.length
+    ) {
+      throw new CliError('invalid internal upgrade continuation');
+    }
+    refreshManagedCopies(process.env.SKILLSHOP_INTERNAL_UPGRADE_SCOPE);
+    return;
+  }
 
   if (command === 'init') {
     if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
@@ -1148,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');
@@ -1178,10 +2312,32 @@ async function main(argv) {
   }
 
   if (command === 'agents') {
-    if (positional.length !== 1 || requestedVersion || pushUpdate) {
+    const initializeProject = positional.length === 2 && positional[1] === 'init';
+    if (
+      positional.length > 2 ||
+      (positional.length === 2 && !initializeProject) ||
+      requestedVersion ||
+      pushUpdate ||
+      agentsTargets.length
+    ) {
       throw new CliError('agents does not accept skill or update options');
     }
-    installAgents(process.cwd(), globalInstall);
+    if (globalInstall) {
+      if (initializeProject || selectedProject || checkProject) {
+        throw new CliError('--global cannot be combined with project agents options');
+      }
+      installAgents(process.cwd(), true);
+      return;
+    }
+    if (initializeProject && checkProject) throw new CliError('agents init does not accept --check');
+    if (initializeProject || checkProject || projectAgentsConfigured(process.cwd(), selectedProject)) {
+      renderProjectAgents(process.cwd(), selectedProject, {
+        initialize: initializeProject,
+        check: checkProject
+      });
+    } else {
+      installAgents(process.cwd(), false, selectedProject);
+    }
     return;
   }
 
@@ -1208,22 +2364,110 @@ 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);
   else installLocal(name, version, process.cwd());
 }
 
+function isIsolatedAgentsInvocation(argv) {
+  // Preserve the top-level help/version routing before looking for a command.
+  // main() handles help anywhere and the standalone version form without parsing.
+  if (argv[0] === '--help' || argv[0] === '-h') return false;
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) return false;
+
+  // parseArgs accepts project options on either side of the command. Ignore help
+  // flags here because main() handles them before parsing, then classify using
+  // the same positional-command rules as execution.
+  try {
+    const args = argv.filter((argument) => argument !== '--help' && argument !== '-h');
+    return parseArgs(args).positional[0] === 'agents';
+  } catch {
+    return false;
+  }
+}
+
+function isUpgradeFlowInvocation(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return false;
+  if (
+    argv[0] === internalUpgradeRefreshCommand &&
+    process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN === internalUpgradeRefreshToken
+  ) return true;
+  try {
+    return parseArgs(argv).positional[0] === 'upgrade';
+  } catch {
+    return false;
+  }
+}
+
+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 isolatedLibraryCommand = isPersonalLibraryInvocation(argv);
+  const skipLegacyReconciliation = isolatedAgentsCommand || upgradeFlow || isolatedLibraryCommand;
   try {
-    reconcileCurrentRepository();
+    if (!skipLegacyReconciliation) reconcileCurrentRepository();
     try {
       await main(argv);
     } finally {
-      reconcileCurrentRepository();
+      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;
   }