docs: five surfaces tell readers to install the skills bundle with `--all`, which writes it to three directories — and two of them describe a scaffolder command that is changing

[claude]

domain:* / type / priority are triage's.

Found while implementing #16331, which changes what create-objectstack runs. Filed rather than fixed there: the file surface for that card is packages/create-objectstack/, and content/docs/** plus skills/** pull in a different gate family (check:doc-authoring, the docs-drift audit, link checking) — and skills/** is a governed surface, human-merge only.

Two problems, one fix

1. Two getting-started pages state what the scaffolder does, and will be wrong once #16331 lands

• content/docs/getting-started/your-first-project.mdx:45 — "Installs the AI skills bundle (npx skills add objectstack-ai/objectstack/skills --all)"
• content/docs/getting-started/build-with-claude-code.mdx:57 — "runs npx skills add objectstack-ai/objectstack/skills --all to install the AI skills bundle"

After #16331 the scaffolder runs npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y. Both lines then describe a command the tool no longer issues.

2. Four surfaces recommend --all to a human, and --all writes the bundle three times

• content/docs/getting-started/your-first-project.mdx:283 (the "re-run to keep in sync" instruction)
• content/docs/getting-started/build-with-claude-code.mdx:381 (same instruction)
• content/docs/ai/skills-reference.mdx:27 and its following paragraph, which says --all is idempotent and recommends keeping it
• content/docs/ai/skills.mdx:35 — "Existing project — add the whole bundle (re-run to update)"
• skills/README.md:9 — the catalog's own front door

Measured against skills@1.5.23 and this catalog (11 skills), in an empty directory:

npx skills add objectstack-ai/objectstack/skills --all
  .agents/   46 real files   604,102 B
  agent/     46 real files   602,682 B   (same bodies, re-serialised frontmatter)
  .claude/   11 symlinks into .agents/

npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
  .claude/   46 real files   604,102 B   and nothing else

A reader who follows the --all instruction inside a git repository and commits gets 22 SKILL.md paths plus 11 symlinks staged instead of 11 — the exact defect #16331 was filed about, reproduced by following the documentation. That is what makes this more than a wording drift: the docs are a second, independent source of the triplication, and closing #16331 in the scaffolder does not close it here.

The --all idempotence claim in skills-reference.mdx is true and beside the point: re-running is idempotent per destination, and it is the destination COUNT that is the problem.

Suggested shape

One docs-only PR that (a) restates what the scaffolder now runs on the two getting-started pages, and (b) makes the per-agent form the recommended one everywhere, with --all described as the multi-runtime opt-in and a one-line note that it writes three copies. skills/README.md needs the governed-surface path.

Not in this card

packages/create-objectstack/** — that is #16331, in flight. The published skills catalog's CONTENT; only the install instruction is in question here.

---

Generated by Claude Code

[os-sam]

Timing note for triage: two of the five surfaces on this card go factually wrong the moment #16401 merges, not gradually.

content/docs/getting-started/your-first-project.mdx:45,283 and build-with-claude-code.mdx:57,381 do not merely teach --all — they state what the scaffolder runs. #16401 (issue #16331) changes that command to --skill '*' --agent claude-code -y, so on merge those four lines describe behaviour the scaffolder no longer has.

The other three (content/docs/ai/skills-reference.mdx:27, content/docs/ai/skills.mdx:35, skills/README.md:9) teach --all as a manual command a reader may still run. Route B does not remove that ability, so they are not false — they are the reproduce-the-triplication hazard this card describes, which is a different and less urgent defect.

Worth splitting on that line if the card is dispatched as one: the four-line half is a merge-window correction, the rest is a considered rewrite.

One routing fact for whoever takes it: skills/README.md is a governed surface, so including it moves the PR onto the terminal four-step (maintainer approval) while content/docs/** alone does not.

Context, since it is not obvious from the card: this was found twice independently — by the dev building #16401 and by the PM seat reviewing it — because the docs-drift bot states it structurally cannot see this class ("a page that states a rule by its inputs shares no identifier with the emitter that implements the rule"). It was hand-grepped both times.

This card is domain:devx by the lane table; the domain:cli session that surfaced it is not routing or claiming it.

---

Generated by Claude Code