skillshop 2.0.0 → 2.1.0

package/README.md

@@ -1,168 +1,281 @@
 # Skillshop
 
-Skillshop is infrastructure for **building and consuming skill libraries**. It is not a bundled personal skill catalog.
+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.
 
-A skill is addressed by a portable component specifier:
+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.
 
-```text
-skill:clips
-skill:loopz
-skill:design-review
+## For users: manage skills
+
+### Install and configure Skillshop
+
+```bash
+npm install --global skillshop
+skillshop init
 ```
 
-The library owns where its `SKILL.md` lives. Consumers only depend on the `skill:*` name.
+`init` asks which agents you use and saves their destinations in `~/.skillshop/config.json`. Change the 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.
 
-## The model
+### Install a named skill
 
-A producer package keeps a source manifest:
+List the skills bundled with Skillshop, then install one:
 
-```json
-{
-  "schemaVersion": 1,
-  "exports": {
-    "skill:clips": "./.agents/skills/clips",
-    "skill:loopz": "./.agents/skills/loopz"
-  }
-}
+```bash
+skillshop list
+skillshop one-shot
+# Equivalent: skillshop install one-shot
+```
+
+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.
+
+To install a named skill for your user account instead:
+
+```bash
+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. Each CLI run reconciles recorded installations; it does not install the entire bundled registry.
+
+### Update or remove skills
+
+```bash
+skillshop update
+skillshop update one-shot
+skillshop update --push
+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.
+
+An exact version such as `skillshop one-shot@2026.8.21` checks the currently bundled version. It does not fetch a historical release. Use `skillshop migrate` to discover older lockfiles and register their repositories.
+
+### Manage agent instructions
+
+```bash
+skillshop agents
+skillshop agents --global
+```
+
+The local command updates a managed block in the nearest existing `AGENTS.md`. The global command updates the supported user instruction files. Sibling `*.block.md` fragments are composed in filename order. Text outside Skillshop's managed blocks is preserved.
+
+### Use skills from another package
+
+A distributor can declare which exported skills a global npm install should place in your user skill directory:
+
+```bash
+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.
+
+To copy one exported skill into a project instead:
+
+```bash
+npm install @example/skill-library skillshop
+npx skillshop import @example/skill-library:review
+```
+
+The `library:skill` argument names an installed package and one skill it exports. The command copies the skill to `.agents/skills/review` in the current project. Use `--to` for another destination or `--global` to copy it to `~/.agents/skills/review`. This is a snapshot. Reimport with `--force` to replace an existing project copy. `skillshop resolve @example/skill-library:review` reports its source location without copying it.
+
+### Example: one user, two scopes
+
+Suppose you use Codex and work in `~/work/sample-app`, which is already a Git repository. Select Codex when `skillshop init` prompts, then install one bundled skill for every project and another only for this app:
+
+```bash
+skillshop init
+skillshop one-shot --global
+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.
+
+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.
+
+## For project owners: distribute skills
+
+### 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
 ```
 
-`skillshop build` validates each directory and generates a package-facing `skillshop.manifest.mjs`. It also adds the standard `./skillshop` package export and, when `package.json#files` is present, ensures the exported skill directories are shipped.
+For example, `.agents/skills/review/SKILL.md` could contain:
 
-This makes a skill library behave like a component package: producers export named components; applications resolve or materialize only the components they choose.
+```markdown
+---
+name: review
+description: Review a proposed code change
+---
 
-## Explicit export boundary
+# Review
 
-`skillshop.library.json` is the **only** skill export definition. The `exports` map is an allowlist, not a directory scan. In particular, `.agents/skills/` is just a possible source/install location: a repository can contain any number of valid `SKILL.md` files there without publishing any of them.
+Read the diff, identify concrete defects, and cite the affected files.
+```
 
-- `skillshop init` creates an empty `exports: {}` map; it does not discover or publish skills.
-- `skillshop build` requires that source manifest and generates entries only for explicitly named local exports and re-exports. Missing manifests fail validation; empty manifests publish zero skills.
-- `skillshop resolve` and `skillshop import` reject unlisted `skill:*` names, even when their files are present on disk.
-- `skillshop export` and `skillshop unexport` explicitly change that public surface. Removing an export does not delete the repository's local skill files.
-- Aggregators must also explicitly list every upstream skill they re-export; importing a dependency does not re-export its entire library.
+Keep any references or scripts needed by the skill beside its `SKILL.md`; Skillshop copies the whole directory.
 
-Skillshop only adds **declared local skill directories** to its managed `package.json#files` entries. Its export allowlist governs the Skillshop API, not arbitrary physical file access: if your own package `files` patterns include other private skills, npm may still publish those files. Keep such paths out of broad package globs if they must not ship.
+Add Skillshop, initialize the export list, and name the skill you want to publish:
 
-A library can also re-export another library's skill without copying its source:
+```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:clips": {
-      "from": "@dfosco/clips",
-      "skill": "skill:clips"
-    }
+    "skill:review": "./.agents/skills/review",
+    "skill:triage": "./.agents/skills/triage"
   }
 }
 ```
 
-The upstream package must be a runtime dependency or a non-optional peer dependency so the generated manifest can safely load its standard `<package>/skillshop` export.
+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.
 
-## CLI
+### 2. Declare user-level installation, if needed
 
-Initialize a library:
+To copy selected skills during a global npm install, add `skillshop.userInstall` and the generic lifecycle command to the distributor's `package.json`:
 
-```bash
-skillshop init
+```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"]
+  }
+}
 ```
 
-Export skills:
+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.
 
-```bash
-skillshop export skill:clips ./.agents/skills/clips
-skillshop export skill:loopz ./.agents/skills/loopz
-skillshop export skill:clips --from @dfosco/clips
-skillshop list
-skillshop validate
-skillshop build
-```
+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.
 
-Consume a skill from an installed package or a local package directory:
+### 3. Check and pack the package
 
 ```bash
-skillshop resolve @dfosco/clips skill:clips
-skillshop import @dfosco/clips skill:clips --to .agents/skills/clips
+npx skillshop library list
+npx skillshop validate
+npx skillshop build
+npm pack --dry-run
 ```
 
-`--force` replaces an existing import target. Without `--force`, the CLI does not overwrite an existing skill directory.
+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.
 
-**Imports are snapshots:** `importSkill` copies the complete skill directory to the destination. Imported files do not depend on the source package afterward and are never changed or deleted by a later `unexport`. To apply an updated source, the consumer must import it again explicitly.
+After checking the tarball, publish the package with `npm publish`. Use `npm publish --access public` for a public scoped package.
 
-For applications that update only files owned by a skill while preserving local additions, the SDK also supports `merge: true`:
+### Example: what happens after publication
 
-```js
-const result = await importSkill({
-  library: '/path/to/a/skill-library',
-  specifier: 'skill:clips',
-  targetDir: '.agents/skills/clips',
-  merge: true,
-});
-// result.installed and result.updated indicate newly copied or changed files.
+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
 ```
 
-The merge mode overlays source files and leaves unrelated destination files untouched. It is opt-in; the normal import still refuses an existing destination unless `overwrite: true` is set.
+An application that needs `skill:triage` can install the package locally and copy that exported skill into its own repository:
 
-## SDK
+```bash
+cd ~/work/sample-app
+npm install @example/skill-library skillshop
+npx skillshop import @example/skill-library:triage
+```
 
-Skillshop exports the builder and consumer capabilities as normal application modules:
+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.
 
-```js
-import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
-import { resolveSkill, importSkill } from 'skillshop/import';
-```
+### Re-export a skill from another library
 
-Build a library programmatically:
+A package can expose a selected upstream skill under its own name:
 
-```js
-exportSkill({
-  root: process.cwd(),
-  specifier: 'skill:clips',
-  source: './.agents/skills/clips',
-});
+```bash
+npm install @example/upstream
+npx skillshop export skill:review --from @example/upstream --skill skill:review
+```
 
-reexportSkill({
-  root: process.cwd(),
-  specifier: 'skill:loopz',
-  from: '@dfosco/clips',
-});
+The resulting export in `skillshop.library.json` is:
 
-buildSkillLibrary(process.cwd());
+```json
+{
+  "skill:review": {
+    "from": "@example/upstream",
+    "skill": "skill:review"
+  }
+}
 ```
 
-Resolve without copying, which is useful for applications such as Hypercanvas:
+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.
 
-```js
-const clips = await resolveSkill({
-  library: '@dfosco/clips',
-  specifier: 'skill:clips',
-});
+## CLI and JavaScript API
 
-console.log(clips.manifestPath);
+```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 [--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>]
 ```
 
-Or materialize the complete skill component:
+`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
-await importSkill({
-  library: '@dfosco/clips',
-  specifier: 'skill:loopz',
-  targetDir: '.agents/skills/loopz',
-});
+import { exportSkill, reexportSkill, buildSkillLibrary } from 'skillshop/export';
+import { resolveSkill, importSkill } from 'skillshop/import';
+import { installDeclaredUserSkills } from 'skillshop/user-install';
 ```
 
-## Package contract
+For example, an application can read an exported skill directly from an installed package, or copy it into a workspace it manages:
 
-Published libraries expose one standard package subpath:
+```js
+import { readFile } from 'node:fs/promises';
+import { resolveSkill, importSkill } from 'skillshop/import';
 
-```text
-<package>/skillshop
-```
+const reference = '@example/skill-library:triage';
+const { manifestPath } = await resolveSkill({ reference });
+const instructions = await readFile(manifestPath, 'utf8');
+// Pass instructions to your agent runtime.
 
-Skillshop generates that manifest. Consumers therefore do not need package-specific JS exports such as `clipsSkill` or `loopzSkill`.
+await importSkill({
+  reference,
+  overwrite: true,
+});
+```
 
-The producer package, a personal library, and an application are separate concerns:
+`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.
 
-- **Skillshop** defines the protocol and tooling.
-- **Clips** can export `skill:clips` and `skill:loopz`.
-- **A personal library** can aggregate local skills and re-export `skill:*` components from packages such as Clips without vendoring them.
-- **Hypercanvas** can optionally resolve/import Clips workflow skills for Squads.
+`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/agents-content/000_communication-writing.block.md

@@ -0,0 +1,11 @@
+## Communication and writing
+
+- Write directly and concisely. Prefer short, distinct sentences over long compound ones.
+- Do not overuse em dashes. There are periods, commas, semicolons, and exclamation marks. Use them.
+- Remove hedges and filler that add no information. Keep technical terms when they add precision.
+- Avoid exact counts unless the number matters. "All the callers" is usually better than "all 4 callers."
+- Short, natural reactions are fine. Use "Good catch!" rather than an inflated response.
+- Avoid throat clearing, restating the question, routine process narration, and closing offers. Brief accountability or correction is fine when it helps the reader.
+- Do not explain in prose what a table or diff already makes clear.
+- State genuine uncertainty briefly. Do not add defensive caveats or pre-empt objections nobody raised.
+- Brevity must not hide important behavior, risk, uncertainty, or evidence.

package/agents-content/001_external-actions.block.md

@@ -0,0 +1,9 @@
+### Approval for external actions
+
+All external actions require explicit approval before proceeding. Even on autopilot mode, do not post without explicit written authorizaton from the user.
+
+- Before posting or editing a PR comment, review reply, issue comment, Slack message, or other external message, show me the exact draft and get an explicit OK. This includes edits to existing messages.
+- Before resolving review threads, requesting reviewers, or changing other visible review state, describe the exact action and get an explicit OK.
+- Create an issue, epic, or PR only when I explicitly request it. Before opening one, show me its proposed title and body and get an explicit OK.
+- A direct request to update an existing PR or issue body authorizes that update without another approval. Fetch the latest body from the host immediately before editing it.
+- Pushing requested commits does not require another approval.

package/agents-content/AGENTS.md

@@ -0,0 +1,11 @@
+### Baseline tone
+
+This applies to every text that you write.
+
+Adopt a skeptical, questioning approach. Don't default to praise, criticize my ideas, provide counterpoints, dig deeper. I need you to find the blind spots in my thinking and account for them, in a straight shooting and constructive way.
+
+Don't overuse adjectives, don't compliment or criticize my arguments in a personalized way, just attend to the facts and topics. Tell it like it is; don't sugar-coat responses. Also don't explicitly mention you're NOT praising me or actively say you're “getting to the point”. Don't comment on your tone at all.
+
+When explaining things, provide depth of concepts, be extensive, with context, clarity and explanation of concepts along the way.
+
+{{ blocks }}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "skillshop",
-  "version": "2.0.0",
-  "description": "Build, export, resolve, and import portable agent skill libraries",
+  "version": "2.1.0",
+  "description": "Build, export, resolve, and install portable agent skill libraries",
   "type": "module",
   "bin": {
     "skillshop": "./src/cli.js",
-    "skillz": "./src/cli.js"
+    "sk": "./src/cli.js"
   },
   "exports": {
     ".": "./src/index.js",
     "./library": "./src/library.js",
     "./export": "./src/export.js",
     "./import": "./src/import.js",
+    "./user-install": "./src/user-install.js",
     "./specifier": "./src/specifier.js"
   },
   "files": [
+    "agents-content/",
+    "skills-content/",
     "src/",
     "README.md"
   ],