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: