skillshop 2.0.0 → 2.2.0

package/README.md

@@ -1,168 +1,341 @@
 # 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
+```
+
+`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:
+
+```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. 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.
+
+### 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.
+
+### Upgrade Skillshop
+
+```bash
+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.
+
+`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.
+
+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 init
+skillshop agents --check
+skillshop agents --global
 ```
 
-The library owns where its `SKILL.md` lives. Consumers only depend on the `skill:*` name.
+There are two local modes. Plain `skillshop agents` keeps the bounded legacy behavior for an uninitialized project: it updates the nearest existing `AGENTS.md` within the selected boundary, or creates one at the boundary root if none exists. After project sources are initialized, plain `skillshop agents` renders them instead. The global command remains separate and updates the supported user instruction files.
 
-## The model
+Initialize project-owned instructions with `skillshop agents init`. The neutral starter template is `.agents/instructions/AGENTS.template.md`; put source blocks beside it as `*.block.md`. Skillshop renders these sources into a distinct managed region in the project-root `AGENTS.md`. Existing user text and prior Skillshop managed guidance are preserved. Edit the template and source blocks, not the generated region. Repeated `skillshop agents init` leaves existing sources alone. If an initialized project's template is removed, `skillshop agents` reports an error rather than restoring bundled personal guidance. Symlinked source, template, block, or output path components are rejected, including dangling links.
 
-A producer package keeps a source manifest:
+The default boundary is the nearest Git repository or worktree root. Outside Git, the current working directory is the boundary. Use `--project <directory>` to choose another boundary; a relative path is resolved from the command's current directory. This is required when a nested project inside a larger repository should own its own output. Put all three explicit-boundary scripts in `packages/app/package.json` so init, rendering, and checking stay in that package:
 
 ```json
 {
-  "schemaVersion": 1,
-  "exports": {
-    "skill:clips": "./.agents/skills/clips",
-    "skill:loopz": "./.agents/skills/loopz"
+  "scripts": {
+    "agents": "skillshop agents --project .",
+    "agents:init": "skillshop agents init --project .",
+    "agents:check": "skillshop agents --check --project ."
   }
 }
 ```
 
-`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 a local project dependency, add Skillshop as a development dependency and opt into rendering through explicit scripts:
+
+```bash
+npm install --save-dev skillshop
+```
+
+```json
+{
+  "scripts": {
+    "agents": "skillshop agents",
+    "agents:init": "skillshop agents init",
+    "agents:check": "skillshop agents --check"
+  }
+}
+```
+
+Run `npm run agents:init` once, edit the project sources, then run `npm run agents`. `npm run agents:check` exits successfully when the generated region in the working tree matches the current sources; it does not inspect Git's index or commit. CI can run `npm ci` followed by `npm run agents:check`. Commit the npm manifest and lockfile, `.agents/instructions/AGENTS.template.md`, its source blocks, and the rendered root `AGENTS.md`. There is no install hook: initialization and rendering happen only when the scripts are run.
+
+Project and bundled source templates support explicit includes:
+
+```markdown
+{{ include "020_testing.block.md" }}
+
+{{ blocks }}
+```
+
+Use `{{ include "020_testing.block.md" }}` or `{{ include '020_testing.block.md' }}` for named blocks. The older `{{ fragments["020_testing.block.md"] }}` and single-quoted lookup forms remain supported. `{{ blocks }}` inserts the remaining fragments in filename order, excluding every explicitly included file even when its include appears later in the template. Repeated includes render at each position. Fragment contents are inserted literally; placeholder-looking text inside a block is not evaluated recursively. Invalid expressions and missing fragments fail before generated output is written.
+
+These expressions apply to source templates only. Skillshop does not interpret them in destination instruction files or sibling fragments.
+
+### 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.
 
-This makes a skill library behave like a component package: producers export named components; applications resolve or materialize only the components they choose.
+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.
 
-## Explicit export boundary
+## For project owners: distribute skills
 
-`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.
+### 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 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.
+For example, `.agents/skills/review/SKILL.md` could contain:
 
-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.
+```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
+```
 
-A library can also re-export another library's skill without copying its source:
+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 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>]
 ```
 
-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.2.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"
   ],