skillshop 4.0.0 → 4.1.0

package/README.md

@@ -36,6 +36,30 @@ skillshop sync                         # updates all recorded project and global
 
 `sync` is also the explicit migration step for older tracked bundled installs. `library init` does not migrate them. If a selected library already has a skill, that source wins and tracked bundle copies are synchronized from it. Otherwise, Skillshop imports a missing source only when every surviving tracked project and global copy agrees across full paths, bytes, and modes. Divergent copies and unreadable ownership state are reported. Unknown source kinds, unmanaged directories, and imported snapshots are left untouched; if they prevent a complete consensus decision, sync reports that conflict. Missing recorded destinations are pruned, never recreated. Keep durable edits in the personal source; sync intentionally replaces local edits inside an owned installed copy.
 
+### Installation ownership and project dependencies
+
+Every installed skills directory has its own `.skillshop-lock`. This is a local ownership manifest, not a project dependency lockfile. It records which installer owns each named directory and its source. Personal-library, bundled, package, package-import, and dependency workflows preserve one another's entries. An existing unmanaged or foreign-owned directory is never implicitly adopted, including with package import `--force`.
+
+For reproducible project requirements, opt into a separate dependency workflow:
+
+```bash
+skillshop dependency add @alice/review@v1.2.0
+skillshop dependency add @alice/triage@0123456789abcdef0123456789abcdef01234567
+skillshop install                        # restore declared dependencies
+skillshop ci                             # restore with a frozen lock
+skillshop dependency remove review
+```
+
+`dependency add` writes `skillshop.json` and `skillshop-lock.json` at the project root and installs the skill. Commit both files. A reference can select a Git tag, branch, or full commit; omitting it resolves the current default branch. The lock records the exact resolved Git commit and SHA-256 integrity of the complete skill tree. It never follows a moved tag or branch during restore. These refs select repository revisions, not semver ranges or the version field in `SKILL.md`.
+
+The project manifest declares `skillsDirectory` (default `.agents/skills`), independently of personal agent settings. Dependency installs use upstream sources directly; they do not create or modify your personal library. `skillshop sync`, ordinary named updates, and Skillshop upgrades leave dependency-owned content alone. Use `skillshop dependency update [name]` to re-resolve upstream refs, or add a different ref; ordinary installs reuse matching lock entries. `skillshop ci` or `skillshop install --frozen-lockfile` fails before installation if the dependency declaration and lock disagree.
+
+Use `skillshop dependency install` as an explicit alias for restore. For skills distributed through npm application packages, continue using npm's dependency declarations and package lock to pin the package; the destination `.skillshop-lock` records installation ownership only.
+
+`skillshop upgrade` automatically migrates legacy project-root `.skillshop-lock` / `.skillz-lock` files and `~/.skillshop/global-skills.json` (or the legacy state home) within its upgrade scope. Replacements are validated and saved before old records are removed, even when skill versions have not changed. Invalid/conflicting ownership or unsafe paths are preserved and reported as an incomplete migration. Unregistered repositories can be discovered with `skillshop migrate ~/workspace`. Installing the CLI directly with npm does not run migration hooks; use `skillshop migrate` or subsequent ownership-reconciling commands.
+
+See [installation and dependency state](docs/installation-and-dependency-state.md) for schemas, migration boundaries, and ownership rules.
+
 ### Install a bundled registry skill (compatibility mode)
 
 When no personal library is selected, the bundled registry remains available:
@@ -47,7 +71,7 @@ skillshop one-shot
 skillshop one-shot --global
 ```
 
-Run project installs inside a Git repository. Skillshop records copies in `.skillshop-lock` and adds only its managed paths to the repository's local Git exclude file. In this compatibility mode it also installs bundled `skillshop` guidance. A global bundled install writes `~/.skillshop/global-skills.json`; for Codex or OpenCode it targets `~/.agents/skills`.
+Run project installs inside a Git repository. Skillshop records ownership in `.skillshop-lock` inside each destination skills directory, for example `.agents/skills/.skillshop-lock`. It adds its local manifests and managed skill paths to the repository's local Git exclude file. In this compatibility mode it also installs bundled `skillshop` guidance. Global installs use the same directory-local format, for example `~/.agents/skills/.skillshop-lock`.
 
 In bundled compatibility mode, most ordinary commands reconcile recorded bundled installations. When a personal library is selected, `list` and named installs join library, download, qualified install, sync, upgrade, and agent instruction commands in bypassing that legacy reconciliation. Upgrade refreshes changed-version bundled copies from the newly installed package in a fresh process. Same-version bundled copies keep local edits; a changed-version replacement overwrites edits in that managed copy. To keep durable local changes, initialize a personal library, use `skillshop sync` to adopt tracked bundled copies where their contents agree, edit the library source, then sync it to owned copies. Personal-library copies are excluded from bundled refresh.
 
@@ -61,7 +85,7 @@ skillshop uninstall one-shot
 skillshop uninstall one-shot --global
 ```
 
-`update` refreshes skills managed in the current project's lockfile from their recorded source. `update --push` updates registered projects. Use `skillshop sync` to propagate personal-library changes to recorded local and global copies. Project uninstall removes only a skill recorded in `.skillshop-lock`. Global uninstall removes the named skill from configured user directories.
+`update` refreshes Skillshop-owned personal or bundled skills in the current project from their recorded source. `update --push` updates registered projects. Use `skillshop sync` to propagate personal-library changes to recorded local and global copies. Project and global uninstall remove only Skillshop CLI-owned copies recorded in the destination manifests. They refuse unmanaged skills and copies owned by packages or project dependencies.
 
 ### Upgrade Skillshop
 
@@ -71,7 +95,7 @@ skillshop upgrade
 
 The command upgrades the npm installation that supplied the invoked CLI. A project-local installation updates Skillshop in the owning npm project and preserves the dependency section where it is already declared. It refreshes only that project's recorded Skillshop-managed skill copies. A global installation updates its npm prefix, then refreshes recorded global copies and copies in registered projects; it does not update those projects' package manifests. Running from a source checkout keeps the historical global-install behavior and does not edit the checkout's package manifest.
 
-After npm succeeds, the newly installed CLI runs in a fresh process and refreshes only existing copies recorded in `.skillshop-lock` or `~/.skillshop/global-skills.json` whose bundled skill version changed. Same-version copies retain local edits. A changed-version replacement overwrites local edits in that managed copy. For durable local changes, initialize a personal library, explicitly sync to adopt tracked bundled copies when their surviving copies agree, then edit the library source and sync. Deleted paths are pruned from ownership records instead of recreated. Unmanaged directories and package-import snapshots are not adopted. An npm install failure stops before copy refresh; a later refresh failure reports that Skillshop was upgraded and gives a nonzero result with the partial-refresh summary.
+After npm succeeds, the newly installed CLI runs in a fresh process. It migrates legacy ownership records, then refreshes only existing CLI-owned copies whose bundled skill version changed. Same-version copies retain local edits. A changed-version replacement overwrites local edits in that managed copy. For durable local changes, initialize a personal library, explicitly sync to adopt tracked bundled copies when their surviving copies agree, then edit the library source and sync. Deleted paths are pruned from ownership records instead of recreated. Unmanaged directories and package-import snapshots are not adopted. An npm install failure stops before copy refresh; a later refresh failure reports that Skillshop was upgraded and gives a nonzero result with the partial-refresh summary.
 
 `skillshop init` is optional. It configures agent destinations and is not required to upgrade Skillshop. The upgrade command never initializes, renders, or rewrites project `AGENTS.md` files or instruction templates.
 
@@ -140,7 +164,7 @@ A distributor can declare which exported skills a global npm install should plac
 npm install --global @example/skill-library
 ```
 
-Those declared skills are copied during the package's install script. This package installer targets `~/.agents/skills` by default, independently of the agents selected with `skillshop init`. Updating the package replaces the same named user skills. If scripts are disabled, run `skillshop install-user /path/to/installed-package` manually.
+Those declared skills are copied during the package's install script. This package installer targets `~/.agents/skills` by default, independently of the agents selected with `skillshop init`. Updating the package replaces its own recorded user skills, refuses unmanaged or foreign-owned collisions, and removes its own copies when their declarations are removed. If scripts are disabled, run `skillshop install-user /path/to/installed-package` manually.
 
 To copy one exported skill into a project instead:
 
@@ -162,9 +186,9 @@ cd ~/work/sample-app
 skillshop changelog
 ```
 
-The global command writes `~/.agents/skills/one-shot/SKILL.md`. The project command writes `.agents/skills/changelog/SKILL.md` and `.agents/skills/skillshop/SKILL.md` inside `sample-app`, then records both managed skills in `.skillshop-lock`. It does not copy `one-shot` into the project. Running `skillshop update` in `sample-app` refreshes the locked project skills; run `skillshop one-shot --global` again to replace the global copy.
+The global command writes `~/.agents/skills/one-shot/SKILL.md`. The project command writes `.agents/skills/changelog/SKILL.md` and `.agents/skills/skillshop/SKILL.md` inside `sample-app`, then records both managed skills in `.agents/skills/.skillshop-lock`. It does not copy `one-shot` into the project. Running `skillshop update` in `sample-app` refreshes the locked project skills; run `skillshop one-shot --global` again to replace the global copy.
 
-Package imports are separate from this lockfile workflow. `import` copies a snapshot from another package; `skillshop update` does not refresh that snapshot. `export` names a skill for consumers of a package and does not install it anywhere.
+Package imports record package-import ownership in the destination manifest and remain separate from personal-library sync and project dependency locking. `import` copies a snapshot from another package; `skillshop update` does not refresh that snapshot. `export` names a skill for consumers of a package and does not install it anywhere.
 
 ## For project owners: distribute skills
 

package/docs/installation-and-dependency-state.md

@@ -0,0 +1,76 @@
+# Installed ownership and project dependency locks
+
+Skillshop separates editable source libraries, installed ownership, and reproducible project requirements. Installing a personal skill does not make it a project dependency. Applications distributed through npm continue to use npm's own dependency declarations and package lock.
+
+## Destination ownership
+
+Every destination skills directory has one `.skillshop-lock`. The destination itself identifies installed paths; entries do not repeat absolute destination paths or point to a second authoritative registry.
+
+```json
+{
+  "manifestVersion": 1,
+  "skills": {
+    "review": {
+      "owner": { "kind": "skillshop", "id": "project" },
+      "source": {
+        "kind": "personal-library",
+        "root": "/Users/example/skillshop-library",
+        "skill": "review",
+        "skillDirectory": "skills/review"
+      }
+    }
+  }
+}
+```
+
+CLI-owned copies use owner kind `skillshop` and id `project` or `global`. Project dependency copies use kind `dependency`, id `project`. These local ids survive moving an entire project directory. Package lifecycle installers use kind `package` and the package name as id; explicit snapshot imports use kind `package-import`. Package ids remain stable across versions and npm installation paths. Anonymous manifest-object imports use their source directory as id and should supply a package name for stable ownership.
+
+Each installer reads the destination manifest, checks ownership, and preserves entries belonging to other installers. Matching ownership permits updates. Existing directories without ownership records and records belonging to other owners are rejected. `import --force` permits replacing an existing matching package-import copy; it does not adopt unrelated directories. Global CLI uninstall checks ownership too. Package declaration updates prune only that package's obsolete copies; `uninstallUserSkill` provides explicit same-owner removal.
+
+The files `~/.skillshop/installations.json` and `repositories.json` are discovery indexes, not ownership authorities. Deleting or editing an index does not grant ownership. Known standard installation directories can still be discovered from the project or home directory. `sync` uses the source roots recorded in destination manifests, independently of the currently selected library.
+
+Ownership manifests are local machine state. Personal/bundled installation commands locally exclude their manifests and owned directories through Git's `info/exclude`. Dependency commands maintain a separate bounded exclude block for generated dependency content and destination manifests. Unrelated installed skill directories are not blanket-excluded. Project declarations and dependency locks remain commit candidates.
+
+## Project declarations and immutable resolution
+
+Add a dependency explicitly:
+
+```sh
+skillshop dependency add @alice/review@v1.2.0
+```
+
+This writes a project-owned `skillshop.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "skillsDirectory": ".agents/skills",
+  "dependencies": {
+    "review": "@alice/review@v1.2.0"
+  }
+}
+```
+
+A corresponding `skillshop-lock.json` records each requested reference, conventional GitHub repository URL, exact resolved commit, and `sha256-` integrity. It also records the project installation directory, so a frozen restore detects destination configuration changes. It contains no personal-library paths or machine-specific destination paths.
+
+Refs can select a Git tag, branch, or full commit hash. An omitted ref resolves the repository's default branch. These are Git revisions; there is no semver-range solver or historical registry of `SKILL.md` version fields. A moved upstream tag cannot change an existing lock entry. The complete directory is fetched from the locked commit, and integrity covers ordered paths, file bytes, and executable bits, including hidden files, scripts and binary references. Repository code is never executed while fetching.
+
+`skillshop install` and `skillshop dependency install` restore declared dependencies. Unchanged entries reuse their locked commit; a new or changed declaration resolves its ref. Already correct owned copies are left in place without upstream requests. Missing copies are restored and edited copies are repaired against the lock. Restoration requires upstream access when the required content is not already installed correctly.
+
+`skillshop ci`, `skillshop install --frozen-lockfile`, and `skillshop dependency install --frozen-lockfile` refuse a missing or stale lock before changing output. Use `skillshop dependency update [name]` to re-resolve selected or all upstream refs, or add a different ref. `skillshop dependency remove review` removes the declaration, locked resolution and matching owned copy while preserving other owners. Ordinary personal sync/update and CLI upgrade never refresh dependency copies.
+
+All required downloads, integrity checks and ownership checks finish before dependency content changes. Replacement/removal uses temporary directories and backups. A failed content or metadata write restores prior content, ownership and project declarations. Manifest writes use atomic rename. These records are ownership and reproducibility data, not process mutexes; concurrent writers targeting the same directory are not supported.
+
+Dependency APIs are exported from `skillshop/dependencies`: `addDependency`, `installDependencies`, `updateDependencies`, and `removeDependency`. They accept `cwd`; install accepts `frozen`. For CLI commands, the nearest project manifest takes precedence while ascending to the nearest Git root. Outside Git, an existing ancestor manifest is used; otherwise the working directory is the project boundary.
+
+## Migration and upgrade boundaries
+
+The new CLI reads legacy project-root `.skillshop-lock` / `.skillz-lock` files and the old state-home `global-skills.json`. It validates their schemas, owned paths and any existing destination claims before repair or migration. Divergent simultaneous legacy root files are rejected. Only explicit ownership records are migrated; scanning directories does not adopt arbitrary skills.
+
+Replacement manifests are saved beside installed skills before legacy records are removed. Retry is safe when a prior attempt saved only part of the replacement state. Malformed JSON, conflicting source/ownership records, and symlinked paths are preserved and reported rather than silently discarded. Upgrading does not merge or overwrite application-owned directories.
+
+`skillshop upgrade` installs the new npm package first and uses its fresh CLI for migration and version-based bundled refresh. A project-local npm installation migrates only its owning project's state. A global installation migrates global state and registered projects. Migration runs even for unchanged-version and personal-library copies. Same-version bundled edits survive; changed-version bundled refresh retains its existing replacement behavior. Missing copies are not recreated by ownership migration.
+
+Direct `npm install --global skillshop` replaces the CLI but does not run migration hooks. The next ownership-reconciling command can migrate its current project and global state; `skillshop migrate ~/workspace` discovers additional repositories. Personal-library initialization, downloading, listing and instruction-rendering commands retain their existing isolation from legacy reconciliation.
+
+Using an old CLI after migration is unsupported: old versions do not understand directory-local manifests. Reinstalling skills with an old package installer can also bypass the new ownership protections. Keep application integrations on the updated Skillshop API.

package/docs/package-library-compatibility.md

@@ -79,7 +79,7 @@ To copy selected skills during a global npm install, add `skillshop.userInstall`
 
 Every `userInstall` entry must be unique and appear in `skillshop.library.json`. In this example, `skill:review` installs for the user on a global npm install. `skill:triage` remains available for explicit project imports. The runtime dependency makes the `skillshop` command available to npm's `postinstall` script. `--if-global` skips the user copy on a project-local install. npm's `--ignore-scripts` skips `postinstall` entirely.
 
-An install replaces each declared destination directory. If a later release removes a name from `userInstall`, Skillshop does not delete a copy previously installed in a user's directory.
+An install records package ownership in `.skillshop-lock` inside the destination skills directory. It replaces only copies already owned by the same package and rejects unmanaged or foreign-owned destinations. A later install removes copies owned by that package when their names are removed from `userInstall`; other owners remain untouched. Package names identify owners across versions and installation paths. Applications can explicitly remove an owned skill with `uninstallUserSkill` from `skillshop/user-install`.
 
 ### 3. Check and pack the package
 
@@ -162,7 +162,7 @@ skillshop import <library>:<skill> [--global] [--to <directory>] [--force]
 skillshop install-user [package-dir] [--if-global] [--to <skills-dir>]
 ```
 
-`init` and `list` keep their bundled-registry meanings. `library init`, `library list`, `validate`, and `build` operate on the package library in the current directory. In a `library:skill` reference, `library` can be an installed package name or a local package directory. `import` defaults to `.agents/skills/<skill>`; `--global` replaces `~/.agents/skills/<skill>`. `unexport` changes the package's public skill list; it does not delete the source directory. Remove a skill from `userInstall` before unexporting it.
+`init` and `list` keep their bundled-registry meanings. `library init`, `library list`, `validate`, and `build` operate on the package library in the current directory. In a `library:skill` reference, `library` can be an installed package name or a local package directory. `import` defaults to `.agents/skills/<skill>`; `--global` targets `~/.agents/skills/<skill>` and replaces only a matching package-import-owned copy. `unexport` changes the package's public skill list; it does not delete the source directory. Remove a skill from `userInstall` before unexporting it.
 
 Applications can use the same operations without invoking the CLI:
 
@@ -191,4 +191,4 @@ await importSkill({
 
 `resolveSkill` leaves the skill inside the installed package. `importSkill` copies its complete directory, including files alongside `SKILL.md`. Set `overwrite: true` only when the application intends to replace an existing destination.
 
-`importSkill({ overwrite: true })` replaces a destination. Its optional `merge: true` mode overlays packaged files and preserves unrelated destination files. User-level installation always uses replacement, even when called through `installDeclaredUserSkills`.
+`importSkill({ overwrite: true })` replaces a destination only when that copy is already owned by the same package-import source; it does not authorize taking ownership of unrelated content. Its optional `merge: true` mode overlays packaged files and preserves unrelated destination files. User-level installation always uses replacement of matching package-owned copies, even when called through `installDeclaredUserSkills`. Merge mode also requires matching ownership for existing targets.

package/docs/releases/4.1.0.md

@@ -0,0 +1,12 @@
+# Skillshop 4.1.0
+
+Separate installed skill ownership from reproducible project dependencies.
+
+- Store ownership in `.skillshop-lock` beside installed skills, with automatic migration of tracked legacy project/global records during `skillshop upgrade`.
+- Add committed `skillshop.json` declarations and `skillshop-lock.json` resolutions that pin exact Git commits and complete-tree SHA-256 integrity.
+- Add `skillshop dependency add/install/update/remove`, dependency restore through `skillshop install`, and frozen restore through `skillshop ci`.
+- Reject unmanaged and foreign-owned collisions, protect global uninstall, and prune removed application declarations only for their recorded package owner.
+
+Migration preserves unmanaged skills and same-version bundled edits. Invalid ownership records and unsafe paths are preserved and reported. Direct npm installation replaces the CLI without migration hooks; run `skillshop migrate ~/workspace` to discover and migrate additional repositories. Older CLI versions cannot read the new ownership format.
+
+Validated with the full automated suite, isolated local/global upgrade fixtures, and packed CLI installation/dependency smoke tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshop",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Install and sync agent skills from personal folder libraries",
   "type": "module",
   "bin": {
@@ -13,7 +13,9 @@
     "./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/",

package/skills-content/skillshop/SKILL.md

@@ -3,12 +3,12 @@ name: skillshop
 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.1"
+  version: "2026.10.28.1"
 ---
 
 # Skillshop — Personal Skill Libraries and Local Registry
 
-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; `.skillshop-lock` and `~/.skillshop/global-skills.json` record which project and global directories Skillshop installed from those sources. Directories absent from ownership records 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
 
@@ -37,6 +37,20 @@ Most ordinary non-agent commands reconcile the current project's lockfile, regis
 
 `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
@@ -98,7 +112,7 @@ skillshop i <name>
 skillshop add <name>
 ```
 
-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`; `.skillshop-lock` and its 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.
+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:
 
@@ -109,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`. 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.
+`--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
 
@@ -122,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
 
@@ -132,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. 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.
+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
 
@@ -153,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
 
@@ -173,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,6 +8,7 @@ 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(`
@@ -23,6 +24,18 @@ Personal folder library commands:
 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) {
@@ -42,6 +55,20 @@ 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 runLegacyCli(argv);
     if (!args.length || args[0] === '--help' || args[0] === '-h') return help();