docs(getting-started,ai): state the skills install command the scaffolder actually runs (#17868)

Clause-②: no

Closes #16400

## What was false

Four `content/docs/**` pages recommended installing the AI skills bundle
with
`npx skills add objectstack-ai/objectstack/skills --all`, and **two of
them
stated that flag as what the scaffolder runs**. That second half was
already
false in the tree, not about to become false: the scaffolder moved to a
single
named agent when PR #16401 landed (2026-09-06T20:36:10Z), so the two
getting-started lines described a command `create-objectstack` no longer
issues.

## What it actually runs today — re-measured, not cited

Read from `packages/create-objectstack/src/skills-install.ts` on this
branch's
base (`c88fa2ccdc`), by evaluating the constants rather than eyeballing
the
template literal:

```
SKILLS_INSTALL_COMMAND     npx -y skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
skillsInstallHint(default) npx    skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
skillsInstallHint('codex') npx    skills add objectstack-ai/objectstack/skills --skill '*' --agent codex -y
DEFAULT_SKILLS_DIR         .claude/skills/
```

`index.ts:542` passes `SKILLS_INSTALL_COMMAND` to `execSync`, and lines
594-601
print `skillsInstallHint(...)` in the closing summary — so "one agent,
one
directory, and the command is printed for any other runtime" is the
behaviour,
not just the constant.

A check in the PR: all **7** command literals left in the four pages are
compared programmatically against the value that module composes. 0
mismatches.

## Carriers — 4 of the card's 5 surfaces are this PR's

The card named five surfaces. Triage split on the landing path, not on
the
sentence kind: 「拆后本卡的文件面只剩 `content/docs/**`,按车道表归 `domain:devx`」.

| surface | kind | state |
|:---|:---|:---|
| `getting-started/your-first-project.mdx` 45, 286 | states what the
scaffolder runs + re-run instruction | fixed here |
| `getting-started/build-with-claude-code.mdx` 57, 381 | same pair |
fixed here |
| `ai/skills-reference.mdx` 27, 30, **33** | manual recommendation + two
prose claims | fixed here |
| `ai/skills.mdx` 35, **38** | manual recommendation + prose claim |
fixed here |
| `skills/README.md` 9 | governed surface | not ours — already moved to
the per-agent form by PR #16806, verified absent from this base |

The two bolded sites were not on the card's or the skills seat's line
list;
`skills-reference.mdx:33` and `skills.mdx:38` attribute the
bundle-versioning
and idempotence properties to `--all` specifically, so leaving them
would have
kept the flag as the recommended form in prose after the commands
changed.

## Fix shape, and why not a pointer

The brief asked whether to keep a corrected literal or point at the
single
source of truth (`skills-install.ts`), as this shift's #16200 did. Split
by
reader:

- **Where the reader must type the command** (all four pages' install
and
re-run instructions) the literal stays, corrected. A docs reader cannot
resolve a pointer into a TypeScript module in our monorepo — that page
is not
on the docs site and they cannot run it. Pointing there would remove the
fact
  instead of keeping it true, which is the vague-sentence failure in a
  different costume.
- **Where the reader does not need the value**, the pointer shape is
used:
`skills-reference.mdx`'s "new projects" paragraph now states the
observable
properties (one runtime, `.claude/skills/`, once) and points at the live
instrument the reader actually holds — *the scaffolder's own closing
summary
prints the exact command it ran*. That paragraph previously named no
command,
so this keeps the number of decaying copies at what it was rather than
adding
  an eighth.

`--all` is not deleted: it is a real CLI option, and triage's
instruction was
that the idempotence claim is true and must not be removed. It survives
on the
reference page as a labelled multi-runtime opt-in that names its cost
(three
destinations: real copies in both `.agents/` and `agent/`, plus
`.claude/`
symlinks), with the distinction that makes the idempotence claim useful
—
re-running is idempotent *per destination*, and it is the destination
count that
grows.

## Reverse-read

*Does anywhere else state the scaffolder's behaviour, and does this diff
make
any standing sentence false?*

- `content/docs/deployment/cli.mdx` 29, 93, 94 — "installs the AI skills
bundle
  + `AGENTS.md`". True, names no command, no decay. **Unchanged.**
- `content/docs/getting-started/how-ai-development-works.mdx:45`,
  `getting-started/index.mdx` 26, 161 — same shape. **Unchanged.**
- `getting-started/build-with-claude-code.mdx:70` — a console transcript
quoting `→ Installing AI skills for your coding agent...`, byte-equal to
`index.ts`'s `printStep`. True. `pnpm check:docs-transcript-drift`
measured it
  green on the final text. **Unchanged.**
- `getting-started/build-with-claude-code.mdx:26` (mermaid) and
`your-first-project.mdx:272` — "installs the skills bundle", no command.
  **Unchanged.**
- `packages/create-objectstack/README.md:60`,
`src/templates/AGENTS.md:82`,
`src/templates/blank/README.md:148`, `skills/README.md:9` — all four
already
carry the per-agent form. This diff agrees with them; none becomes
false.
- `packages/create-objectstack/src/template-consistency.test.ts:597-602`
— "the
boundary is the `/skills` SUBPATH, and it did not move when the
scaffolder
stopped passing `--all`". Directional and historical, still true, and
this
  diff keeps the subpath on every literal.
- **Zero** results for: any other `content/docs` page naming a `skills
add`
command; any test or gate pinning `--all` in the docs (none exists — see
the
acceptance note below); any generated block containing an install
command
(`build-skill-docs.ts` emits none; `skills-reference.mdx`'s generated
region
  starts at line 38, below every site edited).

One sentence outside this card's file surface **is** made false by this
diff,
reported rather than fixed: `.github/workflows/scaffold-e2e.yml:229-231`
says in
a comment "The scaffolder/docs command is `skills add
…/objectstack/skills
--all`". The scaffolder half was already stale; the docs half becomes
stale
here. The probe below it deliberately uses `--all --copy` and is correct
for its
purpose (set-equality against the curated catalog), so only the comment
is
wrong. Left alone because triage split this card's file surface to
`content/docs/**` and editing a workflow would add a verification
surface this
PR does not otherwise touch.

## 验收备注

- **No gate pins the docs against the scaffolder's command.** Triage
flagged
building one as a bonus and explicitly told the claiming seat not to
expand
the PR into `scripts/` for it — so the programmatic literal comparison
above
was run as a one-off in this PR and is not committed. Noted, not filed:
the
next surface to state this command has nothing mechanical to catch it,
and the
  docs-drift audit states it structurally cannot see this class.
- `docs/qa/platform-checklist/areas/cli.json:384` uses `--all --copy` as
a
skills-boundary probe. Not a statement of scaffolder behaviour;
unaffected.
- `.claude/skills/dogfood-verification/SKILL.md:13` notes that the CLI's
`--all` implies `--skill '*'`. True CLI semantics, governed surface,
untouched.

## Verification

Derived with `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack`
(change set taken by the script from the merge base, not from a
hand-written
diff): **43 families, 43 run, 0 NOT-MEASURED, 0 UNRUN, all exit 0** —
reconciled back through `--ran` with an exit code recorded per family,
so the
zero is derived rather than claimed. Four of them first refused with
`PREREQUISITE NOT MET` (exit 3, not a finding); `@objectstack/lint`,
`@objectstack/formula` and `@objectstack/client-react` were built and
all four
then exited 0.

Named readings, all on the final text:

```
pnpm --filter @objectstack/spec check:docs        ✅ 222 generated files in sync with packages/spec
pnpm check:docs-transcript-drift                  ✓ 4 declared transcript value(s) across 402 page(s)
                                                    under content/docs/ equal what the registry derives today
pnpm check:doc-authoring                          ✓ 44 published skill files clean
pnpm check:corpus-claim-drift                     OK, no new claim sites beside a pinned spelling
pnpm check:role-word                              OK, no new occurrences of the reserved word
pnpm check:nul-bytes                              exit 0
```

Heavy steps ran through `scripts/pm/os-verify-lock.sh` (slot
`issue-16400`):
`pnpm install` `VERDICT command-exit 0`, `@objectstack/spec build`
`VERDICT command-exit 0`, the three-package turbo build
`VERDICT command-exit 0`.

**`pnpm lint` — a declared narrowing, measured in three parts.** The
repo-scoped
run is CI's; the reading here is that this diff is outside eslint's
population
entirely. (1) Population from eslint's own config, not a guess:
`new ESLint().isPathIgnored(...)` returns `true` for the changed `.mdx`
files.
(2) File count from `--format json` over exactly the four changed files:
4 files
read, 0 errors, and each of the 4 warnings is `File ignored because no
matching
configuration was supplied`. (3) Invariance: this repo runs one
`eslint.config.mjs` which never enables type-aware linting for any file
(`eslint.config.mjs:325-332`; no `parserOptions.project`), so nothing in
this
diff can move the verdict on a file it does not touch. Union run against
final
`HEAD` `0612e8bfe8`.

**Changeset: skipped, measured.** No package's `files[]` names
`content/docs` —
checked across every `packages/*/package.json` carrying a `files` array,
zero
hits. The only consumer of this tree is `apps/docs`
(`@objectstack/docs`,
`private: true`, no `files`). Positive control: the corrected command
string
does appear in published surfaces
(`packages/create-objectstack/README.md`,
`src/templates/AGENTS.md`, `src/templates/blank/README.md`) — none of
which this
diff touches. Nothing shipped moves, so the `skip-changeset` label is
applied
rather than a body sentence.

**`Clause-②: no`** — the diff is four `.mdx` prose files: no schema key,
no
closed-set member, no published export, no registry entry.
`pnpm check:pm-widening-tells` exit 0.

---
_Generated by [Claude
Code](https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

content/docs/ai/skills-reference.mdx

@@ -15,7 +15,7 @@ ObjectStack ships a set of **domain-specific skills** that teach AI assistants (
 
 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:
+**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.
 
 ```bash
 npm create objectstack@latest my-app
@@ -24,13 +24,15 @@ npm create objectstack@latest my-app
 **Existing projects — install the whole bundle:**
 
 ```bash
-npx skills add objectstack-ai/objectstack/skills --all
+npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
 ```
 
-Run the same command again at any time to pull the latest versions — `--all` is idempotent, 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` without `--all`. (The `/skills` subpath scopes discovery to the published catalog — always keep it in the command.)
+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.
 
 <Callout type="info">
-Skills are versioned as **one bundle**. You do not track or update each skill individually — `--all` always installs the matching set for the `@objectstack/spec` version in your project.
+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>
 
 ---

content/docs/ai/skills.mdx

@@ -28,14 +28,14 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for
 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.
 
 ```bash
-# New project — create-objectstack installs skills automatically
+# New project — create-objectstack installs them automatically, for one agent
 npm create objectstack@latest my-app
 
-# Existing project — add the whole bundle (re-run to update)
-npx skills add objectstack-ai/objectstack/skills --all
+# 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
 ```
 
-The bundle is versioned and updated as **one unit** — `--all` is idempotent, so you never track skills individually. For the full per-skill catalog and install options, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
+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).
 
 ---
 

content/docs/getting-started/build-with-claude-code.mdx

@@ -54,8 +54,10 @@ 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 --all` to install the **AI skills
-  bundle**;
+- 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;
 - 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*.
@@ -378,9 +380,11 @@ Three habits keep this reliable as the app grows:
   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 --all` so the agent authors
-  against the schemas you actually run. The full catalog is documented in the
-  [AI Skills Reference](/docs/ai/skills-reference).
+  `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
+  [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
 
 ## 7. Your app is natively AI-operable (MCP)
 

content/docs/getting-started/your-first-project.mdx

@@ -42,8 +42,11 @@ 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** (`npx skills add objectstack-ai/objectstack/skills --all`)
-   so a coding agent is productive in the project from the first prompt.
+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.
 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.
@@ -283,8 +286,10 @@ automation) — the agent loads the matching skill per task. The full loop, and
 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 --all` to keep the agent in
-sync with the schemas you 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.
 
 ## Next steps