docs(skills): the end state after create-objectstack installs @objectstack/skills — one pinned --copy spelling, one next.0 exception, and the 17.x to 18 skills step (#23275)

content/docs/ai/skills-reference.mdx

@@ -14,30 +14,28 @@ ObjectStack ships a set of **domain-specific skills** that teach AI assistants (
 
 ## Installing skills
 
-The catalog ships as the npm package [`@objectstack/skills`](https://www.npmjs.com/package/@objectstack/skills), released together with every other `@objectstack/*` package at one shared version. Install it at the version of the `@objectstack/spec` your project has installed — the catalog's version is then your spec's, so the skills teach what that spec accepts — and sync it from `node_modules` into your coding agent's skills directory:
+The catalog ships as the npm package [`@objectstack/skills`](https://www.npmjs.com/package/@objectstack/skills), released together with every other `@objectstack/*` package at one shared version. Install it at the version of the `@objectstack/spec` your project has installed — the catalog's version is then your spec's, so the skills teach what that spec accepts — and copy it from `node_modules` into your coding agent's skills directory:
 
 ```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")"
 
-# 2 · link it from node_modules into your agent's skills directory
-npx skills experimental_sync --agent claude-code -y
+# 2 · copy it from node_modules into your agent's skills directory
+npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
-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/`, links each one into `.agents/skills/<skill>` (and, for `claude-code`, `.claude/skills/<skill>` to that), and records the source and version in `skills-lock.json`. Name your own runtime after `--agent` (`codex`, `cursor`, …). Add `--copy` to write real files instead of links — for `claude-code` the catalog then lands once, in `.claude/skills/`, and nowhere else. 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.
+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/<skill>` 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).
+**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`).
+**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.
 
-**New projects.** `create-objectstack` installs the skills for one agent runtime while it scaffolds — once, into `.claude/skills/` — and its closing summary prints the command for any other runtime you use.
+**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.
 
 ```bash
 npm create objectstack@latest my-app
 ```
 
-Through `18.0.0-next.0` the scaffolder takes those skills from the `next` channel below with `skills add`, not from `@objectstack/skills`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add`). To bind a scaffolded project's skills to a version the package is published at, remove them first — `npx skills remove --all` removes every installed skill; name the `objectstack-*` ones instead (`npx skills remove objectstack-data objectstack-ui …`) if you added others — then run steps 1 and 2.
-
 **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 the next version's skills, not for a released project.
 
 ---

content/docs/ai/skills.mdx

@@ -26,14 +26,14 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for
 
 ## Installing skills
 
-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 sync it from `node_modules` into your agent's directory:
+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")"
-npx skills experimental_sync --agent claude-code -y
+npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
-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 the versions, `--copy`, projects scaffolded by `create-objectstack` and the `next` channel, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
+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).
 
 ---
 

content/docs/getting-started/build-with-claude-code.mdx

@@ -57,14 +57,13 @@ The scaffolder does more than copy files. It:
 - derives a **namespace** from the name (`support-desk` → `support_desk`), so
   every object you create is named `support_desk_*`;
 - installs dependencies;
-- installs the **AI skills bundle** for one agent runtime — once, into
-  `.claude/skills/` — and prints the command for any other runtime you use.
-  Through `18.0.0-next.0` that bundle comes from the repository's unreleased
-  `main`, not from your version; to make the catalog's version your installed
-  `@objectstack/spec`'s, replace it with the `@objectstack/skills` package and
-  `npx skills experimental_sync --agent claude-code -y`
+- installs the **AI skills bundle** for one agent runtime from the
+  `@objectstack/skills` package, at your `@objectstack/spec`'s version — copied
+  once into `.claude/skills/`, to commit with the project — and prints the
+  command for any other runtime you use
   ([Installing skills](/docs/ai/skills-reference#installing-skills) has the
-  steps, and the versions the package is published at);
+  steps, the versions the package is published at, and the one scaffolder
+  version that is an exception);
 - writes an **`AGENTS.md`** (and `.github/copilot-instructions.md`) that teach your
   coding agent the project layout, the naming rules, and — critically — *to run
   `npm run validate` after every metadata change*.
@@ -428,8 +427,9 @@ Three habits keep this reliable as the app grows:
 - **Keep the skills current.** The catalog's version is your installed
   `@objectstack/spec`'s: when you upgrade, bump `@objectstack/skills` with the
   other `@objectstack/*` packages, then re-run
-  `npx skills experimental_sync --agent claude-code -y` — name your own runtime
-  after `--agent` — so the agent authors against the schemas you actually run.
+  `npx skills@1.7.2 experimental_sync --agent claude-code --copy -y` — name your
+  own runtime after `--agent` — and commit what it changed, so the agent authors
+  against the schemas you actually run.
   The install steps, and the versions the package is published at, are in the
   [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
 

content/docs/getting-started/your-first-project.mdx

@@ -43,15 +43,14 @@ The scaffolder (`create-objectstack`) does four things:
    renamed to carry that prefix (`my_app_note`), which is what
    `os validate` later enforces.
 2. **Installs dependencies** (pnpm if available, otherwise npm).
-3. **Installs the AI skills bundle for one coding agent** — once, into
-   `.claude/skills/` — so a coding agent is productive in the project from the
-   first prompt. The closing summary prints the command for any other runtime
-   you use. Through `18.0.0-next.0` the bundle comes from the repository's
-   unreleased `main`, not from your version; to make the catalog's version your
-   installed `@objectstack/spec`'s, replace it with the `@objectstack/skills`
-   package and `npx skills experimental_sync --agent claude-code -y`
+3. **Installs the AI skills bundle for one coding agent** from the
+   `@objectstack/skills` package, at your installed `@objectstack/spec`'s
+   version — copied once into `.claude/skills/`, to commit with the project — so
+   a coding agent is productive in the project from the first prompt. The
+   closing summary prints the command for any other runtime you use
    ([Installing skills](/docs/ai/skills-reference#installing-skills) has the
-   steps, and the versions the package is published at).
+   steps, the versions the package is published at, and the one scaffolder
+   version that is an exception).
 4. **Writes `AGENTS.md`** (and `.github/copilot-instructions.md`) with the
    project conventions — including the rule to run `npm run validate` after
    every metadata change.
@@ -353,12 +352,12 @@ Each of those lands in a different metadata domain (UI, dashboards,
 automation) — the agent loads the matching skill per task. The full loop, and a
 per-domain prompt catalog, is on
 [Build with Claude Code](/docs/getting-started/build-with-claude-code#beyond-the-first-app--one-skill-per-metadata-domain).
-The catalog's version is your installed `@objectstack/spec`'s once it comes
-from the `@objectstack/skills` package (step 1.3): when you upgrade, bump
-`@objectstack/skills` with the other `@objectstack/*` packages, then re-run
-`npx skills experimental_sync --agent claude-code -y` to keep the agent in sync
-with the schemas you run. Name your own runtime after `--agent` if it is not
-Claude Code.
+The catalog's version is your installed `@objectstack/spec`'s (step 1.3): when
+you upgrade, bump `@objectstack/skills` with the other `@objectstack/*`
+packages, then re-run
+`npx skills@1.7.2 experimental_sync --agent claude-code --copy -y` and commit
+what it changed, to keep the agent in sync with the schemas you run. Name your
+own runtime after `--agent` if it is not Claude Code.
 
 ## Next steps
 

content/docs/releases/v18/index.mdx

@@ -37,6 +37,28 @@ under the same rules.
   v18 prerelease's handshake admits `engines.protocol: '^18'` and refuses
   `'^17'`. Read [Upgrading](/docs/upgrading) before you move an app's declared
   range.
+- **The AI skills move with the packages.** From v18 the skills catalog is the
+  `@objectstack/skills` package, on the same version as every other
+  `@objectstack/*` package, and it moves only with them. A 17.x project has no
+  such dependency — its skills were installed with `skills add` from the
+  repository's `main` — and the sync from the package skips every skill a
+  `skills add` installed (`Skipped … installed with skills add`, exit 0), so
+  bumping the packages alone keeps the 17.x-era skill text. After moving the
+  `@objectstack/*` dependencies to 18, remove those skills, then add the
+  catalog at the new `@objectstack/spec`'s version and copy it into your
+  agent's directory ([Upgrading](/docs/upgrading#moving-the-dependency-pins),
+  step 4):
+
+  ```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")"
+  npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
+  ```
+
+  `npx skills remove --all` replaces the first command when these are the only
+  skills the project has.
 - **GA ends the prerelease.** Reaching GA exits pre mode and publishes the line
   to `latest`. Curated notes for the line's releases are compiled at release
   time and are not written yet; until then, the changesets are the record.

content/docs/upgrading.mdx

@@ -68,7 +68,7 @@ Not every deployment moves a tag. An app that consumes the platform as **npm
 dependencies** — `@objectstack/*` in its own `package.json`, which is the shape
 [`create-objectstack`](/docs/getting-started/quick-start) scaffolds — carries the
 platform version in its dependency tree and moves it there. There is no `os`
-command for this move; it is three steps you run yourself.
+command for this move; it is four steps you run yourself.
 
 1. **Bump every `@objectstack/*` dependency together, to the same version.**
    The train is version-locked — every package on it shares one version number —
@@ -87,6 +87,34 @@ command for this move; it is three steps you run yourself.
    manifest. Both name the protocol **major**, so a move inside one major leaves
    both alone, and a major boundary is where they change. Move them deliberately
    when you cross one; never edit them to silence a mismatch.
+4. **Re-install the AI skills from the moved catalog, and commit them.** The
+   skills your coding agent reads come from the `@objectstack/skills` dev
+   dependency, which moves only with the other `@objectstack/*` packages — in
+   step 1, never on its own — and step 2 only puts it in `node_modules`. Copy it
+   into your agent's directory (name your own runtime after `--agent`):
+
+   ```bash
+   npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
+   ```
+
+   **From 17.x to 18**, a project has no `@objectstack/skills` to move: its
+   skills were installed with `skills add` from the repository's `main`, and the
+   sync skips every skill a `skills add` installed (it prints
+   `Skipped … installed with skills add` and exits 0), so a project that only
+   bumps its packages keeps its 17.x-era skill text. Remove those skills first,
+   then add the catalog at your new `@objectstack/spec`'s version and 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")"
+   npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
+   ```
+
+   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.
 
 Then run [the loop](#the-loop) below — `os validate` before `os build` — because
 moving the pins can move the gate.