From 0612e8bfe89e78e204fe8a117c6313a7b5090651 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 15:43:06 +0000 Subject: [PATCH] docs(getting-started,ai): state the skills install command the scaffolder actually runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two getting-started pages stated that `create-objectstack` installs the AI skills bundle with `npx skills add objectstack-ai/objectstack/skills --all`. That stopped being true when the scaffolder moved to a single named agent: `skills-install.ts` now composes npx -y skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y so both lines described a command the tool no longer issues. They are not teaching a usage — they state what the tool runs — so they are corrected to state the true command, not softened into something vaguer. The same flag was the recommended manual form on two more pages. `--all` is still a real option, so it stays on the reference page as a labelled multi-runtime opt-in that names its cost: it writes the bundle to three destinations instead of one. The idempotence claim is kept, with the distinction that makes it useful — re-running is idempotent per destination, and it is the destination count that grows. Every command literal keeps the `/skills` subpath, which is the published catalog boundary, and all seven now equal what `skills-install.ts` composes. Claude-Session: https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU Co-authored-by: Claude --- content/docs/ai/skills-reference.mdx | 10 ++++++---- content/docs/ai/skills.mdx | 8 ++++---- .../getting-started/build-with-claude-code.mdx | 14 +++++++++----- .../docs/getting-started/your-first-project.mdx | 13 +++++++++---- 4 files changed, 28 insertions(+), 17 deletions(-) diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx index 0db0840a8b..735761daa1 100644 --- a/content/docs/ai/skills-reference.mdx +++ b/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. -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. --- diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx index b9457e33a4..efd68976b0 100644 --- a/content/docs/ai/skills.mdx +++ b/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). --- diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx index 9c05c75122..c3b0855efd 100644 --- a/content/docs/getting-started/build-with-claude-code.mdx +++ b/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) diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx index 242f222b31..2a63698a2e 100644 --- a/content/docs/getting-started/your-first-project.mdx +++ b/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