From f0b0ddc2de357c1cf9b049b356eb7266a4be90e1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 01:09:14 +0000 Subject: [PATCH] docs(skills): give the @objectstack/skills install line for the project's own package manager The npm page, the catalog's front page and the upgrade skill's re-install step printed the npm-only line, which exits 1 in a pnpm-installed project. Each now prints the pnpm line with the npm and yarn spellings beside it and the rule: add the package with the manager that installed the project. Claude-Session: https://claude.ai/code/session_01M82feuetLzrCiBz41BJb7L Co-authored-by: Claude --- .changeset/24974-skills-install-line.md | 12 ++++++++++++ packages/skills/README.md | 20 ++++++++++++++------ skills/README.md | 19 +++++++++++-------- skills/objectstack-upgrade/SKILL.md | 13 ++++++------- 4 files changed, 43 insertions(+), 21 deletions(-) create mode 100644 .changeset/24974-skills-install-line.md diff --git a/.changeset/24974-skills-install-line.md b/.changeset/24974-skills-install-line.md new file mode 100644 index 00000000000..ad18da907ee --- /dev/null +++ b/.changeset/24974-skills-install-line.md @@ -0,0 +1,12 @@ +--- +'@objectstack/skills': patch +--- + +docs(skills): the npm page and the catalog's front page give the install line for the project's own package manager + +Clause-②: no + +`README.md` (the npm page) and `dist/skills/README.md` (the catalog's front page, copied from the repository's `skills/README.md`) printed `npm install --save-dev "@objectstack/skills@$(node -p …)"` as the only install line. In a pnpm-installed project that line exits `1` with `npm error Cannot read properties of null (reading 'edgesOut')` and writes nothing, and `create-objectstack` installs with pnpm when it is available, so a scaffolded project is commonly a pnpm project. + +- **Both pages** now print `pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"`, with the npm and yarn spellings on a comment line beside it, and the rule: add the package with the manager that installed the project. The `objectstack-upgrade` skill's re-install step, which an agent follows for this exact move, prints the same line. +- **The npm page** names pnpm's `ERR_PNPM_NO_MATCHING_VERSION` beside npm's `ETARGET` for a project on `@objectstack/spec` 17.x, and runs `npx skills list` before `npx skills remove --all`, which removes every installed skill without asking. diff --git a/packages/skills/README.md b/packages/skills/README.md index 9ec39c4c6dc..4778e177e68 100644 --- a/packages/skills/README.md +++ b/packages/skills/README.md @@ -25,20 +25,25 @@ agent's own skills directory (`.claude/skills/` for Claude Code, and so on): ```sh # 1 · the catalog, at the version of your installed @objectstack/spec -npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +# npm: npm install --save-dev "@objectstack/skills@…" · yarn: yarn add -D "@objectstack/skills@…" # 2 · copy it from node_modules into your agent's skills directory npx skills@1.7.2 experimental_sync --agent claude-code --copy -y ``` +Add the package with the manager that installed the project: in a pnpm project, +`npm install --save-dev` exits `1` with +`npm error Cannot read properties of null (reading 'edgesOut')`. + `experimental_sync` discovers the skills at `dist/skills//SKILL.md` of every dependency and copies each one into the named agent's skills directory as real files, recording the source in `skills-lock.json` (`--agent ` names the runtime — `codex`, `cursor`, …). Keep `--copy`: without it the sync writes links into `node_modules`, which a clone of the project does not have; the CLI is pinned to the version `create-objectstack` runs. Keep the version -in step 1: a bare `npm install --save-dev @objectstack/skills` installs -whichever version the registry tags `latest`, not your spec's. +in step 1: a bare `pnpm add -D @objectstack/skills` installs whichever version +the registry tags `latest`, not your spec's. **Updating.** The catalog moves only with your ObjectStack version: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the @@ -46,13 +51,16 @@ sync (step 2, same flags). **Which versions exist.** The package is published from `18.0.0-next.0` on; there is no 17.x release of it, so on a project whose `@objectstack/spec` is -17.x step 1 refuses with `ETARGET` (`No matching version found`). +17.x step 1 refuses with `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both +print `No matching version found`). **Projects scaffolded by `create-objectstack`.** Through `18.0.0-next.0` the scaffolder installs the skills from the `next` channel below with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … -installed with skills add`). Remove them first — `npx skills remove --all`, or -name the `objectstack-*` skills if you added others — then run steps 1 and 2. +installed with skills add`). Run `npx skills list` first, because +`npx skills remove --all` removes every installed skill without asking: run that +when the list shows only the `objectstack-*` skills, or name those if you added +others — then run steps 1 and 2. ## The `next` channel diff --git a/skills/README.md b/skills/README.md index c092455658c..9e9b29eec34 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,17 +8,20 @@ They ship as the npm package `@objectstack/skills`, released with the other copy it from `node_modules` into your agent's directory: ```bash -npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +# npm: npm install --save-dev "@objectstack/skills@…" · yarn: yarn add -D "@objectstack/skills@…" npx skills@1.7.2 experimental_sync --agent claude-code --copy -y ``` -Keep `--copy`: the skills land as real files in `.claude/skills/`, to commit with -the project; without it they are links into `node_modules`, which a clone does -not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). To update, -bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run -the sync. The package is published from `18.0.0-next.0` on (there is no 17.x -release); scaffolded projects, the move from a `skills add` install and the rest -are in the [Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills). +Add the package with the manager that installed the project: in a pnpm project, +`npm install --save-dev` exits `1`. Keep `--copy`: the skills land as real files +in `.claude/skills/`, to commit with the project; without it they are links into +`node_modules`, which a clone does not have. Name your own runtime after +`--agent` (`codex`, `cursor`, …). To update, bump `@objectstack/skills` with the +other `@objectstack/*` packages, then re-run the sync. The package is published +from `18.0.0-next.0` on (there is no 17.x release); scaffolded projects, the move +from a `skills add` install and the rest are in the +[Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills). **The `next` channel.** `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y` reads the catalog straight from the repository's unreleased `main` — for trying diff --git a/skills/objectstack-upgrade/SKILL.md b/skills/objectstack-upgrade/SKILL.md index 885583cfcd0..250a9df504c 100644 --- a/skills/objectstack-upgrade/SKILL.md +++ b/skills/objectstack-upgrade/SKILL.md @@ -118,15 +118,16 @@ deleting them on merge, is the usual arrangement — decide it with the owner. A 17.x project's skills came from `skills add`; their `skills-lock.json` entries read `sourceType: github`, so the sync skips them (exit 0) and the agent keeps -reading 17.x skill text. Remove them (a missing name is skipped; `--all` when -they are the project's only skills), add `@objectstack/skills` at the installed -spec's version, copy it: +reading 17.x skill text. Remove them (a missing name is skipped), add +`@objectstack/skills` at the installed spec's version with the manager that +installed the project, copy it: ```bash npx skills remove objectstack-ai objectstack-api objectstack-automation \ objectstack-data objectstack-formula objectstack-i18n objectstack-platform \ objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y -npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")" +# npm: npm install --save-dev "@objectstack/skills@…" · yarn: yarn add -D "@objectstack/skills@…" npx skills@1.7.2 experimental_sync --agent claude-code --copy -y ``` @@ -253,9 +254,7 @@ upgrade and again in the report. > **Not reachable from a consumer project**, so do not send anyone there: the > conversion and migration registries (`src/conversions/registry.ts`, > `src/migrations/registry.ts`) and the platform repo's generated upgrade guide -> are **not** in the published package — only `src/**/*.zod.ts` is. Their -> consumer-facing projection is `spec-changes.json` and the chain's own `--json` -> output. +> are **not** in the published package — only `src/**/*.zod.ts` is. ### 2.2 The three residue classes