@@ -14,27 +14,31 @@ ObjectStack ships a set of **domain-specific skills** that teach AI assistants (
 
 ## Installing skills
 
-Skills install into a project from the [skills.sh](https://skills.sh) registry, reading the `skills/` directory of the [`objectstack-ai/objectstack`](https://github.com/objectstack-ai/objectstack) repository.
-
-**New projects — installed automatically.** `create-objectstack` runs the install step for you during scaffolding, for a single agent runtime: the bundle lands once, in `.claude/skills/`, and the scaffolder's closing summary prints the exact command it ran — with a different agent name for any other runtime you use.
+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:
 
 ```bash
-npm create objectstack@latest my-app
+# 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
 ```
 
-**Existing projects — install the whole bundle:**
+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.
+
+**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).
+
+**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`).
+
+**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.
 
 ```bash
-npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
+npm create objectstack@latest my-app
 ```
 
-Name your own runtime after `--agent` (`codex`, `cursor`, …) — the bundle is byte-identical whichever you name, and it lands **once**, in that agent's own directory (`.claude/skills/` for `claude-code`). Run the same command again at any time to pull the latest versions: re-running is idempotent per destination, so updating is one command regardless of how many skills the bundle contains. To choose which skills to add instead of the full set, run `npx skills add objectstack-ai/objectstack/skills` with neither `--skill` nor `--all` and pick from the list. (The `/skills` subpath scopes discovery to the published catalog — always keep it in the command.)
-
-**The multi-runtime opt-in, and what it costs.** Replacing `--skill '*' --agent claude-code -y` with `--all` installs for every runtime the skills CLI knows. It is the same bundle, but it writes it to **three** destinations instead of one — a full real copy in **both** `.agents/` and `agent/`, plus `.claude/` symlinks pointing into `.agents/`. Inside a git repository that means the first `git add -A` stages the bundle twice over, plus the symlinks. Idempotence does not help here: re-running is idempotent *per destination*, and it is the destination count that grows. Name one `--agent` per runtime you actually use instead.
+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.
 
-<Callout type="info">
-Skills are versioned as **one bundle**. You do not track or update each skill individually — `--skill '*'` always installs the matching set for the `@objectstack/spec` version in your project.
-</Callout>
+**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.
 
 ---
 
 
@@ -26,17 +26,14 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for
 
 ## Installing skills
 
-Skills are distributed through the [skills.sh](https://skills.sh) registry from the [`objectstack-ai/objectstack`](https://github.com/objectstack-ai/objectstack) repository's `skills/` 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 sync it from `node_modules` into your agent's directory:
 
 ```bash
-# New project — create-objectstack installs them automatically, for one agent
-npm create objectstack@latest my-app
-
-# Existing project — add the whole bundle for your agent (re-run to update)
-npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
+npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+npx skills experimental_sync --agent claude-code -y
 ```
 
-Name your own runtime after `--agent` (`codex`, `cursor`, …); the bundle lands **once**, in that agent's own directory. It is versioned and updated as **one unit** — re-running the command is idempotent, so you never track skills individually. `--all` installs for every runtime the CLI knows and writes the bundle to **three** destinations instead of one; for that trade-off and the rest of the install options, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
+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).
 
 ---
 
 
@@ -57,10 +57,14 @@ 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;
-- runs `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`
-  to install the **AI skills bundle** for one agent runtime — once, into
-  `.claude/skills/`, and it prints the same command for any other runtime you
-  use;
+- 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`
+  ([Installing skills](/docs/ai/skills-reference#installing-skills) has the
+  steps, and the versions the package is published at);
 - 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*.
@@ -421,11 +425,12 @@ Three habits keep this reliable as the app grows:
 - **The gate applies to every domain.** Flows, dashboards, permissions, and
   translations all go through the same `npm run validate` — the agent should run
   it after each change, exactly as `AGENTS.md` instructs.
-- **Keep the skills current.** After upgrading `@objectstack/spec`, re-run
-  `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`
-  — name your own runtime after `--agent` — so the agent authors against the
-  schemas you actually run. The full catalog, and the multi-runtime `--all`
-  trade-off, are documented in the
+- **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.
+  The install steps, and the versions the package is published at, are in the
   [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
 
 ## 7. Your app is natively AI-operable (MCP)
 
@@ -43,11 +43,15 @@ 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** — it runs
-   `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`,
-   so the bundle lands **once**, in `.claude/skills/`, and a coding agent is
-   productive in the project from the first prompt. The closing summary prints
-   the same command with a different agent name for any other runtime you use.
+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`
+   ([Installing skills](/docs/ai/skills-reference#installing-skills) has the
+   steps, and the versions the package is published at).
 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.
@@ -349,11 +353,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).
-If you upgrade `@objectstack/spec` later, re-run
-`npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`
-— the same command the scaffolder ran, so it refreshes the one directory it
-installed — 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 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.
 
 ## Next steps