docs: correct skills CLI install path to the curated /skills subpath (#51)

os-zhuang · claude · web-flow · commit 70e111fefca5 · 2026-07-21T08:57:16.000+08:00
The quickstart, IDE-skills, agents, and skills-cli pages (all locales) advertised `npx skills add objectstack-ai/framework`, which points the skills CLI at the repo root — its catalog walk then also discovers repo-internal skills outside the curated `skills/` directory (framework#3101 established /skills as the hard publish boundary). Also in the skills-cli reference: - replace the `<org>/<repo>@<ref>` pin syntax and the `@v5.0.0` example — the skills CLI has no @<git-ref> source form and the framework repo has no v5.0.0 tag; use the documented https://github.com/<org>/<repo>/tree/<ref>/<path> URL form instead - drop the 'pulls latest matching the spec version range' comment (the CLI does no spec-version matching) - update the Claude Code row: current CLI writes universal .agents/skills/<name>/ and symlinks .claude/skills/<name> to it Claude-Session: https://claude.ai/code/session_012Kj2MJEPXoUXC4LiC3XYJc Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/content/docs/build/agents.de.mdx b/content/docs/build/agents.de.mdx
@@ -182,7 +182,7 @@ Sie dieselbe Agent-Definition in einem Marketplace-Paket ausliefern.
 ## Wie es weitergeht
 
 - [AI Builder](/docs/build/ai-builder) — der Assistent zur Build-Zeit
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework`, damit Ihr IDE-Agent Metadaten korrekt erstellt
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills`, damit Ihr IDE-Agent Metadaten korrekt erstellt
 - [Actions](/docs/build/interface/actions) — deklarieren Sie die Tools, die Ihre Agents verwenden werden
 - [AI Service](/docs/configure/ai) — Anbieter-, Embedder- und MCP-Einrichtung
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — vollständige Schemas
diff --git a/content/docs/build/agents.es.mdx b/content/docs/build/agents.es.mdx
@@ -182,7 +182,7 @@ distribuyes la misma definición de agente en un paquete del marketplace.
 ## A dónde ir después
 
 - [AI Builder](/docs/build/ai-builder) — el asistente de tiempo de build
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework` para que el agente de tu IDE genere los metadatos correctamente
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills` para que el agente de tu IDE genere los metadatos correctamente
 - [Actions](/docs/build/interface/actions) — declara las tools que usarán tus agentes
 - [AI Service](/docs/configure/ai) — configuración de proveedor, embedder y MCP
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — esquemas completos
diff --git a/content/docs/build/agents.fr.mdx b/content/docs/build/agents.fr.mdx
@@ -187,7 +187,7 @@ d'agent dans un package du marketplace.
 ## Pour aller plus loin
 
 - [AI Builder](/docs/build/ai-builder) — l'assistant au moment du build
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework` pour que votre agent d'IDE rédige correctement les métadonnées
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills` pour que votre agent d'IDE rédige correctement les métadonnées
 - [Actions](/docs/build/interface/actions) — déclarez les outils que vos agents utiliseront
 - [AI Service](/docs/configure/ai) — configuration du fournisseur, de l'embedder et de MCP
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — schémas complets
diff --git a/content/docs/build/agents.ja.mdx b/content/docs/build/agents.ja.mdx
@@ -178,7 +178,7 @@ marketplace パッケージで同じエージェント定義を出荷してい
 ## 次に進む先
 
 - [AI Builder](/docs/build/ai-builder) — ビルド時のアシスタント
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework` で、IDE エージェントがメタデータを正しく作成できるようにします
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills` で、IDE エージェントがメタデータを正しく作成できるようにします
 - [Actions](/docs/build/interface/actions) — エージェントが使用するツールを宣言します
 - [AI Service](/docs/configure/ai) — プロバイダー、エンベッダー、MCP のセットアップ
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — 完全なスキーマ
diff --git a/content/docs/build/agents.ko.mdx b/content/docs/build/agents.ko.mdx
@@ -178,7 +178,7 @@ marketplace 패키지로 배포하더라도, 테넌트 A의 `tier1_support` 에
 ## 다음으로 갈 곳
 
 - [AI Builder](/docs/build/ai-builder) — 빌드 타임 어시스턴트
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework` 로 IDE 에이전트가 메타데이터를 올바르게 작성하도록 합니다
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills` 로 IDE 에이전트가 메타데이터를 올바르게 작성하도록 합니다
 - [Actions](/docs/build/interface/actions) — 에이전트가 사용할 도구를 선언합니다
 - [AI Service](/docs/configure/ai) — 프로바이더, 임베더, MCP 설정
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — 전체 스키마
diff --git a/content/docs/build/agents.mdx b/content/docs/build/agents.mdx
@@ -181,7 +181,7 @@ the same agent definition in a marketplace package.
 ## Where to go next
 
 - [AI Builder](/docs/build/ai-builder) — the build-time assistant
-- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework` so your IDE agent authors metadata correctly
+- [IDE Skills](/docs/build/ai-skills) — `npx skills add objectstack-ai/framework/skills` so your IDE agent authors metadata correctly
 - [Actions](/docs/build/interface/actions) — declare the tools your agents will use
 - [AI Service](/docs/configure/ai) — provider, embedder, MCP setup
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) — full schemas
diff --git a/content/docs/build/agents.zh-Hans.mdx b/content/docs/build/agents.zh-Hans.mdx
@@ -150,7 +150,7 @@ Agents 是按 Environment 划分的。租户 A 的 `tier1_support` agent 永远
 ## 下一步去哪里
 
 - [AI Builder](/docs/build/ai-builder) —— 构建期助手
-- [IDE Skills](/docs/build/ai-skills) —— `npx skills add objectstack-ai/framework`，让你的 IDE agent 正确地编写元数据
+- [IDE Skills](/docs/build/ai-skills) —— `npx skills add objectstack-ai/framework/skills`，让你的 IDE agent 正确地编写元数据
 - [Actions](/docs/build/interface/actions) —— 声明你的 agent 将使用的 tool
 - [AI Service](/docs/configure/ai) —— provider、embedder、MCP 设置
 - [`@objectstack/spec/ai`](https://github.com/objectstack-ai/framework/tree/main/packages/spec/src/ai) —— 完整 schema
diff --git a/content/docs/build/ai-skills.de.mdx b/content/docs/build/ai-skills.de.mdx
@@ -20,7 +20,7 @@ opencode** und etwa 50 weiteren Agents.
 In jedem Projekt, das `@objectstack/*`-Pakete verwendet:
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 Die CLI erkennt, welche Agents Sie konfiguriert haben (`.claude/`,
@@ -102,7 +102,7 @@ veröffentlichen wollen** (siehe [Templates](./templates) und [Marketplace](./ma
 ## Aktualisieren
 
 Die Skills folgen den `@objectstack/spec`-Versionen. Führen Sie
-`npx skills add objectstack-ai/framework` nach dem Upgrade des Spec-Pakets
+`npx skills add objectstack-ai/framework/skills` nach dem Upgrade des Spec-Pakets
 erneut aus, um Ihren Agent mit den neuesten Zod-Schemas, CEL-Helfern und
 dem Metadaten-Vokabular synchron zu halten.
 
diff --git a/content/docs/build/ai-skills.es.mdx b/content/docs/build/ai-skills.es.mdx
@@ -20,7 +20,7 @@ Continue, Roo, Goose, Kiro, opencode** y ~50 agentes más.
 En cualquier proyecto que use paquetes `@objectstack/*`:
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 El CLI detecta qué agentes tienes configurados (`.claude/`,
@@ -104,7 +104,7 @@ para la personalización del tenant y las AI Skills para IDE al trabajar en
 ## Actualización
 
 Las skills siguen las versiones de `@objectstack/spec`. Vuelve a ejecutar
-`npx skills add objectstack-ai/framework` tras actualizar el paquete spec
+`npx skills add objectstack-ai/framework/skills` tras actualizar el paquete spec
 para mantener tu agente sincronizado con los últimos esquemas Zod,
 helpers de CEL y vocabulario de metadatos.
 
diff --git a/content/docs/build/ai-skills.fr.mdx b/content/docs/build/ai-skills.fr.mdx
@@ -22,7 +22,7 @@ cinquantaine d'autres agents.
 Dans n'importe quel projet utilisant les packages `@objectstack/*` :
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 La CLI détecte les agents que vous avez configurés (`.claude/`,
@@ -107,7 +107,7 @@ travaillent sur des **packages qu'elles comptent publier** (voir
 ## Mise à jour
 
 Les skills suivent les versions de `@objectstack/spec`. Relancez
-`npx skills add objectstack-ai/framework` après avoir mis à niveau le
+`npx skills add objectstack-ai/framework/skills` après avoir mis à niveau le
 package spec pour garder votre agent synchronisé avec les derniers
 schémas Zod, helpers CEL et vocabulaire de métadonnées.
 
diff --git a/content/docs/build/ai-skills.ja.mdx b/content/docs/build/ai-skills.ja.mdx
@@ -20,7 +20,7 @@ opencode** およびその他約 50 種類のエージェントで動作しま
 `@objectstack/*` パッケージを使用しているプロジェクトであればどこでも:
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 CLI は構成済みのエージェント (`.claude/`、`.cursor/`、`.github/copilot/`、
@@ -101,7 +101,7 @@ AI Builder を使い、**公開を意図したパッケージ** を扱う際に
 ## 更新
 
 スキルは `@objectstack/spec` のバージョンに追従します。spec パッケージを
-アップグレードした後に `npx skills add objectstack-ai/framework` を再実行して、
+アップグレードした後に `npx skills add objectstack-ai/framework/skills` を再実行して、
 エージェントを最新の Zod スキーマ、CEL ヘルパー、メタデータ語彙と
 同期させてください。
 
diff --git a/content/docs/build/ai-skills.ko.mdx b/content/docs/build/ai-skills.ko.mdx
@@ -20,7 +20,7 @@ opencode** 및 그 외 약 50개의 에이전트와 함께 작동합니다.
 `@objectstack/*` 패키지를 사용하는 모든 프로젝트에서:
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 CLI는 어떤 에이전트가 구성되어 있는지(`.claude/`,
@@ -103,7 +103,7 @@ Builder를, 그리고 **게시할 의도가 있는 패키지** 작업에는 IDE
 ## 업데이트
 
 Skills는 `@objectstack/spec` 버전을 따릅니다. spec 패키지를 업그레이드한
-후 `npx skills add objectstack-ai/framework`를 다시 실행하여 에이전트를
+후 `npx skills add objectstack-ai/framework/skills`를 다시 실행하여 에이전트를
 최신 Zod 스키마, CEL 헬퍼, 메타데이터 어휘와 동기화 상태로 유지하세요.
 
 ## 관련 항목
diff --git a/content/docs/build/ai-skills.mdx b/content/docs/build/ai-skills.mdx
@@ -20,7 +20,7 @@ opencode** and ~50 other agents.
 In any project that uses `@objectstack/*` packages:
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 The CLI detects which agents you have configured (`.claude/`,
@@ -102,7 +102,7 @@ publish** (see [Templates](./templates) and [Marketplace](./marketplace)).
 ## Updating
 
 The skills follow `@objectstack/spec` versions. Re-run
-`npx skills add objectstack-ai/framework` after upgrading the spec
+`npx skills add objectstack-ai/framework/skills` after upgrading the spec
 package to keep your agent in sync with the latest Zod schemas, CEL
 helpers, and metadata vocabulary.
 
diff --git a/content/docs/build/ai-skills.zh-Hans.mdx b/content/docs/build/ai-skills.zh-Hans.mdx
@@ -12,7 +12,7 @@ ObjectOS 提供 **9 个一方 Agent Skill**，教编码助手如何编写各类
 在任何使用 `@objectstack/*` 包的项目里：
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 CLI 会检测你配置了哪些 Agent（`.claude/`、`.cursor/`、`.github/copilot/`、`AGENTS.md` 等），并把 Skill 写到正确位置。随时重跑可拉取最新版本。
@@ -77,7 +77,7 @@ metadata:
 
 ## 升级
 
-Skill 跟随 `@objectstack/spec` 版本。升级 spec 包后重跑 `npx skills add objectstack-ai/framework`，可让你的 Agent 与最新的 Zod schema、CEL 辅助函数、元数据词汇保持同步。
+Skill 跟随 `@objectstack/spec` 版本。升级 spec 包后重跑 `npx skills add objectstack-ai/framework/skills`，可让你的 Agent 与最新的 Zod schema、CEL 辅助函数、元数据词汇保持同步。
 
 ## 相关
 
diff --git a/content/docs/quickstart.de.mdx b/content/docs/quickstart.de.mdx
@@ -79,7 +79,7 @@ REST-Endpunkte, Console-Ansichten, Audit-Log-Einträge, Berechtigungsschranken.
 Keine Datei bearbeitet, kein Neustart. Siehe [Build → AI Builder](/docs/build/ai-builder)
 für das vollständige Vokabular.
 
-> **Handcodierung in Ihrer IDE?** Führen Sie `npx skills add objectstack-ai/framework` aus,
+> **Handcodierung in Ihrer IDE?** Führen Sie `npx skills add objectstack-ai/framework/skills` aus,
 > um Claude Code / Cursor / Copilot / Codex beizubringen, wie man
 > ObjectOS-Metadaten gegen die echten Zod-Schemas verfasst. Siehe
 > [Build → IDE Skills](/docs/build/ai-skills).
diff --git a/content/docs/quickstart.es.mdx b/content/docs/quickstart.es.mdx
@@ -79,7 +79,7 @@ endpoints REST, vistas de Console, entradas de registro de auditoría, controles
 Sin editar archivos, sin reiniciar. Consulta [Build → AI Builder](/docs/build/ai-builder)
 para conocer todo el vocabulario.
 
-> **¿Programando a mano en tu IDE?** Ejecuta `npx skills add objectstack-ai/framework`
+> **¿Programando a mano en tu IDE?** Ejecuta `npx skills add objectstack-ai/framework/skills`
 > para enseñar a Claude Code / Cursor / Copilot / Codex a crear
 > metadatos de ObjectOS con los esquemas reales de Zod. Consulta
 > [Build → IDE Skills](/docs/build/ai-skills).
diff --git a/content/docs/quickstart.fr.mdx b/content/docs/quickstart.fr.mdx
@@ -79,7 +79,7 @@ points de terminaison REST, vues Console, entrées du journal d'audit, contrôle
 de permissions. Aucun fichier modifié, aucun redémarrage. Consultez
 [Build → AI Builder](/docs/build/ai-builder) pour le vocabulaire complet.
 
-> **Vous codez à la main dans votre IDE ?** Exécutez `npx skills add objectstack-ai/framework`
+> **Vous codez à la main dans votre IDE ?** Exécutez `npx skills add objectstack-ai/framework/skills`
 > pour apprendre à Claude Code / Cursor / Copilot / Codex comment rédiger
 > des métadonnées ObjectOS conformes aux véritables schémas Zod. Consultez
 > [Build → IDE Skills](/docs/build/ai-skills).
diff --git a/content/docs/quickstart.ja.mdx b/content/docs/quickstart.ja.mdx
@@ -70,7 +70,7 @@ os start
 
 AI がプランを提案し、あなたが承認すると、メタデータが即座に有効になります — REST エンドポイント、Console ビュー、監査ログのエントリ、権限ゲート。ファイルの編集も再起動も不要です。完全な語彙については [Build → AI Builder](/docs/build/ai-builder) を参照してください。
 
-> **IDE で手書きコーディングしますか？** `npx skills add objectstack-ai/framework` を実行すると、Claude Code / Cursor / Copilot / Codex に、本物の Zod スキーマに対して ObjectOS メタデータを記述する方法を教えられます。[Build → IDE Skills](/docs/build/ai-skills) を参照してください。
+> **IDE で手書きコーディングしますか？** `npx skills add objectstack-ai/framework/skills` を実行すると、Claude Code / Cursor / Copilot / Codex に、本物の Zod スキーマに対して ObjectOS メタデータを記述する方法を教えられます。[Build → IDE Skills](/docs/build/ai-skills) を参照してください。
 
 ### marketplace からアプリをインストールする
 
diff --git a/content/docs/quickstart.ko.mdx b/content/docs/quickstart.ko.mdx
@@ -78,7 +78,7 @@ REST 엔드포인트, Console 뷰, 감사 로그 항목, 권한 게이트까지.
 파일 편집도, 재시작도 필요 없습니다. 전체 어휘는 [Build → AI Builder](/docs/build/ai-builder)를
 참고하세요.
 
-> **IDE에서 직접 코딩하시나요?** `npx skills add objectstack-ai/framework`를
+> **IDE에서 직접 코딩하시나요?** `npx skills add objectstack-ai/framework/skills`를
 > 실행하여 Claude Code / Cursor / Copilot / Codex가 실제 Zod 스키마에 맞춰
 > ObjectOS 메타데이터를 작성하는 방법을 익히도록 하세요.
 > [Build → IDE Skills](/docs/build/ai-skills)를 참고하세요.
diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx
@@ -79,7 +79,7 @@ REST endpoints, Console views, audit log entries, permission gates.
 No file edited, no restart. See [Build → AI Builder](/docs/build/ai-builder)
 for the full vocabulary.
 
-> **Hand-coding in your IDE?** Run `npx skills add objectstack-ai/framework`
+> **Hand-coding in your IDE?** Run `npx skills add objectstack-ai/framework/skills`
 > to teach Claude Code / Cursor / Copilot / Codex how to author
 > ObjectOS metadata against the real Zod schemas. See
 > [Build → IDE Skills](/docs/build/ai-skills).
diff --git a/content/docs/quickstart.zh-Hans.mdx b/content/docs/quickstart.zh-Hans.mdx
@@ -70,7 +70,7 @@ os start
 
 AI 提出一份计划，你批准，元数据就立刻生效 —— REST 端点、Console 视图、审计日志、权限闸门。无需编辑文件，无需重启。完整词汇请见 [Build → AI Builder](/docs/build/ai-builder)。
 
-> **在 IDE 中手写代码？** 运行 `npx skills add objectstack-ai/framework`，让 Claude Code / Cursor / Copilot / Codex 学会根据真实的 Zod schema 编写 ObjectOS 元数据。参见 [Build → IDE Skills](/docs/build/ai-skills)。
+> **在 IDE 中手写代码？** 运行 `npx skills add objectstack-ai/framework/skills`，让 Claude Code / Cursor / Copilot / Codex 学会根据真实的 Zod schema 编写 ObjectOS 元数据。参见 [Build → IDE Skills](/docs/build/ai-skills)。
 
 ### 从市场安装应用
 
diff --git a/content/docs/reference/skills-cli.de.mdx b/content/docs/reference/skills-cli.de.mdx
@@ -14,7 +14,7 @@ findest du unter [Build → IDE Skills](/docs/build/ai-skills).
 ## Installation
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 Beim ersten Ausführen wird das
@@ -32,7 +32,7 @@ Automatisch erkannt anhand dessen, was sich in deinem Projekt befindet:
 
 | Agent | Geschriebener Pfad |
 |:--|:--|
-| Claude Code | `.claude/skills/<name>/SKILL.md` |
+| Claude Code | `.claude/skills/<name>/` → symlink to `.agents/skills/<name>/` |
 | Cursor | `.cursor/rules/<name>.mdc` |
 | GitHub Copilot | `.github/copilot-instructions.md` (konsolidiert) |
 | Codex / Codex CLI | `AGENTS.md` (konsolidiert) |
@@ -62,7 +62,7 @@ laden soll und wann an einen verwandten Skill abgegeben werden soll.
 
 ```bash
 npx skills add <org>/<repo>        # add a skill bundle from a GitHub repo
-npx skills add <org>/<repo>@<ref>  # pin to a tag / branch / SHA
+npx skills add https://github.com/<org>/<repo>/tree/<ref>/<path>  # pin to a tag / branch / SHA
 npx skills list                    # list installed skills
 npx skills remove <name>           # remove a skill
 npx skills detect                  # show which agents the CLI will write to
@@ -72,7 +72,7 @@ npx skills --help                  # full options
 Pinne eine Version für reproduzierbare CI:
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## Wo die Ausgabe committet werden sollte
@@ -85,7 +85,7 @@ die du ohnehin normalerweise einchecken würdest.
 ## Aktualisieren
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 Führe den Befehl nach dem Upgrade von `@objectstack/spec` erneut aus,
diff --git a/content/docs/reference/skills-cli.es.mdx b/content/docs/reference/skills-cli.es.mdx
@@ -15,7 +15,7 @@ consulta [Build → IDE Skills](/docs/build/ai-skills).
 ## Instalación
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 La primera ejecución descarga el paquete [`skills`](https://www.npmjs.com/package/skills)
@@ -32,7 +32,7 @@ Se detecta automáticamente según lo que haya en tu proyecto:
 
 | Agente | Ruta escrita |
 |:--|:--|
-| Claude Code | `.claude/skills/<name>/SKILL.md` |
+| Claude Code | `.claude/skills/<name>/` → symlink to `.agents/skills/<name>/` |
 | Cursor | `.cursor/rules/<name>.mdc` |
 | GitHub Copilot | `.github/copilot-instructions.md` (consolidado) |
 | Codex / Codex CLI | `AGENTS.md` (consolidado) |
@@ -62,7 +62,7 @@ agente cargarlo y cuándo delegar en uno hermano.
 
 ```bash
 npx skills add <org>/<repo>        # add a skill bundle from a GitHub repo
-npx skills add <org>/<repo>@<ref>  # pin to a tag / branch / SHA
+npx skills add https://github.com/<org>/<repo>/tree/<ref>/<path>  # pin to a tag / branch / SHA
 npx skills list                    # list installed skills
 npx skills remove <name>           # remove a skill
 npx skills detect                  # show which agents the CLI will write to
@@ -72,7 +72,7 @@ npx skills --help                  # full options
 Fija una versión para una CI reproducible:
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## Dónde confirmar la salida
@@ -85,7 +85,7 @@ incluirías en el control de versiones de todos modos.
 ## Actualización
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 Vuelve a ejecutarlo después de actualizar `@objectstack/spec` para que
diff --git a/content/docs/reference/skills-cli.fr.mdx b/content/docs/reference/skills-cli.fr.mdx
diff --git a/content/docs/reference/skills-cli.ja.mdx b/content/docs/reference/skills-cli.ja.mdx
diff --git a/content/docs/reference/skills-cli.ko.mdx b/content/docs/reference/skills-cli.ko.mdx
diff --git a/content/docs/reference/skills-cli.mdx b/content/docs/reference/skills-cli.mdx
diff --git a/content/docs/reference/skills-cli.zh-Hans.mdx b/content/docs/reference/skills-cli.zh-Hans.mdx
