From f88e80d98181624e747b1ec9b0023813659c2223 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 01:40:33 +0000 Subject: [PATCH] docs(skills): the upgrade skill's preflight re-installs the catalog from @objectstack/skills on a 17.x to 18 move; both READMEs give the scaffolder's pinned --copy sync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `objectstack-upgrade` §0 Preflight gains one step for the skills themselves: remove the eleven `objectstack-*` skills `skills add` installed (their `skills-lock.json` entries read `sourceType: github`, so `experimental_sync` skips them and exits 0), install `@objectstack/skills` at the installed spec's version, and copy it with `npx skills@1.7.2 experimental_sync --agent claude-code --copy -y` — the command `create-objectstack` runs (`packages/create-objectstack/src/skills-install.ts`). The step is paid under the token ratchet by deleting text the same file restates elsewhere; the ceiling is unchanged (6180 → 6172 tokens of 6188). `skills/README.md` and `packages/skills/README.md` replace the unpinned linked sync with that pinned `--copy` spelling and say why `--copy`. The generated index block of `skills/README.md` is untouched. Changeset: `@objectstack/skills` patch. Claude-Session: https://claude.ai/code/session_013zGKMG1cRedVzWtqGGGZW9 Co-authored-by: Claude --- .changeset/23276-upgrade-skill-skills-step.md | 11 +++++ packages/skills/README.md | 16 ++++--- skills/README.md | 16 ++++--- skills/objectstack-upgrade/SKILL.md | 43 +++++++++---------- 4 files changed, 50 insertions(+), 36 deletions(-) create mode 100644 .changeset/23276-upgrade-skill-skills-step.md diff --git a/.changeset/23276-upgrade-skill-skills-step.md b/.changeset/23276-upgrade-skill-skills-step.md new file mode 100644 index 00000000000..9dfb1373e9f --- /dev/null +++ b/.changeset/23276-upgrade-skill-skills-step.md @@ -0,0 +1,11 @@ +--- +"@objectstack/skills": patch +--- + +docs(skills): the upgrade skill's preflight re-installs the catalog from `@objectstack/skills` when a 17.x project moves to 18, and both READMEs give the scaffolder's pinned `--copy` sync (#23276) + +Clause-②: no + +`objectstack-upgrade`'s §0 Preflight gains one step for the skills themselves. A 17.x project's skills were installed with `skills add` from the repository's `main`; their `skills-lock.json` entries read `sourceType: github`, and `experimental_sync` skips them (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. The step removes the eleven `objectstack-*` skills the catalog carried during 17.x (a name not installed is skipped; `--all` when they are the project's only skills), installs `@objectstack/skills` at the installed `@objectstack/spec`'s version, and copies it with `npx skills@1.7.2 experimental_sync --agent claude-code --copy -y` — the command `create-objectstack` runs. The step is paid under the token ratchet by deleting text the same file restates elsewhere; the ceiling is unchanged. + +`README.md` (the npm page) and `dist/skills/README.md` (the catalog's front page, copied from the repository's `skills/README.md`) replace the unpinned linked sync (`npx skills experimental_sync --agent claude-code -y`) with that pinned `--copy` spelling and say why: without `--copy` the sync writes links into `node_modules`, which a clone of a project that commits its skills does not have. diff --git a/packages/skills/README.md b/packages/skills/README.md index 8c98f384b9d..9ec39c4c6dc 100644 --- a/packages/skills/README.md +++ b/packages/skills/README.md @@ -27,16 +27,18 @@ agent's own skills directory (`.claude/skills/` for Claude Code, and so on): # 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 ``` `experimental_sync` discovers the skills at `dist/skills//SKILL.md` of -every dependency and links each one into the named agent's skills directory -(`--agent ` names the runtime — `codex`, `cursor`, …; `--copy` writes real -files instead of links). Keep the version in step 1: a bare -`npm install --save-dev @objectstack/skills` installs whichever version the -registry tags `latest`, not your spec's. +every dependency and copies each one into the named agent's skills directory +as real files, recording the source in `skills-lock.json` (`--agent ` +names the runtime — `codex`, `cursor`, …). Keep `--copy`: without it the sync +writes links into `node_modules`, which a clone of the project does not have; +the CLI is pinned to the version `create-objectstack` runs. Keep the version +in step 1: a bare `npm install --save-dev @objectstack/skills` installs +whichever version the registry tags `latest`, not your spec's. **Updating.** The catalog moves only with your ObjectStack version: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the diff --git a/skills/README.md b/skills/README.md index fca5f43e0d0..c092455658c 100644 --- a/skills/README.md +++ b/skills/README.md @@ -5,18 +5,20 @@ working in **any ObjectStack app** — this monorepo *and* third-party projects. They 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: +copy it from `node_modules` into your agent's directory: ```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`, …). To update, 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); -`--copy`, projects scaffolded by `npm create objectstack` and the rest are in the -[Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills). +Keep `--copy`: the skills land as real files in `.claude/skills/`, to commit with +the project; without it they are links into `node_modules`, which a clone does +not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). To update, +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); scaffolded projects, the move from a `skills add` install and the rest +are in the [Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills). **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 diff --git a/skills/objectstack-upgrade/SKILL.md b/skills/objectstack-upgrade/SKILL.md index 8cc5d581588..1d282c4e041 100644 --- a/skills/objectstack-upgrade/SKILL.md +++ b/skills/objectstack-upgrade/SKILL.md @@ -75,8 +75,6 @@ os migrate meta --from 17 --json # `applied` must be [] (see §3.3) # → write .upgrade/REPORT.md (template in §3.4) ``` -Everything below is the long form of those four steps. - --- ## 0 · Preflight @@ -102,8 +100,7 @@ one installed. Three sources, in order of authority: Arriving several majors late is the designed-for case: `os migrate meta --from 16` replays every step in order, with no requirement to upgrade one major at a time — -down to the chain's support floor, 16 today. Below the floor, upgrade to it by -the older route first, then run the chain. +down to the chain's support floor, 16 today. ### Make the work reviewable before you change anything @@ -117,6 +114,22 @@ The `.upgrade/` directory is the deliverable's workspace: the machine outputs and the human output (`REPORT.md`). Keeping them in the repo for the review, and deleting them on merge, is the usual arrangement — decide it with the owner. +### Re-install the skills from the moved catalog + +A 17.x project's skills came from `skills add`; their `skills-lock.json` entries +read `sourceType: github`, so the sync skips them (exit 0) and the agent keeps +reading 17.x skill text. Remove them (a missing name is skipped; `--all` when +they are the project's only skills), add `@objectstack/skills` at the installed +spec's version, 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 +``` + --- ## 1 · Mechanical layer — invoke the chain @@ -157,9 +170,6 @@ other with the reason it was not written, never writes a semantic change, and if re-running the chain over the written files disagrees, restores every file and exits 1. -Porting the edits left unwritten is yours, one `conversionId` at a time; use -`--out` as the oracle you diff against, never as the file you ship. - ### Stored rows: rehydration replays the same conversions A deployment's `sys_metadata` rows are the other subject. They are handled for @@ -318,16 +328,9 @@ os migrate meta --from 16 --json | node -e " grep -rn "" src/ app/ --include='*.ts' --include='*.tsx' ``` -Two traps that have cost real upgrades a lap: - -- **A renamed context field keeps compiling.** When a read moves from one key to - another and the old key is simply absent afterwards, the code reads - `undefined` and every branch quietly takes its false path. Verify against a - real dispatch, not a fixture — invoke the path and assert the value observed - under the canonical key. -- **A rename is not always the fix.** If the old read was itself wrong, renaming - it migrates the defect rather than the code. Read the semantic entry's - `reason` before applying its `replacement`. +One trap that has cost real upgrades a lap: **a rename is not always the fix.** +If the old read was itself wrong, renaming it migrates the defect rather than +the code. Read the semantic entry's `reason` before applying its `replacement`. ### 2.6 Working an R3 — the prose sweep @@ -383,9 +386,7 @@ the author-time rule set. Read the two separately — a rule finding about a missing sharing model or an options-less choice field is a **pre-existing** project-quality issue, not upgrade residue. Establish which is which by running `os validate` **once before you start**, on the un-upgraded source, and keeping -that output as the control. Fixing the project's standing lint debt may be a -welcome side-effect, but it is not this upgrade, and it must not be reported as -part of it. +that output as the control. > ### ⚠ A green `validate` does NOT mean the chain has nothing left to do > @@ -408,8 +409,6 @@ part of it. > build carries a step for, which is one PAST the installed major for most of a > release line, so `todos` carries the next major's semantic residue — real, but > not this upgrade's business. -> -> Run both. A report that cites only `validate` cannot see this class at all. → Moved verbatim to [references/examples-upgrade.md](./references/examples-upgrade.md) § 3.4 The report — the human half.