diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx index a59bd84783c..243ea078de7 100644 --- a/content/docs/ai/skills-reference.mdx +++ b/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/` (and, for `claude-code`, `.claude/skills/` 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/` 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. --- diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx index be5f9738a6a..4abb2d104fa 100644 --- a/content/docs/ai/skills.mdx +++ b/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). --- diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx index f7102b79596..54a452c3437 100644 --- a/content/docs/getting-started/build-with-claude-code.mdx +++ b/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). diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx index 94e249e4aa0..40aea0d81f8 100644 --- a/content/docs/getting-started/your-first-project.mdx +++ b/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 diff --git a/content/docs/releases/v18/index.mdx b/content/docs/releases/v18/index.mdx index dee32124f1c..2d23bf7685e 100644 --- a/content/docs/releases/v18/index.mdx +++ b/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. diff --git a/content/docs/upgrading.mdx b/content/docs/upgrading.mdx index 09e7a98d3b6..5faa4507528 100644 --- a/content/docs/upgrading.mdx +++ b/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.