skillshop 2.2.0 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Skillshop
 
-Skillshop installs and manages agent skills. Its CLI includes a bundled skill registry, with the same named install, update, and agent configuration commands as the earlier `skillz` CLI. It also lets project owners export skills from their own npm packages. A skill is a directory containing `SKILL.md` and any supporting files.
+Skillshop installs and manages agent skills. For user-authored skills, a plain folder library is the source of truth. Download individual skills from GitHub, install them into project or global destinations, and sync later source edits across recorded copies. The bundled registry and npm package-library APIs remain available for compatibility. A skill is a directory containing `SKILL.md` and any supporting files.
 
 The command is `skillshop`; `sk` runs the same CLI. The previous `skillz` command is no longer an executable alias. Existing `.skillz-lock` and `~/.skillz` state remain readable.
 
@@ -15,26 +15,41 @@ skillshop init
 
 `skillshop init` asks which agents you use and saves their destinations in `~/.skillshop/config.json`. It is optional for project skill installs: without saved agent selection, Skillshop uses the nearest existing `.agents`, `.github`, or `.codex` directory and falls back to project-root `.agents/skills`. Run `skillshop init` to choose system-wide defaults; change that selection later with `skillshop config agents`. Codex and OpenCode use `.agents/skills` inside projects and `~/.agents/skills` for user-level installs. Copilot and Claude use their own skill directories. Shared destinations get one copy.
 
-### Install a named skill
-
-List the skills bundled with Skillshop, then install one:
+### Use a personal folder library
 
 ```bash
-skillshop list
-skillshop one-shot
-# Equivalent: skillshop install one-shot
+skillshop library init                 # selects ~/skillshop-library
+skillshop library init ./my-skills     # selects or adopts an existing folder
+skillshop library list
+skillshop download @alice/review       # adds source only
+skillshop install @alice/review        # downloads if absent, then installs locally
+skillshop install @alice/review --global
+skillshop install review               # installs an existing selected source
+skillshop sync                         # updates all recorded project and global copies
 ```
 
-Run a project install inside a Git repository. Skillshop copies the skill into each configured project destination and records managed copies in `.skillshop-lock`. It also installs the `skillshop` guidance skill. The lockfile and managed skill directories go into the repository's local Git exclude file, leaving unrelated skill directories alone.
+`library init` can create a missing folder or select an existing library. It preserves existing skill directories and config; no `package.json`, npm metadata, or version field is required. Without an explicit directory it selects the visible `~/skillshop-library` folder. The library config is `skillshop-library.json`; the default source directory is `skills/`. A skill can contain any regular files and nested folders, including hidden references and executable scripts.
+
+`download @owner/skill` reads `https://github.com/owner/skillshop-library.git` and copies only `skills/skill` into the selected personal library. The `@` marks a remote owner/skill reference; it is not part of the GitHub owner or repository URL. Download does not install the skill. `install @owner/skill` downloads when that source is absent, then installs from the library. If the same repository source is already present, local edits are reused without an upstream fetch. `install name` installs a matching skill from the selected library. Once a library is selected, named installs and `skillshop list` use that library; they do not fall back to bundled skills or add bundled guidance. Add `--global` to install into configured user directories. Unprefixed `owner/skill` inputs are rejected; use `@owner/skill` for remote references.
 
-To install a named skill for your user account instead:
+`download @owner/skill --force` explicitly replaces the personal source directory after validation. A same-name authored or different-source skill otherwise fails safely. `skillshop sync` copies the current full directory from each recorded personal source to its Skillshop-managed project and global copies. It includes file additions, edits, removals, hidden files, binary contents, and modes; stale extras inside those owned copies are removed. Sync never fetches GitHub and changing the selected library does not redirect existing copies.
+
+`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.
+
+### Install a bundled registry skill (compatibility mode)
+
+When no personal library is selected, the bundled registry remains available:
 
 ```bash
+skillshop list
+skillshop one-shot
+# Equivalent: skillshop install one-shot
 skillshop one-shot --global
-# Equivalent: sk install one-shot --global
 ```
 
-For Codex or OpenCode, this writes `~/.agents/skills/one-shot`. A global install replaces an existing skill directory with that name, including local edits and extra files. Global installs use `~/.skillshop/global-skills.json` for bookkeeping. Except for `skillshop upgrade`, ordinary non-agent-instruction CLI runs reconcile recorded installations. Upgrade skips reconciliation in the old process and refreshes changed copies from the newly installed package in a fresh process. Agent instruction commands also bypass reconciliation and do not install the bundled registry.
+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`.
+
+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.
 
 ### Update or remove skills
 
@@ -46,7 +61,7 @@ skillshop uninstall one-shot
 skillshop uninstall one-shot --global
 ```
 
-`update` replaces skills managed in the current project's lockfile. `update --push` updates registered projects. Neither command updates global copies; reinstall a global skill by name with `--global`. Project uninstall removes only a skill recorded in `.skillshop-lock`. Global uninstall removes the named skill from configured user directories.
+`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.
 
 ### Upgrade Skillshop
 
@@ -56,7 +71,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 their local bodies. A changed-version replacement overwrites local edits in that managed copy; make durable edits in the bundled source. 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 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.
 
 `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.
 
@@ -153,189 +168,31 @@ Package imports are separate from this lockfile workflow. `import` copies a snap
 
 ## For project owners: distribute skills
 
-### 1. Export the skills
+### Personal skills: share a folder through GitHub
 
-In an npm package, put each skill in a directory with a `SKILL.md`. For example:
+The recommended authoring format is a normal folder. Fork the bundled template at [`templates/skillshop-library`](templates/skillshop-library) or create the same layout in a GitHub repository named `skillshop-library`:
 
 ```text
-my-library/
-  package.json
-  .agents/skills/review/SKILL.md
-  .agents/skills/triage/SKILL.md
-```
-
-For example, `.agents/skills/review/SKILL.md` could contain:
-
-```markdown
----
-name: review
-description: Review a proposed code change
----
-
-# Review
-
-Read the diff, identify concrete defects, and cite the affected files.
-```
-
-Keep any references or scripts needed by the skill beside its `SKILL.md`; Skillshop copies the whole directory.
-
-Add Skillshop, initialize the export list, and name the skill you want to publish:
-
-```bash
-npm install skillshop
-npx skillshop library init
-npx skillshop export skill:review ./.agents/skills/review
-npx skillshop export skill:triage ./.agents/skills/triage
-```
-
-This writes `skillshop.library.json`:
-
-```json
-{
-  "schemaVersion": 1,
-  "exports": {
-    "skill:review": "./.agents/skills/review",
-    "skill:triage": "./.agents/skills/triage"
-  }
-}
-```
-
-The `exports` map is an explicit allowlist. Skillshop does not scan your repository for other skills. `skillshop export` also builds the library; run `skillshop build` after editing the JSON by hand. The build generates `skillshop.manifest.mjs`, adds the package's `./skillshop` export, and includes declared local skill directories in `package.json#files` when that field exists. Commit the resulting package files with your source.
-
-### 2. Declare user-level installation, if needed
-
-To copy selected skills during a global npm install, add `skillshop.userInstall` and the generic lifecycle command to the distributor's `package.json`:
-
-```json
-{
-  "name": "@example/skill-library",
-  "version": "1.0.0",
-  "dependencies": {
-    "skillshop": "^2.1.0"
-  },
-  "files": [],
-  "scripts": {
-    "prepack": "skillshop build",
-    "postinstall": "skillshop install-user . --if-global"
-  },
-  "skillshop": {
-    "userInstall": ["skill:review"]
-  }
-}
-```
-
-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.
-
-### 3. Check and pack the package
-
-```bash
-npx skillshop library list
-npx skillshop validate
-npx skillshop build
-npm pack --dry-run
-```
-
-Check that the npm package contains `skillshop.manifest.mjs`, every exported `SKILL.md`, and any assets those skills need. The export list controls what Skillshop can resolve; it does not prevent your own broad `files` patterns from publishing other files. A real `npm pack` and global install from its tarball are useful checks before a release.
-
-After checking the tarball, publish the package with `npm publish`. Use `npm publish --access public` for a public scoped package.
-
-### Example: what happens after publication
-
-With the two-skill package above published as `@example/skill-library`, a global install copies only the declared `skill:review` to the user's skill directory:
-
-```bash
-npm install --global @example/skill-library
-# ~/.agents/skills/review/SKILL.md now comes from the package
+skillshop-library/
+  skillshop-library.json
+  skills/
+    review/
+      SKILL.md
+      references/
+      scripts/
 ```
 
-An application that needs `skill:triage` can install the package locally and copy that exported skill into its own repository:
+The config declares the relative source directory. Each skill needs a standard `SKILL.md` with `name` and `description`; author/version metadata is optional. Put references, scripts, and other assets beside it. Skillshop downloads the complete directory and preserves executable modes.
 
 ```bash
-cd ~/work/sample-app
-npm install @example/skill-library skillshop
-npx skillshop import @example/skill-library:triage
-```
-
-After the distributor publishes an update, reinstalling the package globally replaces the user's `review` directory. The application's `triage` snapshot stays as it was until the application updates the package and imports again with `--force`. The two installation paths are independent.
-
-### Re-export a skill from another library
-
-A package can expose a selected upstream skill under its own name:
-
-```bash
-npm install @example/upstream
-npx skillshop export skill:review --from @example/upstream --skill skill:review
-```
-
-The resulting export in `skillshop.library.json` is:
-
-```json
-{
-  "skill:review": {
-    "from": "@example/upstream",
-    "skill": "skill:review"
-  }
-}
-```
-
-That object is one entry inside the manifest's `exports` map. The upstream package must be a runtime dependency or a non-optional peer dependency. Re-exporting is explicit; depending on another library does not expose all of its skills.
-
-## CLI and JavaScript API
-
-```text
-skillshop init
-skillshop config agents
-skillshop list
-skillshop <name> [--global]
-skillshop install <name> [--global]
-skillshop update [name]
-skillshop update --push
-skillshop uninstall <name> [--global]
-skillshop agents init [--project <directory>]
-skillshop agents [--project <directory>] [--check]
-skillshop agents --global
-skillshop migrate [root ...]
-skillshop library init
-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 @alice/review
+skillshop install @alice/review
+skillshop install @alice/review --global
+skillshop sync
 ```
 
-`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.
-
-Applications can use the same operations without invoking the CLI:
-
-```js
-import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
-import { resolveSkill, importSkill } from 'skillshop/import';
-import { installDeclaredUserSkills } from 'skillshop/user-install';
-```
-
-For example, an application can read an exported skill directly from an installed package, or copy it into a workspace it manages:
-
-```js
-import { readFile } from 'node:fs/promises';
-import { resolveSkill, importSkill } from 'skillshop/import';
-
-const reference = '@example/skill-library:triage';
-const { manifestPath } = await resolveSkill({ reference });
-const instructions = await readFile(manifestPath, 'utf8');
-// Pass instructions to your agent runtime.
-
-await importSkill({
-  reference,
-  overwrite: true,
-});
-```
+`download @owner/skill` adds a source to the personal folder library without installing it. `install @owner/skill` downloads if needed and installs from that source; subsequent local edits are reused. `install name` uses a bare name for an existing library source. `sync` updates recorded local and global copies from the saved source roots. It never fetches upstream. See [the forkable library template](templates/skillshop-library/README.md) for its full layout and command details.
 
-`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.
+### Existing package API compatibility
 
-`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`.
+The published npm export/import APIs remain supported for existing consumers. Their authoring, lifecycle, and JavaScript API guide is in [Package library compatibility](docs/package-library-compatibility.md). New user-authored libraries can use the folder and GitHub workflow above without npm packaging.

package/docs/package-library-compatibility.md

@@ -0,0 +1,194 @@
+# Package library compatibility
+
+This guide documents the existing npm package export/import APIs. It is retained for consumers of those published APIs. It is not required for personal folder libraries or GitHub skill sharing.
+
+### Package API compatibility: export skills from npm packages
+
+The npm export/import API remains supported for existing package-based libraries. It is not required for personal skill authoring.
+
+#### 1. Export the skills
+
+In an npm package, put each skill in a directory with a `SKILL.md`. For example:
+
+```text
+my-library/
+  package.json
+  .agents/skills/review/SKILL.md
+  .agents/skills/triage/SKILL.md
+```
+
+For example, `.agents/skills/review/SKILL.md` could contain:
+
+```markdown
+---
+name: review
+description: Review a proposed code change
+---
+
+# Review
+
+Read the diff, identify concrete defects, and cite the affected files.
+```
+
+Keep any references or scripts needed by the skill beside its `SKILL.md`; Skillshop copies the whole directory.
+
+Add Skillshop, initialize the export list, and name the skill you want to publish:
+
+```bash
+npm install skillshop
+npx skillshop library init
+npx skillshop export skill:review ./.agents/skills/review
+npx skillshop export skill:triage ./.agents/skills/triage
+```
+
+This writes `skillshop.library.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "exports": {
+    "skill:review": "./.agents/skills/review",
+    "skill:triage": "./.agents/skills/triage"
+  }
+}
+```
+
+The `exports` map is an explicit allowlist. Skillshop does not scan your repository for other skills. `skillshop export` also builds the library; run `skillshop build` after editing the JSON by hand. The build generates `skillshop.manifest.mjs`, adds the package's `./skillshop` export, and includes declared local skill directories in `package.json#files` when that field exists. Commit the resulting package files with your source.
+
+### 2. Declare user-level installation, if needed
+
+To copy selected skills during a global npm install, add `skillshop.userInstall` and the generic lifecycle command to the distributor's `package.json`:
+
+```json
+{
+  "name": "@example/skill-library",
+  "version": "1.0.0",
+  "dependencies": {
+    "skillshop": "^2.1.0"
+  },
+  "files": [],
+  "scripts": {
+    "prepack": "skillshop build",
+    "postinstall": "skillshop install-user . --if-global"
+  },
+  "skillshop": {
+    "userInstall": ["skill:review"]
+  }
+}
+```
+
+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.
+
+### 3. Check and pack the package
+
+```bash
+npx skillshop library list
+npx skillshop validate
+npx skillshop build
+npm pack --dry-run
+```
+
+Check that the npm package contains `skillshop.manifest.mjs`, every exported `SKILL.md`, and any assets those skills need. The export list controls what Skillshop can resolve; it does not prevent your own broad `files` patterns from publishing other files. A real `npm pack` and global install from its tarball are useful checks before a release.
+
+After checking the tarball, publish the package with `npm publish`. Use `npm publish --access public` for a public scoped package.
+
+### Example: what happens after publication
+
+With the two-skill package above published as `@example/skill-library`, a global install copies only the declared `skill:review` to the user's skill directory:
+
+```bash
+npm install --global @example/skill-library
+# ~/.agents/skills/review/SKILL.md now comes from the package
+```
+
+An application that needs `skill:triage` can install the package locally and copy that exported skill into its own repository:
+
+```bash
+cd ~/work/sample-app
+npm install @example/skill-library skillshop
+npx skillshop import @example/skill-library:triage
+```
+
+After the distributor publishes an update, reinstalling the package globally replaces the user's `review` directory. The application's `triage` snapshot stays as it was until the application updates the package and imports again with `--force`. The two installation paths are independent.
+
+### Re-export a skill from another library
+
+A package can expose a selected upstream skill under its own name:
+
+```bash
+npm install @example/upstream
+npx skillshop export skill:review --from @example/upstream --skill skill:review
+```
+
+The resulting export in `skillshop.library.json` is:
+
+```json
+{
+  "skill:review": {
+    "from": "@example/upstream",
+    "skill": "skill:review"
+  }
+}
+```
+
+That object is one entry inside the manifest's `exports` map. The upstream package must be a runtime dependency or a non-optional peer dependency. Re-exporting is explicit; depending on another library does not expose all of its skills.
+
+## CLI and JavaScript API
+
+```text
+skillshop init
+skillshop config agents
+skillshop list
+skillshop <name> [--global]
+skillshop install <name> [--global]
+skillshop update [name]
+skillshop update --push
+skillshop uninstall <name> [--global]
+skillshop agents init [--project <directory>]
+skillshop agents [--project <directory>] [--check]
+skillshop agents --global
+skillshop migrate [root ...]
+skillshop library init
+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>]
+```
+
+`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.
+
+Applications can use the same operations without invoking the CLI:
+
+```js
+import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
+import { resolveSkill, importSkill } from 'skillshop/import';
+import { installDeclaredUserSkills } from 'skillshop/user-install';
+```
+
+For example, an application can read an exported skill directly from an installed package, or copy it into a workspace it manages:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { resolveSkill, importSkill } from 'skillshop/import';
+
+const reference = '@example/skill-library:triage';
+const { manifestPath } = await resolveSkill({ reference });
+const instructions = await readFile(manifestPath, 'utf8');
+// Pass instructions to your agent runtime.
+
+await importSkill({
+  reference,
+  overwrite: true,
+});
+```
+
+`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`.

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.0.0",
+  "description": "Install and sync agent skills from personal folder libraries",
   "type": "module",
   "bin": {
     "skillshop": "./src/cli.js",
@@ -18,6 +18,8 @@
   "files": [
     "agents-content/",
     "skills-content/",
+    "templates/",
+    "docs/",
     "src/",
     "README.md"
   ],

package/skills-content/skillshop/SKILL.md

@@ -1,18 +1,39 @@
 ---
 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.23.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; `.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.
+
+## 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.
 
@@ -66,7 +87,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 +98,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`; `.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.
 
 To require the exact version currently available from the local registry:
 
@@ -88,7 +109,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. 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.
 
 ## Update managed skills
 
@@ -111,7 +132,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 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