skillshop 2.2.0 → 4.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skillshop",
-  "version": "2.2.0",
-  "description": "Build, export, resolve, and install portable agent skill libraries",
+  "version": "4.1.0",
+  "description": "Install and sync agent skills from personal folder libraries",
   "type": "module",
   "bin": {
     "skillshop": "./src/cli.js",
@@ -13,11 +13,15 @@
     "./export": "./src/export.js",
     "./import": "./src/import.js",
     "./user-install": "./src/user-install.js",
-    "./specifier": "./src/specifier.js"
+    "./specifier": "./src/specifier.js",
+    "./dependencies": "./src/dependencies.js",
+    "./installation-state": "./src/installation-state.js"
   },
   "files": [
     "agents-content/",
     "skills-content/",
+    "templates/",
+    "docs/",
     "src/",
     "README.md"
   ],

package/skills-content/skillshop/SKILL.md

@@ -1,21 +1,56 @@
 ---
 name: skillshop
-description: Manage repository-local agent skills, Skillshop upgrades, and project agent instructions. Use when a repository has a .skillshop-lock or the user asks to install, uninstall, pin, list, update, or upgrade Skillshop-managed copies, or initialize, render, or check project AGENTS.md instructions.
+description: Manage personal folder skill libraries, GitHub skill downloads, owned-copy sync, repository-local agent skills, Skillshop upgrades, and project agent instructions. Use when the user asks to initialize or list a personal library, download or install @owner/skill, install a bare personal skill name, sync personal sources, manage Skillshop copies, upgrade Skillshop, or initialize, render, or check project AGENTS.md instructions.
 metadata:
   author: Daniel Fosco
-  version: "2026.10.23"
+  version: "2026.10.28.1"
 ---
 
-# Skillshop — Local Skill Registry
+# Skillshop — Personal Skill Libraries and Local Registry
 
-Use the `skillshop` CLI to manage skills in this repository. The project-root `.skillshop-lock` is the source of truth for which skill directories are managed by skillshop; directories absent from the lock belong to the project or another installer.
+Use the `skillshop` CLI to manage personal folder libraries and their recorded installed copies. A personal library is the source of truth for user-authored skills; each destination skills directory contains a `.skillshop-lock` ownership manifest for its installed copies. Project-root `skillshop.json` and `skillshop-lock.json` separately declare and lock reproducible project dependencies. Directories absent from ownership records belong to the project or another installer.
+
+## Personal folder libraries
+
+```bash
+skillshop library init                 # selects ~/skillshop-library
+skillshop library init ./my-skills     # creates or adopts an existing folder
+skillshop library list
+skillshop download @alice/review       # adds source without installing
+skillshop install @alice/review        # downloads if missing, then installs locally
+skillshop install @alice/review --global
+skillshop install review               # installs an existing selected source
+skillshop sync                         # syncs all recorded personal copies
+```
+
+The library is an ordinary folder. It needs no `package.json`, npm author metadata, build step, or version field. `skillshop library init` selects the visible default `~/skillshop-library` or creates/adopts the explicit directory. It preserves existing library skills and config. `skillshop library list` shows the selected source folder.
+
+The plain `skillshop-library.json` config names a relative `skillsDirectory` (default `skills`). Each skill is a directory with `SKILL.md` declaring `name` and `description`; references, scripts, hidden files, binary assets, and executable modes are included in the full directory.
+
+`skillshop download @owner/skill` fetches `https://github.com/owner/skillshop-library.git` and adds only the requested `skills/skill` directory to the personal library. The leading `@` marks remote syntax and is stripped from the GitHub owner; the repository URL contains no `@`. Unprefixed `owner/skill` inputs are rejected. Download does not install the skill. Same-name authored or different-source collisions fail. `skillshop download @owner/skill --force` explicitly replaces that source after validating the remote tree. `skillshop install @owner/skill` downloads only when the source is absent. An existing same-origin source, including local edits, is reused without an upstream fetch. `skillshop install name` uses a bare name for a source already in the selected personal library.
+
+`skillshop sync` updates copies recorded as personal-library installs and is the explicit migration step for tracked legacy bundled copies. It compares and copies the complete source tree, including path and mode changes, repairs edits made inside an installed copy, and removes stale extras inside that owned skill directory. It uses the source root recorded at install time, even after another library is selected. Sync does not fetch upstream. `skillshop library init` never migrates. For a tracked bundle copy, an existing selected-library source wins. If the source is missing, it is imported only when every surviving tracked project and global copy agrees in paths, bytes, and modes. Divergence, unknown source kinds, unreadable ownership state, unmanaged directories, and package-import snapshots are preserved and reported. A missing personal source reports an error and preserves existing destinations. Missing destinations are pruned from their ownership records and are not recreated. Keep durable edits in the personal source; sync replaces edits made in its owned installed copies.
 
 This registry is hand-maintained. `metadata.author` is original-author attribution, not ownership. The user can adapt skills locally. skillshop does not read other installers' state or update their skills; the user resolves name collisions.
 
-Every non-`agents` invocation, including help, version, and failed commands, reconciles the current project's lockfile, registration, and Git exclusions, except `skillshop upgrade`. Agent instruction commands also bypass reconciliation. Upgrade skips the old process's pre/post reconciliation, installs the npm package first, then starts the installed CLI in a fresh process to refresh only changed-version copies recorded in Skillshop's project/global ownership files. A failed npm install must not touch managed copies; report any partial copy refresh and return failure. Never adopt unmanaged directories or package-import snapshots, and do not recreate deleted paths. Reconciliation removes missing installation paths and stale repository registrations. Tracked installed frontmatter is repaired without replacing bodies or extra fields: names match directory names, author/version use the installation record, and missing descriptions use the bundled skill. Incomplete records fall back to installed or bundled metadata. Valid files are not rewritten. Invalid lockfiles, unsafe paths, and unsupported frontmatter must be reported, not discarded. Do not silently untrack Git files; that remains an explicit migration operation.
+Most ordinary non-agent commands reconcile the current project's lockfile, registration, and Git exclusions. Personal library, download, qualified install, sync, upgrade, and agent-instruction commands bypass that legacy reconciliation. In personal mode, `skillshop list` and named installs also bypass it. Upgrade installs the npm package first, then starts the installed CLI in a fresh process to refresh changed-version bundled copies recorded in Skillshop's project/global ownership files. Personal-source copies are excluded from bundled refresh. A failed npm install must not touch managed copies; report any partial copy refresh and return failure. Never adopt unmanaged directories or package-import snapshots, and do not recreate deleted paths. Reconciliation removes missing installation paths and stale repository registrations. Tracked bundled installed frontmatter is repaired without replacing bodies or extra fields. Invalid lockfiles, unsafe paths, and unsupported frontmatter must be reported, not discarded. Do not silently untrack Git files; that remains an explicit migration operation.
 
 `skillshop init` is optional for upgrade. It configures agent destinations but does not install the npm package or refresh managed skill copies. Upgrade never generates or edits `AGENTS.md` files or project instruction templates.
 
+## Project skill dependencies
+
+```bash
+skillshop dependency add @alice/review@v1.2.0
+skillshop dependency install
+skillshop install
+skillshop ci
+skillshop dependency remove review
+```
+
+`dependency add` declares a GitHub skill in project-root `skillshop.json` and resolves its tag, branch or commit into an exact commit and complete-tree SHA-256 integrity in `skillshop-lock.json`. Commit both files. `skillsDirectory` defaults to `.agents/skills` and is project-owned, independent of user agent selection. Restore reuses the locked commit even when upstream refs move. `ci` and `install --frozen-lockfile` refuse missing/stale locks. These operations bypass personal libraries and unrelated legacy state. Dependency copies are not changed by personal sync, named update or CLI upgrade. Use npm's own lockfile for npm-distributed package dependencies.
+
+All installers record/check ownership in the destination `.skillshop-lock`; unmanaged/foreign-owned collisions must fail. Package updates prune removed declarations only for that same package owner. Import `--force` authorizes replacement of the same package-import owner, not adoption of arbitrary directories.
+
 ## Configure agents
 
 ```bash
@@ -66,7 +101,7 @@ For npm consumers, declare explicit scripts rather than relying on an install ho
 
 Commit the template and block sources together with the rendered root `AGENTS.md`; commit `package.json` and the npm lockfile when Skillshop is a development dependency. Run `npm run agents:check` in CI to detect stale or missing generated output.
 
-## Install a skill
+## Install a bundled skill when no personal library is selected
 
 Run commands from anywhere inside the repository:
 
@@ -77,7 +112,7 @@ skillshop i <name>
 skillshop add <name>
 ```
 
-The CLI installs the full skill package into every configured project path, refreshes every skill already listed in `.skillshop-lock`, and updates the lockfile. Changing the configured agents migrates managed local copies on the next install or update. Local installs are recorded in `~/.skillshop/repositories.json`; `.skillshop-lock` and its managed skill paths are added to the repository's Git `info/exclude`.
+Without a selected personal library, the CLI installs the full skill package into every configured project path, refreshes every skill already listed in `.skillshop-lock`, and updates the lockfile. Changing the configured agents migrates managed local copies on the next install or update. Local installs are recorded in `~/.skillshop/repositories.json`; destination `.skillshop-lock` files and their managed skill paths are added to the repository's Git `info/exclude`. With a personal library selected, `skillshop list` and unqualified named installs use that library only; they do not reconcile bundled copies or add bundled `skillshop` guidance.
 
 To require the exact version currently available from the local registry:
 
@@ -88,7 +123,7 @@ skillshop install <name> --version <version>
 skillshop <name> --global
 ```
 
-`--global` (or `-g`) installs into every configured system skill path without a project lockfile. Installs are recorded in `~/.skillshop/global-skills.json`. Except for `skillshop upgrade`, ordinary commands other than `skillshop agents` can repair their frontmatter and prune missing paths. Agent-instruction commands bypass that reconciliation. `skillshop upgrade` instead refreshes recorded global and registered project copies only after npm succeeds and a fresh CLI starts. Same-version copies keep local body edits; a changed-version refresh replaces the managed copy and overwrites local edits. Older installs are recorded on explicit reinstall; do not adopt other global skills. Global copies are not migrated when the agent setting changes, so remove unwanted global skills before reconfiguration. The local registry contains one current version per skill. `--version` (or `-v`) is an exact compatibility check; do not claim that an unavailable historical version can be resolved.
+`--global` (or `-g`) installs into every configured system skill path without a project lockfile. Ownership is recorded in `.skillshop-lock` inside each global skills directory. For bundled tracked installs, most ordinary commands can repair frontmatter and prune missing paths. Personal library, download, qualified install, sync, upgrade, and agent-instruction commands bypass that legacy reconciliation. In personal mode, `skillshop list` and named installs bypass it too. `skillshop upgrade` refreshes recorded bundled global and registered project copies only after npm succeeds and a fresh CLI starts. Same-version bundled copies keep local body edits; a changed-version refresh replaces that managed copy and overwrites its local edits. For durable personal edits, select a folder library, use explicit sync to adopt agreeing tracked copies, and edit the library source. Personal-library copies are excluded from bundled refresh. Explicit `skillshop sync` never scans untracked directories. Global copies are not migrated when the agent setting changes, so remove unwanted global skills before reconfiguration. The local registry contains one current version per skill. `--version` (or `-v`) is an exact compatibility check; do not claim that an unavailable historical version can be resolved.
 
 ## Update managed skills
 
@@ -101,7 +136,7 @@ skillshop update --push
 skillshop up --push
 ```
 
-`update` with no name replaces every skill listed in the current repository's `.skillshop-lock` and updates its locked metadata. A name updates only that managed skill. `--push` updates every centrally registered repository and cannot be combined with a skill name. Updates and installs replace local edits; keep edits in the registry if they should survive these operations. Global installs cannot be updated with this command; reinstall them by name with `--global`.
+`update` with no name replaces every skill listed in the current repository's directory-local ownership manifests and updates its locked metadata. A name updates only that managed skill. `--push` updates every centrally registered repository and cannot be combined with a skill name. Updates and installs replace local edits; keep edits in the registry if they should survive these operations. Global installs cannot be updated with this command; reinstall them by name with `--global`.
 
 ## Upgrade Skillshop
 
@@ -111,7 +146,7 @@ skillshop upgrade
 
 Upgrade targets the npm installation that supplied the invoked CLI. A local npm dependency updates in its owning project and stays in its existing dependency section; only that project's locked Skillshop copies are refreshed. A global npm installation updates its active prefix and refreshes recorded global copies plus copies in registered projects without changing those projects' npm manifests. A source checkout retains the compatibility behavior of installing Skillshop globally, without editing the checkout's `package.json`.
 
-After npm succeeds, the new package's CLI starts in a fresh process. It replaces existing recorded copies only when the bundled skill version changed, preserving local bodies for same-version copies. Changed-version replacement overwrites local edits in that managed copy; make durable changes in the bundled skill source. Missing paths are pruned from records rather than recreated. Unmanaged skills and imported snapshots remain untouched. Install failure prevents refresh; refresh failure reports the npm stage as successful and returns nonzero with a partial-result summary. Upgrade does not run agent initialization or project instruction generation.
+After npm succeeds, the new package's CLI starts in a fresh process. It migrates valid legacy project-root and global ownership records to destination manifests before refreshing skills, even when versions are unchanged. Old records are removed only after replacement manifests are saved. Conflicting, malformed or unsafe state is preserved and reported. It replaces existing recorded copies only when the bundled skill version changed, preserving local bodies for same-version copies. Changed-version replacement overwrites local edits in that managed copy. For durable personal edits, select a library, explicitly sync to adopt agreeing tracked copies, then edit the library source and sync. Missing paths are pruned from records rather than recreated. Unmanaged skills and imported snapshots remain untouched. Install failure prevents refresh; refresh failure reports the npm stage as successful and returns nonzero with a partial-result summary. Upgrade does not run agent initialization or project instruction generation.
 
 ## Migrate existing repositories
 
@@ -132,7 +167,7 @@ skillshop rm <name>
 skillshop uninstall <name> --global
 ```
 
-Local uninstall removes every managed copy of the named directory only when it is listed in `.skillshop-lock`, then removes its lock entry. It must leave unlisted directories alone. Later updates honor the remaining lock entries and do not restore an uninstalled skill. Use `--global` to explicitly remove the same name from the configured system paths and clear corresponding global records.
+Local uninstall removes every managed copy of the named directory only when it is listed in `.skillshop-lock`, then removes its lock entry. It must leave unlisted directories alone. Later updates honor the remaining lock entries and do not restore an uninstalled skill. Global uninstall also requires CLI ownership; it must preserve application-owned and unmanaged skills. Use `dependency remove` for dependency-owned copies.
 
 ## Inspect the registry and CLI
 
@@ -152,6 +187,6 @@ skillshop -h
 - Do not manually add unrelated skills to `.skillshop-lock`.
 - Do not remove or overwrite unlisted skill directories.
 - Installed copies can be edited, but installs and updates replace them. Preserve durable edits in the registry.
-- Do not add lock-managed skill directories or `.skillshop-lock` to Git; they are locally excluded dependencies.
-- Global installation with `skillshop <name> --global` writes to the configured system paths and records only skillshop's own installs in `~/.skillshop/global-skills.json`.
+- Do not add lock-managed skill directories or `.skillshop-lock` to Git; they are local installation state. Commit `skillshop.json` and `skillshop-lock.json` when using project dependencies.
+- Global installation with `skillshop <name> --global` writes to the configured system paths and records ownership in each destination skills directory's `.skillshop-lock`.
 - Use `skillshop list` to inspect available local-registry names, versions, and authors.

package/src/cli.js

@@ -8,25 +8,34 @@ import { importSkill, resolveSkill } from './import.js';
 import { installDeclaredUserSkills } from './user-install.js';
 import { reconcileLegacyState, runLegacyCli } from './legacy-cli.js';
 import { parseLibrarySkillReference, skillName } from './specifier.js';
+import { addDependency, installDependencies, removeDependency, updateDependencies } from './dependencies.js';
 
 function help() {
   console.log(`
-Library commands:
+Personal folder library commands:
 
-  skillshop library init
+  skillshop library init [directory]
   skillshop library list
-  skillshop export skill:<name> <directory>
-  skillshop export skill:<name> --from <package> [--skill skill:<source-name>]
-  skillshop unexport skill:<name>
-  skillshop validate
-  skillshop build
-  skillshop resolve <library>:<skill>
-  skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
-  skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
+  skillshop download @<owner>/<skill> [--force]
+  skillshop install @<owner>/<skill> [--global]
+  skillshop install <name> [--global]
+  skillshop sync
 
-A library publishes skills by portable specifier, for example skill:review.
-Import uses the short <library>:<skill> form and copies to .agents/skills/<skill> by default.
---global copies to ~/.agents/skills/<skill> and replaces an existing directory.`);
+Create or select a source folder with skillshop library init. Download @owner/skill adds a GitHub skill to that folder without installing it.
+Install @owner/skill downloads when needed, then installs the complete source tree. Bare install names use the selected personal library. Sync updates recorded project and global copies from their saved source roots.
+No npm package manifest or author metadata is required. Existing npm package export/import APIs remain available for compatibility.`);
+  console.log(`
+Project skill dependencies (separate from personal-library installs):
+
+  skillshop dependency add @<owner>/<skill>[@<tag-or-commit>]
+  skillshop dependency install [--frozen-lockfile]
+  skillshop dependency update [name]
+  skillshop dependency remove <name>
+  skillshop install                  Restore declared project dependencies
+  skillshop ci                       Restore with a frozen dependency lock
+
+Commit skillshop.json and skillshop-lock.json. Installed ownership lives in each skills directory's .skillshop-lock.
+Dependency restores use exact locked Git commits and content integrity; personal sync does not update them.`);
 }
 
 function flag(args, name) {
@@ -46,8 +55,22 @@ const libraryCommands = new Set(['export', 'unexport', 'validate', 'build', 'res
 
 async function main(argv, { libraryNamespace = false } = {}) {
   const [command, ...args] = argv;
+  if (command === 'dependency' || command === 'ci' || (command === 'install' && (args.length === 0 || (args.length === 1 && args[0] === '--frozen-lockfile')))) {
+    if (args.includes('--help') || args.includes('-h')) return help();
+    let result;
+    if (command === 'dependency' && args[0] === 'add' && args.length === 2) result = addDependency(args[1]);
+    else if (command === 'dependency' && args[0] === 'remove' && args.length === 2) result = removeDependency(args[1]);
+    else if (command === 'dependency' && args[0] === 'update' && (args.length === 1 || args.length === 2)) result = updateDependencies(args[1] ?? null);
+    else if (command === 'ci' && args.length === 0) result = installDependencies({ frozen: true });
+    else if (command === 'install') result = installDependencies({ frozen: args.includes('--frozen-lockfile') });
+    else if (command === 'dependency' && args[0] === 'install' && (args.length === 1 || (args.length === 2 && args[1] === '--frozen-lockfile'))) {
+      result = installDependencies({ frozen: args.includes('--frozen-lockfile') });
+    } else throw new Error('Usage: skillshop dependency add @owner/skill[@ref] | install [--frozen-lockfile] | update [name] | remove <name>');
+    console.log(`Project skill dependencies: ${Object.keys(result.lock.dependencies).length} locked, ${result.changed} installation change(s) at ${result.root}`);
+    return;
+  }
   if (!libraryNamespace && command === 'library') {
-    if (args[0] === 'init' || args[0] === 'list') return main(args, { libraryNamespace: true });
+    if (args[0] === 'init' || args[0] === 'list') return runLegacyCli(argv);
     if (!args.length || args[0] === '--help' || args[0] === '-h') return help();
     throw new Error('Usage: skillshop library init | list');
   }
@@ -146,13 +169,14 @@ async function main(argv, { libraryNamespace = false } = {}) {
 
 const argv = process.argv.slice(2);
 const usingLibraryCommands = argv[0] === 'library' || libraryCommands.has(argv[0]);
+const personalLibraryCommand = argv[0] === 'library' && ['init', 'list'].includes(argv[1]);
 
 try {
-  if (usingLibraryCommands) reconcileLegacyState();
+  if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   try {
     await main(argv);
   } finally {
-    if (usingLibraryCommands) reconcileLegacyState();
+    if (usingLibraryCommands && !personalLibraryCommand) reconcileLegacyState();
   }
 } catch (error) {
   console.error(`skillshop: ${error.message}`);

package/src/dependencies.js

@@ -0,0 +1,282 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { fetchGitHubSkill, parseGitHubSkillReference } from './github-library.js';
+import { atomicJson, assertRegularPath, assertInstallationOwner, readInstallationManifest, writeInstallationManifest, sameOwner } from './installation-state.js';
+
+export const dependencyManifestName = 'skillshop.json';
+export const dependencyLockName = 'skillshop-lock.json';
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const sorted = (value) => Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
+
+export function parseDependencyReference(value) {
+  if (typeof value !== 'string') throw new Error('skill dependency must be @owner/skill or @owner/skill@ref');
+  const separator = value.lastIndexOf('@');
+  const reference = separator > 0 ? value.slice(0, separator) : value;
+  const ref = separator > 0 ? value.slice(separator + 1) : null;
+  if (ref !== null && (!ref || ref.startsWith('-') || !/^[A-Za-z0-9_./-]+$/.test(ref) || ref.includes('..') || ref.endsWith('/'))) {
+    throw new Error(`invalid skill dependency ref: ${ref}`);
+  }
+  return { ...parseGitHubSkillReference(reference), reference, ref, requested: value };
+}
+
+export function dependencyProjectRoot(cwd = process.cwd()) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, dependencyManifestName)) || fs.existsSync(path.join(current, '.git'))) return fs.realpathSync(current);
+    const parent = path.dirname(current);
+    if (parent === current) return fs.realpathSync(cwd);
+    current = parent;
+  }
+}
+
+function readJson(file) {
+  assertRegularPath(file);
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { throw new Error(`cannot parse ${file}: ${error.message}`); }
+}
+
+function skillsPath(root, relative) {
+  if (typeof relative !== 'string' || !relative || path.isAbsolute(relative) || relative.includes('\\')) throw new Error('dependency skillsDirectory must be a relative project directory');
+  const directory = path.resolve(root, relative);
+  const contained = path.relative(root, directory);
+  if (!contained || contained === '..' || contained.startsWith(`..${path.sep}`) || path.isAbsolute(contained)) throw new Error('dependency skillsDirectory escapes the project');
+  assertRegularPath(directory);
+  return directory;
+}
+
+function readManifest(root, { create = false } = {}) {
+  const manifest = readJson(path.join(root, dependencyManifestName));
+  if (!manifest) {
+    if (create) return { schemaVersion: 1, skillsDirectory: '.agents/skills', dependencies: {} };
+    throw new Error(`no ${dependencyManifestName}; add a dependency with skillshop dependency add @owner/skill@ref`);
+  }
+  if (manifest.schemaVersion !== 1 || !object(manifest.dependencies)) throw new Error(`${dependencyManifestName} is not a supported dependency manifest`);
+  skillsPath(root, manifest.skillsDirectory);
+  for (const [name, reference] of Object.entries(manifest.dependencies)) {
+    if (parseDependencyReference(reference).name !== name) throw new Error(`dependency ${name} must match its upstream skill name`);
+  }
+  return manifest;
+}
+
+function readLock(root) {
+  const lock = readJson(path.join(root, dependencyLockName));
+  if (!lock) return null;
+  if (lock.lockfileVersion !== 1 || !object(lock.dependencies)) throw new Error(`${dependencyLockName} is not a supported dependency lockfile`);
+  skillsPath(root, lock.skillsDirectory);
+  for (const [name, entry] of Object.entries(lock.dependencies)) {
+    if (!object(entry)) throw new Error(`invalid locked dependency ${name}`);
+    const parsed = parseDependencyReference(entry.reference);
+    if (parsed.name !== name || entry.repository !== parsed.repository || !/^[a-f0-9]{40,64}$/.test(entry.commit) || !/^sha256-[A-Za-z0-9+/]{43}=$/.test(entry.integrity)) {
+      throw new Error(`invalid locked dependency ${name}`);
+    }
+  }
+  return lock;
+}
+
+export function skillIntegrity(directory) {
+  assertRegularPath(directory);
+  const hash = createHash('sha256');
+  const visit = (relative = '') => {
+    const absolute = path.join(directory, relative);
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink()) throw new Error(`skill contains a symlink: ${absolute}`);
+    if (stat.isDirectory()) {
+      hash.update(JSON.stringify(['directory', relative]));
+      for (const name of fs.readdirSync(absolute).sort()) visit(relative ? `${relative}/${name}` : name);
+    } else if (stat.isFile()) {
+      const contents = fs.readFileSync(absolute);
+      hash.update(JSON.stringify(['file', relative, Boolean(stat.mode & 0o111), contents.length]));
+      hash.update(contents);
+    } else throw new Error(`skill contains a non-regular entry: ${absolute}`);
+  };
+  visit();
+  return `sha256-${hash.digest('base64')}`;
+}
+
+function lockMatches(manifest, lock) {
+  return lock && lock.skillsDirectory === manifest.skillsDirectory &&
+    JSON.stringify(sorted(manifest.dependencies)) === JSON.stringify(sorted(Object.fromEntries(Object.entries(lock.dependencies).map(([name, entry]) => [name, entry.reference]))));
+}
+
+function snapshotFile(file) {
+  assertRegularPath(file);
+  return fs.existsSync(file) ? { bytes: fs.readFileSync(file), mode: fs.statSync(file).mode & 0o777 } : null;
+}
+
+function dependencyExclusion(root, manifest, directories) {
+  let gitRoot;
+  try { gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+  const relativeRoot = path.relative(gitRoot, root);
+  if (relativeRoot === '..' || relativeRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeRoot)) throw new Error('dependency project is outside its Git root');
+  const gitPath = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: root, encoding: 'utf8' }).trim();
+  const file = path.resolve(root, gitPath);
+  assertRegularPath(file);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const begin = '# >>> skillshop project dependencies >>>';
+  const end = '# <<< skillshop project dependencies <<<';
+  const lines = existing.replace(/\r\n/g, '\n').split('\n');
+  const starts = lines.flatMap((line, i) => line === begin ? [i] : []);
+  const ends = lines.flatMap((line, i) => line === end ? [i] : []);
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length && starts[0] >= ends[0])) throw new Error('dependency Git exclude markers are malformed');
+  const retained = starts.length ? [...lines.slice(0, starts[0]), ...lines.slice(ends[0] + 1)] : lines;
+  while (retained.at(-1) === '') retained.pop();
+  const pattern = (target) => `/${path.relative(gitRoot, target).split(path.sep).join('/').replaceAll('\\', '\\\\').replace(/([ !#*?\[\]])/g, '\\$1')}`;
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const paths = [...directories.keys()].map((installedDirectory) => pattern(path.join(installedDirectory, '.skillshop-lock')));
+  paths.push(...Object.keys(manifest.dependencies).map((name) => `${pattern(path.join(directory, name))}/`));
+  return { file, contents: `${[...retained, ...(retained.length ? [''] : []), begin, ...[...new Set(paths)].sort(), end].join('\n')}\n` };
+}
+
+// All downloads and ownership/integrity checks finish before mutating any
+// installation. Backups keep replacement/removal and metadata writes recoverable.
+function commitChanges(root, manifest, lock, changes, directoryStates, { saveManifest }) {
+  const token = randomUUID();
+  const exclusion = dependencyExclusion(root, manifest, directoryStates);
+  const files = [path.join(root, dependencyLockName), ...(saveManifest ? [path.join(root, dependencyManifestName)] : []),
+    ...[...directoryStates.keys()].map((directory) => path.join(directory, '.skillshop-lock')), ...(exclusion ? [exclusion.file] : [])];
+  const before = new Map(files.map((file) => [file, snapshotFile(file)]));
+  const applied = [];
+  try {
+    for (const change of changes) {
+      const target = path.join(change.directory, change.name);
+      const backup = `${target}.skillshop-backup-${token}`;
+      const temporary = `${target}.skillshop-tmp-${token}`;
+      fs.mkdirSync(change.directory, { recursive: true });
+      if (change.source) fs.cpSync(change.source, temporary, { recursive: true });
+      const existed = fs.existsSync(target);
+      if (existed) fs.renameSync(target, backup);
+      const step = { target, backup, temporary, existed };
+      applied.push(step);
+      if (change.source) fs.renameSync(temporary, target);
+    }
+    for (const [directory, state] of directoryStates) writeInstallationManifest(directory, state);
+    atomicJson(path.join(root, dependencyLockName), lock);
+    if (saveManifest) atomicJson(path.join(root, dependencyManifestName), { ...manifest, dependencies: sorted(manifest.dependencies) });
+    if (exclusion && (!before.get(exclusion.file) || before.get(exclusion.file).bytes.toString('utf8') !== exclusion.contents)) {
+      fs.mkdirSync(path.dirname(exclusion.file), { recursive: true });
+      fs.writeFileSync(exclusion.file, exclusion.contents);
+    }
+  } catch (error) {
+    for (const step of applied.reverse()) {
+      fs.rmSync(step.target, { recursive: true, force: true });
+      if (step.existed) fs.renameSync(step.backup, step.target);
+    }
+    for (const [file, previous] of before) {
+      if (previous) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, previous.bytes, { mode: previous.mode });
+        fs.chmodSync(file, previous.mode);
+      } else fs.rmSync(file, { force: true });
+    }
+    throw error;
+  } finally {
+    for (const change of changes) {
+      const target = path.join(change.directory, change.name);
+      fs.rmSync(`${target}.skillshop-tmp-${token}`, { recursive: true, force: true });
+    }
+  }
+  // Cleanup after the commit cannot roll back a successfully published install.
+  for (const step of applied) fs.rmSync(step.backup, { recursive: true, force: true });
+}
+
+function installManifest(root, manifest, previousLock, { frozen = false, saveManifest = false } = {}) {
+  if (frozen && !lockMatches(manifest, previousLock)) throw new Error(`${dependencyLockName} is missing or out of date with ${dependencyManifestName}; frozen install refused`);
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const owner = { kind: 'dependency', id: 'project' };
+  const directories = new Map([[directory, readInstallationManifest(directory)]]);
+  if (previousLock) {
+    const previousDirectory = skillsPath(root, previousLock.skillsDirectory);
+    if (!directories.has(previousDirectory)) directories.set(previousDirectory, readInstallationManifest(previousDirectory));
+  }
+  // Detect ownership conflicts before network requests, including removals.
+  for (const name of Object.keys(manifest.dependencies)) assertInstallationOwner(directory, name, owner);
+  const removals = [];
+  for (const [installedDirectory, state] of directories) {
+    for (const [name, entry] of Object.entries(state.skills)) {
+      if (sameOwner(entry.owner, owner) && (installedDirectory !== directory || !Object.hasOwn(manifest.dependencies, name))) {
+        assertInstallationOwner(installedDirectory, name, owner, { requireOwned: true });
+        removals.push({ directory: installedDirectory, name });
+        delete state.skills[name];
+      }
+    }
+  }
+  const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillshop-dependencies-'));
+  try {
+    const dependencies = {};
+    const changes = [...removals];
+    for (const [name, reference] of Object.entries(sorted(manifest.dependencies))) {
+      const parsed = parseDependencyReference(reference);
+      const previous = previousLock?.dependencies[name];
+      const locked = previous?.reference === reference ? previous : null;
+      const target = path.join(directory, name);
+      const existing = directories.get(directory).skills[name];
+      let current = false;
+      if (locked && existing?.source?.commit === locked.commit && existing?.source?.integrity === locked.integrity && fs.existsSync(target)) {
+        current = skillIntegrity(target) === locked.integrity;
+      }
+      let resolved = locked;
+      if (!current) {
+        const staging = path.join(temporaryRoot, name);
+        fs.mkdirSync(staging);
+        const fetched = fetchGitHubSkill(parsed.reference, staging, locked ? { commit: locked.commit } : { ref: parsed.ref });
+        const integrity = skillIntegrity(fetched.skillDirectory);
+        if (locked && integrity !== locked.integrity) throw new Error(`integrity mismatch for locked dependency ${name}; installation unchanged`);
+        resolved = { reference, repository: parsed.repository, commit: fetched.origin.commit, integrity };
+        changes.push({ directory, name, source: fetched.skillDirectory });
+      }
+      dependencies[name] = resolved;
+      directories.get(directory).skills[name] = { owner, source: { kind: 'dependency', ...resolved } };
+    }
+    const lock = { lockfileVersion: 1, skillsDirectory: manifest.skillsDirectory, dependencies };
+    commitChanges(root, manifest, lock, changes, directories, { saveManifest });
+    return { root, lock, changed: changes.length };
+  } finally {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export function addDependency(reference, { cwd = process.cwd() } = {}) {
+  const parsed = parseDependencyReference(reference);
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root, { create: true });
+  manifest.dependencies[parsed.name] = reference;
+  return installManifest(root, manifest, readLock(root), { saveManifest: true });
+}
+
+export function installDependencies({ cwd = process.cwd(), frozen = false } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  return installManifest(root, readManifest(root), readLock(root), { frozen });
+}
+
+export function updateDependencies(name = null, { cwd = process.cwd() } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root);
+  if (name !== null && !Object.hasOwn(manifest.dependencies, name)) throw new Error(`${name} is not a declared project skill dependency`);
+  const lock = readLock(root);
+  if (lock) {
+    for (const key of Object.keys(manifest.dependencies)) {
+      if (name === null || key === name) delete lock.dependencies[key];
+    }
+  }
+  return installManifest(root, manifest, lock);
+}
+
+export function removeDependency(name, { cwd = process.cwd() } = {}) {
+  const root = dependencyProjectRoot(cwd);
+  const manifest = readManifest(root);
+  if (!Object.hasOwn(manifest.dependencies, name)) throw new Error(`${name} is not a declared project skill dependency`);
+  const lock = readLock(root);
+  if (!lockMatches(manifest, lock)) throw new Error(`${dependencyLockName} is missing or out of date; install dependencies before removing one`);
+  const directory = skillsPath(root, manifest.skillsDirectory);
+  const state = assertInstallationOwner(directory, name, { kind: 'dependency', id: 'project' });
+  delete state.skills[name];
+  delete manifest.dependencies[name];
+  delete lock.dependencies[name];
+  commitChanges(root, manifest, lock, [{ directory, name }], new Map([[directory, state]]), { saveManifest: true });
+  return { root, lock, changed: 1 };
+}