diff --git a/content/docs/build/agents.de.mdx b/content/docs/build/agents.de.mdx
index 8a2f3b8..3f76e6f 100644
--- 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
index da4a6ad..861d198 100644
--- 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
index 68bac87..f3937d7 100644
--- 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
index 93f2088..c433677 100644
--- 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
index 4299801..c80b0bd 100644
--- 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
index ab6c82a..aa2841b 100644
--- 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
index b4f3a17..1247363 100644
--- 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
index 5e561ee..9451672 100644
--- 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
index f3471fd..7abaefa 100644
--- 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
index e89b903..2c7ee21 100644
--- 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
index 34a6e41..ce5ae8d 100644
--- 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
index b962823..a1f735b 100644
--- 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
index dd2f08a..ea187f9 100644
--- 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
index 323dfa4..e590342 100644
--- 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
index 36cb8bf..62a9d00 100644
--- 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
index e2b6809..2ff496b 100644
--- 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
index 1f5b298..1cdbb6b 100644
--- 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
index 3773573..00f56bd 100644
--- 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
index 871c7a9..74634b5 100644
--- 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
index 81188a4..51815e2 100644
--- 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
index 1b8f2a5..54d7439 100644
--- 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
index 2ee4f20..2f17e71 100644
--- 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
index 955431f..b7434da 100644
--- 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
index 85b822f..973c68d 100644
--- a/content/docs/reference/skills-cli.fr.mdx
+++ b/content/docs/reference/skills-cli.fr.mdx
@@ -15,7 +15,7 @@ conceptuelle, voir [Build → IDE Skills](/docs/build/ai-skills).
 ## Installation
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 Lors de la première exécution, le paquet
@@ -33,7 +33,7 @@ Détecté automatiquement en fonction du contenu de votre projet :
 
 | Agent | Chemin écrit |
 |:--|:--|
-| 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` (consolidé) |
 | Codex / Codex CLI | `AGENTS.md` (consolidé) |
@@ -63,7 +63,7 @@ le charger et quand déférer à un skill voisin.
 
 ```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
@@ -73,7 +73,7 @@ npx skills --help                  # full options
 Épinglez une version pour une CI reproductible :
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## Où committer la sortie
@@ -86,7 +86,7 @@ vous versionneriez normalement de toute façon.
 ## Mise à jour
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 Réexécutez après avoir mis à niveau `@objectstack/spec` afin que l'agent
diff --git a/content/docs/reference/skills-cli.ja.mdx b/content/docs/reference/skills-cli.ja.mdx
index dcfead4..0dc40e0 100644
--- a/content/docs/reference/skills-cli.ja.mdx
+++ b/content/docs/reference/skills-cli.ja.mdx
@@ -14,7 +14,7 @@ description: ObjectOS のスキルバンドルをコーディングエージェ
 ## インストール
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 初回実行時には、`npx` 経由で npm から
@@ -31,7 +31,7 @@ npx skills add objectstack-ai/framework
 
 | エージェント | 書き込まれるパス |
 |:--|:--|
-| 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`（統合） |
 | Codex / Codex CLI | `AGENTS.md`（統合） |
@@ -61,7 +61,7 @@ CLI が書き込もうとする内容を確認するには `npx skills detect` 
 
 ```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
@@ -71,7 +71,7 @@ npx skills --help                  # full options
 再現可能な CI のためにバージョンを固定する場合：
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## 出力をどこにコミットするか
@@ -83,7 +83,7 @@ npx skills add objectstack-ai/framework@v5.0.0
 ## 更新
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 `@objectstack/spec` をアップグレードした後に再実行すると、エージェントが
diff --git a/content/docs/reference/skills-cli.ko.mdx b/content/docs/reference/skills-cli.ko.mdx
index 74a23eb..d31bbbb 100644
--- a/content/docs/reference/skills-cli.ko.mdx
+++ b/content/docs/reference/skills-cli.ko.mdx
@@ -13,7 +13,7 @@ description: ObjectOS 스킬 번들을 코딩 에이전트에 설치하는 npx 
 ## 설치
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 처음 실행하면 `npx`를 통해 npm에서 [`skills`](https://www.npmjs.com/package/skills)
@@ -30,7 +30,7 @@ npx skills add objectstack-ai/framework
 
 | 에이전트 | 기록되는 경로 |
 |:--|:--|
-| 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` (통합) |
 | Codex / Codex CLI | `AGENTS.md` (통합) |
@@ -60,7 +60,7 @@ CLI가 기록할 내용을 확인하려면 `npx skills detect`를 실행하세
 
 ```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
@@ -70,7 +70,7 @@ npx skills --help                  # full options
 재현 가능한 CI를 위해 버전을 고정하세요.
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## 출력을 어디에 커밋해야 하나요
@@ -82,7 +82,7 @@ npx skills add objectstack-ai/framework@v5.0.0
 ## 업데이트
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 `@objectstack/spec`를 업그레이드한 후 다시 실행하면 에이전트가 최신
diff --git a/content/docs/reference/skills-cli.mdx b/content/docs/reference/skills-cli.mdx
index 13a2a49..30bf2be 100644
--- a/content/docs/reference/skills-cli.mdx
+++ b/content/docs/reference/skills-cli.mdx
@@ -14,7 +14,7 @@ This page is a reference card. For the conceptual overview see
 ## Install
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 The first run downloads the [`skills`](https://www.npmjs.com/package/skills)
@@ -31,7 +31,7 @@ Detected automatically based on what's in your project:
 
 | Agent | Path written |
 |:--|:--|
-| 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` (consolidated) |
 | Codex / Codex CLI | `AGENTS.md` (consolidated) |
@@ -61,7 +61,7 @@ load it and when to defer to a sibling.
 
 ```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
@@ -71,7 +71,7 @@ npx skills --help                  # full options
 Pin a version for reproducible CI:
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## Where to commit the output
@@ -84,7 +84,7 @@ anyway.
 ## Updating
 
 ```bash
-npx skills add objectstack-ai/framework      # pulls latest matching the spec version range
+npx skills add objectstack-ai/framework/skills
 ```
 
 Re-run after upgrading `@objectstack/spec` so the agent stays in sync
diff --git a/content/docs/reference/skills-cli.zh-Hans.mdx b/content/docs/reference/skills-cli.zh-Hans.mdx
index 3c47429..5144287 100644
--- a/content/docs/reference/skills-cli.zh-Hans.mdx
+++ b/content/docs/reference/skills-cli.zh-Hans.mdx
@@ -10,7 +10,7 @@ description: 将 ObjectOS skill 包安装到编码 Agent 的 npx 命令。
 ## 安装
 
 ```bash
-npx skills add objectstack-ai/framework
+npx skills add objectstack-ai/framework/skills
 ```
 
 首次运行通过 `npx` 从 npm 下载 [`skills`](https://www.npmjs.com/package/skills) 包,然后从 [github.com/objectstack-ai/framework](https://github.com/objectstack-ai/framework) 拉取 skill 包(`skills/<name>/` 目录)并写入你的项目 Agent 配置。
@@ -23,7 +23,7 @@ npx skills add objectstack-ai/framework
 
 | Agent | 写入路径 |
 |:--|:--|
-| 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`（合并） |
 | Codex / Codex CLI | `AGENTS.md`（合并） |
@@ -52,7 +52,7 @@ npx skills add objectstack-ai/framework
 
 ```bash
 npx skills add <org>/<repo>        # 从 GitHub 仓库添加 skill 包
-npx skills add <org>/<repo>@<ref>  # 钉到 tag / 分支 / SHA
+npx skills add https://github.com/<org>/<repo>/tree/<ref>/<path>  # 钉到 tag / 分支 / SHA
 npx skills list                    # 列出已安装 skill
 npx skills remove <name>           # 移除 skill
 npx skills detect                  # 显示 CLI 将写入哪些 Agent
@@ -62,7 +62,7 @@ npx skills --help                  # 完整选项
 为可复现 CI 钉定版本：
 
 ```bash
-npx skills add objectstack-ai/framework@v5.0.0
+npx skills add https://github.com/objectstack-ai/framework/tree/<commit-sha>/skills
 ```
 
 ## 输出应提交在哪
@@ -72,7 +72,7 @@ npx skills add objectstack-ai/framework@v5.0.0
 ## 更新
 
 ```bash
-npx skills add objectstack-ai/framework      # 拉取匹配 spec 版本范围的最新版本
+npx skills add objectstack-ai/framework/skills
 ```
 
 升级 `@objectstack/spec` 后重新运行,使 Agent 与最新 Zod schema、CEL 辅助函数和元数据词汇保持同步。