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

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