Repository navigation
docs(skills install): the end state after create-objectstack installs @objectstack/skills — one pinned spelling with --copy, one next.0 exception, and the 17→18 skills step in the upgrade guide (ruling A on #22649, second docs pass) #23275
Description
Blocked-by: #22659
Unlock-action: re-check PR #23248
Filing gate ③ a task the maintainer directed. The maintainer, in the skills seat's session chat on 2026-10-13: 「评估升级到 v18 之后 ,skills 官方应该从 npm 安装,模版项目的 skills 安装流程,文档相关的说明应该如何修正」, and on the seat's evaluation: 「评估里两张卡同意立」. Filed by domain:skills seat 1 (seat post #7623, session_013zGKMG1cRedVzWtqGGGZW9, huangyiirene). Ruling-ref: 6096124407 (ruling A on #22649, the direction this card completes; the first docs pass was #22668). Triage may re-grade on first touch. ⛔ Not a claim.
Reader who acts: the domain:devx seat, once PR #23248 (#22659 — create-objectstack installs the catalog from @objectstack/skills) is on main; the docs must not describe that scaffolder before it ships. Surface: content/docs/getting-started/build-with-claude-code.mdx (lines 60–67 and 425–434), content/docs/getting-started/your-first-project.mdx (47–54 and 357–359), content/docs/ai/skills-reference.mdx (17–41), content/docs/ai/skills.mdx (29–36), content/docs/upgrading.mdx, content/docs/releases/v18/index.mdx. ⛔ No skills/** and no packages/** — the two package READMEs and the upgrade skill are the skills lane's sibling card, filed in the same act.
Why (measured on origin/main afbf960c, 2026-10-13)
- Three transitional passages —
build-with-claude-code.mdx:60-67,your-first-project.mdx:47-54,skills-reference.mdx:39— say that through18.0.0-next.0the scaffolder takes the skills from the repository's unreleasedmainand tell the reader to replace them with the package. PR feat(create-objectstack): a scaffolded project installs its skills from @objectstack/skills at its spec version, never from GitHub main (#22659) #23248 makes the scaffolder install the package itself (templatedevDependenciesgain@objectstack/skillsat the spec's version; it runsnpx -y skills@1.7.2 experimental_sync --agent claude-code --copy -y), so from the next prerelease these passages describe a scaffolder that no longer exists. - The pages teach the linked sync (
npx skills experimental_sync --agent claude-code -y, no--copy). PR feat(create-objectstack): a scaffolded project installs its skills from @objectstack/skills at its spec version, never from GitHub main (#22659) #23248 measured that shape in a committed project: the links point into the gitignorednode_modules, so a clone gets dangling links and zeroSKILL.md. The scaffolder uses--copy, and theAGENTS.mdit writes says to keep it. Two spellings of one command, and the documented one breaks on clone. - The pages run an unpinned
npx skills; the scaffolder pinsskills@1.7.2becauseexperimental_syncis that tool's unstable interface. A third spelling. content/docs/upgrading.mdxandcontent/docs/releases/v18/index.mdxsay nothing about the skills (grep -n -iE 'skill' content/docs/upgrading.mdx→ 0 lines; the positive controlgrep -c 'os migrate meta' content/docs/upgrading.mdx→ 6). A 17.x project's skills were installed byskills addfrom GitHubmain; itsskills-lock.jsonrecordssourceType: github, andexperimental_syncskips those (Skipped … installed with skills add, exit 0 — PR feat(create-objectstack): a scaffolded project installs its skills from @objectstack/skills at its spec version, never from GitHub main (#22659) #23248's measurement). An upgrader who bumps only the packages keeps the 17.x-era skill text.
What done looks like
- The three transitional passages are rewritten to the end state: the scaffolder installs the catalog from
@objectstack/skillsat the project's@objectstack/specversion, copied into.claude/skills/. The18.0.0-next.0exception (that one scaffolder still readmain; remove its skills withnpx skills remove, then run the two steps) lives in exactly one sentence, inskills-reference.mdx's "Which versions exist"; the other two pages link there. ⛔ No staged wording and no second transitional paragraph. - One install spelling across the pages, equal to the scaffolder's: the
npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"step, thennpx skills@1.7.2 experimental_sync --agent claude-code --copy -y. The linked (no--copy) form is dropped, or kept as one sentence for a project that does not commit its skills. The pinned CLI version is read frompackages/create-objectstack/src/skills-install.tson the tree at dispatch, never recalled. content/docs/upgrading.mdx(the cross-major checklist) andcontent/docs/releases/v18/index.mdxgain one skills step for 17.x → 18:npx skills remove objectstack-ai objectstack-api objectstack-automation objectstack-data objectstack-formula objectstack-i18n objectstack-platform objectstack-query objectstack-ui objectstack-upgrade(ornpx skills remove --allwhen only this catalog was installed), then the two install steps above, and the rule that the catalog moves only with the@objectstack/*packages.check:doc-route-spelling,check:corpus-claim-drift,check:doc-authoringand the docs link check green;skip-changeset(docs only —content/docs/**ships in no package).- ⛔ No new gate: the spelling is held by prose review (
contract-review.mdroutescontent/docs/**to the dispatching seat's ACCEPT, sentence by sentence against the diff).
Workload: S; precedent PR #23220 (the first docs pass over the same pages).
四维(业务立场)
- 长远合理性:技能随版本装是 contract-first 的自然延伸;文档只写终态、一处例外,两年后读者看到的是「装哪版用哪版」一句话。
- 实际业务拉动:
next.1起npm create objectstack@next产出的 AGENTS.md 与官网文档互相矛盾;17.x 升 18 的用户技能被experimental_sync静默跳过(PR feat(create-objectstack): a scaffolded project installs its skills from @objectstack/skills at its spec version, never from GitHub main (#22659) #23248 实测)。 - 防 AI 犯错:一种命令、一处例外、
--copy(无悬空链接)、先 remove 再 sync(无静默跳过)——把两种读法收成一种。 - 创业阶段不扩散:删过渡段、删链接式拼写;不加门禁、不加脚本。
Dedupe: REST listing labels=domain:devx&state=all&since=2026-09-20 (278 cards) and labels=domain:skills&state=all&since=2026-09-20 (252 cards), grepped for --copy|experimental_sync|skills install|upgrade skill|objectstack-upgrade|upgrading.mdx|install the catalog|skills add → 9 and 17 hits; #22668 (closed; PRs #23220 and #23232) is the first pass this card follows, #17870 (closed) corrected the scaffold-e2e comment; none is this second pass or the upgrade step. Dedupe words: skills docs second pass · experimental_sync --copy · skills@1.7.2 pin · upgrading.mdx skills step · next.0 exception.
Generated by Claude Code
Activity
objectstack-fleet commentedon Oct 13, 2026
Unlock scan:
pm:blocked→pm:queue·domain:devxseat 1 ·session_012zwsLMxQBwHUYJgPyrpEvx· 2026-10-13T13:59Z. ⛔ Not a claim.Blocked-by: #22659is satisfied, re-derived at this act:completedat 2026-10-13T12:47Z through PR feat(create-objectstack): a scaffolded project installs its skills from @objectstack/skills at its spec version, never from GitHub main (#22659) #23248, merged as5da2c0f837. In that PR,create-objectstackinstalls the catalog from@objectstack/skillsand no longer from GitHubmain.main") now holds.18.0.0-next.0the scaffolder takes those skills from thenextchannel …". That stays true for every scaffolder published up to and including18.0.0-next.0.skills-reference.mdx, the build-with-claude-code step-1 bullet, your-first-project step 3, and both READMEs.6146552291on [PM seat] domain:devx @ objectstack — ⏳ vacant #6023). The card is dispatched after the two in-flight cards (test budget (domain:devx): 2 test file(s) over 10 s of wall in the hourly full battery (Part of #23151) #23185, platform-checklist accuracy and fixture gaps from the #23104 browser pass, successor of #23121: the rows #23132 did not land (family card) #23169) reach their terminal states.objectstack-fleet commentedon Oct 13, 2026
Claim: PM loop round 13 (serial) ·
domain:devxseat 1 · 2026-10-13T14:21Z · maintainer-directed (the card's filing quotes the order in the skills seat's session); unblocked by this seat6147282033Session:
session_012zwsLMxQBwHUYJgPyrpEvxAccount:
zhuangjianguo(the seat's linked user asGET /useranswers it; the card's assignee)Branch:
claude/issue-23275-skills-install-end-stateWorktree:
objectstack-issue-23275Domain:
domain:devxSeat:
domain:devx#1File surface:
content/docs/getting-started/build-with-claude-code.mdx,content/docs/getting-started/your-first-project.mdx,content/docs/ai/skills-reference.mdx,content/docs/ai/skills.mdx,content/docs/upgrading.mdxandcontent/docs/releases/v18/index.mdx. ⛔ Noskills/**and ⛔ nopackages/**: the two package READMEs and the upgrade skill are the skills lane's sibling cardContainer & model:
M,mode:subagent,model: opus(dispatch-gates --tieron the surface: "no path-derived mandate")Clause-②: no (docs)
Responsibility: the docs still describe the pre-#23248 scaffolder (skills from GitHub through
18.0.0-next.0) and a linked sync, where the scaffolder now copies the catalog from@objectstack/skills| no platform path covers it: PR #23248 changed the scaffolder only | from the next publish,npm create objectstack@next's own AGENTS.md and the site contradict each other, and a 17.x → 18 upgrade's skills are silently skipped by the syncThread-read: 6147282033
Serial constraints cleared: no open PR touches any of the six pages (all open PRs' file lists read at this act). This is the seat's only dispatch in flight (serial order
6146552291).objectstack-fleet commentedon Oct 13, 2026
os-dev-report
{
"issue": 23275,
"status": "done",
"branch": "claude/issue-23275-skills-install-end-state",
"pr": "#23295",
"session": "session_012zwsLMxQBwHUYJgPyrpEvx",
"premise_still_valid": true,
"summary": "Rewrote the six pages to the end state after PR #23248. The scaffolder installs @objectstack/skills at the project's @objectstack/spec version and copies it into .claude/skills/. The three transitional 'Through 18.0.0-next.0' passages are gone; the one exception (create-objectstack@18.0.0-next.0 still read main) is one sentence in skills-reference 'Which versions exist', and the two getting-started pages link there. Every sync on the site (7 occurrences) is now the scaffolder's own npx skills@1.7.2 experimental_sync --agent claude-code --copy -y (SKILLS_CLI read from skills-install.ts at the head), and the linked form is no longer taught. upgrading.mdx 'Moving the dependency pins' goes from three steps to four, and step 4 carries the 17.x to 18 sequence; releases/v18/index.mdx gains the same step as one bullet, with a block byte-identical to it. Measured deviations from the card's literal: (1) the remove list adds objectstack-pm-dispatch, which was on main 2026-08-02..~09-11 and in the spec@17.0.0..17.4.0 tags. On a project installed from the 17.4.0 tree, the card's 10-name list printed 'removed 10' of 'Found 11' and left it in three dirs plus its lock entry; the 11-name list removed all 11, and an absent name is skipped (exit 0). (2) The named remove carries -y, like the scaffolder's own remedy line. (3) remove stays unpinned, as the card and the scaffolder spell it. PR is draft and assigned to zhuangjianguo; labels read back as documentation, size/m, skip-changeset. Worktree removed after push.",
"tests": "All at head 98ee767. Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 50 from the merge base (6 paths, 119 lines). Pass 1: 45 exited 0. Four exited 3 (PREREQUISITE NOT MET): check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift. spec check:docs exited 1 with 'Generate it first: gen:schema' (missing gitignored tree, not a finding). Then 'turbo run build' for spec, formula, lint, client and client-react with --concurrency=2, under os-verify-lock: 35 tasks, 'VERDICT command-exit 0'. All five re-ran to 0 ('263 prose examples type-check', '226 generated files in sync', '4 declared transcript value(s) ... equal'). --ran: '50 derived, 50 run, 0 NOT-MEASURED, 0 UNRUN' (a DERIVED zero). Card-named gates all 0: check:corpus-claim-drift, check:doc-authoring, check-doc-route-spelling --advisory and --self-test, and enforce mode ('population clean'); check:doc-anchors 0. Docs link check, the check-links.yml argv with lychee 0.24.2: exit 0, '2457 Total ... 0 Errors'. MDX compile with @mdx-js/mdx 3.1.1: 6/6 ok, negative control fails. eslint --format json over the six files: 6 results, 0 errors, all 'File ignored'; no type-aware linting, so no other file's verdict moves (the repo-wide run is CI's). Control-char grep: 0 hits. check:nul-bytes 0. Commands, measured in scratchpad projects (skills CLI 1.7.2, npm 10.9.4): (a) this tree's scaffolder, run for real via tsx with no flags: '+ @objectstack/skills 18.0.0-next.0', 'Synced 10 skills', 10 real SKILL.md and 0 symlinks, lock 10 x node_modules, summary prints the pinned --copy command; git add then clone gives 10 readable SKILL.md. Linked control: 20 symlinks staged, clone has 20 dangling links. (b) The reference's code block, run with bash -e on a fresh spec@next project: exit 0, 10 real skills. On a 17.7.0 project, step 1 exits 1 with ETARGET. (c) The upgrading.mdx block, run with bash -e after bumping spec to next. Shape A (17.5-17.7 'skills add --skill * --agent claude-code -y'): removed 10, Synced 10. Shape B (17.0-17.3 'skills add --all' over the 17.4.0 tree): removed 11, Synced 10. Both: 10 real SKILL.md, lock 10 x @objectstack/skills node_modules 18.0.0-next.0. Control: sync without removal printed 'Skipped ... installed with skills add' x10 and 'Nothing to sync.', exit 0. No ablation or reverse verification applies to a docs-only diff.",
"mcp_calls": "0",
"api_writes": "3 relay dispatches (POST /repos/objectstack-ai/objectstack/dispatches), executed as objectstack-fleet[bot]: pr_create (POST /repos/objectstack-ai/objectstack/pulls draft + POST /repos//issues/23295/assignees); labels_add via scripts/pm/label-write.mjs (POST /repos//issues/23295/labels); this os-dev-report comment via scripts/pm/post-stamped.mjs (POST /repos//issues/23275/comments). Plus 2 git pushes (the empty-branch probe and the commit), not REST.",
"deviations": [
"Commit trailer: the model-free pair AGENTS.md requires (Claude-Session + Co-authored-by: Claude), not the harness reminder's model-named Co-Authored-By line, which the pre-push hook would refuse.",
"Clause line: the PR body carries the claim's own line 'Clause-②: no (docs)'; the dispatch wrote 'Clause-②: no'. scripts/pm/clause2-line.mjs readClause2Line reads both as declared 'no', with no arm.",
"content/docs/releases/v18/index.mdx is release-owned. It is edited here because the card and the claim name it and this PR is docs-only (no code rider). The PR body says so."
],
"open_questions": [],
"out_of_scope_findings": [
"carrier: the skills-lane sibling card named in #23275's body (the package READMEs and the objectstack-upgrade skill) · if it copies the card's 10-name 'npx skills remove' list, it needs objectstack-pm-dispatch too. Measured: on a project installed from the spec@17.4.0 tree, the 10-name list leaves that skill in .claude/skills, .agents/skills and agent/skills plus its github lock entry · noted in PR Acceptance notes, not filed",
"carrier: 承接者:无 · the getting-started pages say 'npm create objectstack@latest', which resolves create-objectstack@17.7.0 today, and that scaffolder still runs 'skills add' from main. This was true before this PR, and the 17.x line is covered by 'Which versions exist' and the new upgrade step; it resolves at GA · noted in PR Acceptance notes, not filed"
]
}
Generated by Claude Code
objectstack-fleet commentedon Oct 13, 2026
Review: ACCEPT · PR #23295 (draft, head
98ee767b5a,Fixes #23275) ·domain:devxseat 1 ·session_012zwsLMxQBwHUYJgPyrpEvx· 2026-10-13T15:08ZI checked this on GitHub. I did not take the dev report's word for it.
content/docs/**goes to the dispatching seat's ACCEPT, percontract-review.md, so I read the diff sentence by sentence.content/docs/**pages, +83 / −36. These are the six the card names.skills/**, nopackages/**, no contract face.documentation,size/mandskip-changeset. The docs ship in no package.mainisskills-install.ts:102SKILLS_CLI = 'skills@1.7.2'.:119composes… experimental_sync --agent ${agent} --copy -y. Every sync line in the diff is exactly that. The linked form is no longer taught. It survives only as the reason for--copy, which is one of the card's allowed outcomes.create-objectstack@18.0.0-next.0sentence is in one place:skills-reference.mdx, under "Which versions exist".skills.mdx,build-with-claude-code.mdxandyour-first-project.mdxlink to it and do not restate it. The old "Through18.0.0-next.0…" paragraph and the two "replace it" passages are gone. No staged wording remains.upgrading.mdxstep 4, and the count is updated to "four steps".releases/v18/index.mdxhas the same block, byte-identical once de-indented.@objectstack/*packages.node_modules.releases/v18/is release-owned. The card names this page, and the PR body says so.objectstack-pm-dispatch. The dev measured that skill in the 17.0.0–17.4.0 trees and absent from 17.5.0 on. On a project installed from 17.4.0, the card's 10-name list left it installed. The 11-name list removed all of them. On a 10-skill project, the absent name was skipped with exit 0. So one list covers both shapes.-yon the named remove. It matchesskills remove --helpand the scaffolder's own remedy line.removeis left unpinned. Onlyexperimental_syncis the unstable interface, as the card spelled it.check:corpus-claim-drift,check:doc-authoringandcheck-doc-route-spellingin enforce mode.check:doc-anchorsexits 0, so the new#moving-the-dependency-pinslinks resolve.98ee767b5a: 32 green, 10 skipped, 1 running (Test Core 1/6), none red. I am marking the PR ready and arming auto-merge.objectstack-upgrade) needsobjectstack-pm-dispatchin any remove list it copies. I am passing that to the sibling card next, not here.objectstack-fleet commentedon Oct 13, 2026
Landed: PR #23295 →
175e8d4149(Fixes #23275) ·domain:devxseat 1 ·session_012zwsLMxQBwHUYJgPyrpEvx· 2026-10-13T15:36Zmain, all 6 files equal the PR head98ee767b5a:skills-reference.mdx,skills.mdx,build-with-claude-code.mdx,your-first-project.mdx,upgrading.mdxandreleases/v18/index.mdx.completed), andpm:dispatchedis removed.6148721272): its remove list needsobjectstack-pm-dispatchtoo, making 11 names..d.tsdeclarationexport function mkdtempSync(prefix: string)as a call site, so the full battery reds on main since PR #23273 #23294, themain-red fix. It is already in flight (6148770120), with this card's dev returned and its PR armed.