From bd085862fcd1b4f9e1a899ccb53d04cca71da160 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 19:20:02 +0000 Subject: [PATCH] docs: give the @objectstack/skills install line for the project's own package manager The three content/docs sites printed `npm install --save-dev` as the only command; in a pnpm-installed project it exits 1 with `npm error Cannot read properties of null (reading 'edgesOut')`. Each site now carries the pnpm line, a comment with the npm and yarn spellings, and the rule to add the package with the manager that installed the project. The 17.x refusal names the pnpm code beside npm's, and skills-reference runs `npx skills list` before `npx skills remove --all`. Claude-Session: https://claude.ai/code/session_01FM29ZqLTrnPNXxijioZwMp Co-authored-by: Claude --- content/docs/ai/skills-reference.mdx | 7 +++++-- content/docs/ai/skills.mdx | 5 ++++- content/docs/upgrading.mdx | 6 +++++- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx index 243ea078de7..69d601e6e41 100644 --- a/content/docs/ai/skills-reference.mdx +++ b/content/docs/ai/skills-reference.mdx @@ -18,17 +18,20 @@ The catalog ships as the npm package [`@objectstack/skills`](https://www.npmjs.c ```bash # 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')`. + Step 2 is the [skills CLI](https://www.npmjs.com/package/skills)'s sync from `node_modules`: it finds the skills under `node_modules/@objectstack/skills/dist/skills/`, copies each one into your agent's directory — for `claude-code`, real files in `.claude/skills/` and nowhere else — and records the source and version in `skills-lock.json`. Commit both with the project. Keep `--copy`: without it the sync writes links into `node_modules`, which is not committed, so a clone of the project gets dangling links and no skills. The CLI is pinned because `experimental_sync` is that tool's own unstable interface; `create-objectstack` runs the same version. Name your own runtime after `--agent` (`codex`, `cursor`, …), one runtime per run — never `--agent '*'`, which copies the catalog into dozens of agent directories at once. A bare `npm install --save-dev @objectstack/skills` installs whichever version the registry tags `latest`, not your spec's — keep the version in step 1. **Updating.** The catalog is versioned as **one bundle**, and it moves only with your ObjectStack version — you never track or update a skill on its own: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the sync (step 2, same flags) and commit what it changed. -**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ETARGET` (`No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded run `npx skills remove --all` — or remove the `objectstack-*` skills by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2. +**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both print `No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded 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 remove those by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2. **New projects.** `create-objectstack` runs both steps while it scaffolds: the `package.json` it writes depends on `@objectstack/skills` at the same version as `@objectstack/spec`, its dependency install puts the catalog in `node_modules`, and step 2 copies it for one agent runtime, into `.claude/skills/`. Its closing summary prints step 2 again — to re-run after an upgrade, and with another `--agent` for any other runtime you use. diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx index 4abb2d104fa..cee600755a4 100644 --- a/content/docs/ai/skills.mdx +++ b/content/docs/ai/skills.mdx @@ -29,10 +29,13 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for Skills ship as the npm package `@objectstack/skills`, released with the other `@objectstack/*` packages at one shared version. Install it at your installed `@objectstack/spec`'s version — the catalog's version is then your spec's — and copy it from `node_modules` into your agent's directory, the two steps `create-objectstack` runs when it scaffolds a project: ```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 ``` +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')`. + The skills land as real files in `.claude/skills/`; commit them with the project, and keep `--copy` — without it they are links into `node_modules`, which a clone does not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). The catalog is versioned and updated as **one unit**, with ObjectStack itself: 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); for what the sync writes, the versions, the one scaffolder that is an exception and the `next` channel, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills). --- diff --git a/content/docs/upgrading.mdx b/content/docs/upgrading.mdx index e858d1052df..07f9199202f 100644 --- a/content/docs/upgrading.mdx +++ b/content/docs/upgrading.mdx @@ -108,10 +108,14 @@ command for this move; it is four steps you run yourself. 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 ``` + 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')`. The list names every skill the catalog carried during 17.x, and a name that is not installed is skipped; `npx skills remove --all` does the same when these are the only skills the project has. Run `npx skills list` first: