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

The scaffolder now installs the catalog from @objectstack/skills at the
project's @objectstack/spec version and copies it into .claude/skills/, so the
three transitional "through 18.0.0-next.0" passages are rewritten to that end
state, and the one scaffolder that still read main is named once, in the
skills reference's "Which versions exist". Every sync on the site is now the
scaffolder's own command, npx skills@1.7.2 experimental_sync --agent
claude-code --copy -y. upgrading.mdx gains step 4 of "Moving the dependency
pins" and the v18 line page gains the same 17.x to 18 skills step: remove the
skills add-installed skills, add the catalog at the new spec version, copy it.

Claude-Session: https://claude.ai/code/session_012zwsLMxQBwHUYJgPyrpEvx
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

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.