diff --git a/README.md b/README.md
index 150c2729..1c0f43fe 100644
--- a/README.md
+++ b/README.md
@@ -515,8 +515,9 @@ Because SkillHub speaks the same `SKILL.md` format, skills from `anthropics/skil
 git clone https://github.com/anthropics/skills
 
 # ...and publish it into your private SkillHub registry
-export CLAWHUB_REGISTRY=https://skillhub.your-company.com
-npx clawhub publish ./skills/<category>/<skill-name>
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./skills/<category>/<skill-name>
 ```
 
 > ⚖️ **Licensing**: honor each skill's own license when republishing. Most skills in
@@ -546,16 +547,18 @@ npx clawhub search email
 npx clawhub install my-skill
 npx clawhub install my-namespace--my-skill
 
-# Publish to global namespace
-npx clawhub publish ./my-skill --slug my-skill --version 1.0.0
-
-# Publish to a team namespace such as my-space
-npx clawhub publish ./my-skill --slug my-space--my-skill --version 1.0.0
+# Publishing uses the first-party SkillHub CLI
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space
 ```
 
 `my-space--my-skill` is the canonical compat slug. SkillHub parses it as
 namespace `my-space` plus skill slug `my-skill`.
 
+ClawHub compatibility covers search, inspection, and installation. Its publish
+protocol is not compatible with SkillHub; use the first-party CLI shown above.
+
 > 💡 **Tip**: The above commands are not only applicable to OpenClaw, but also to other CLI Coding Agents or Agent assistants by specifying the installation directory (`--dir`). For example: `npx clawhub --dir ~/.claude/skills install my-skill`
 
 📖 **[Complete OpenClaw Integration Guide →](./docs/openclaw-integration.md)**
diff --git a/README_zh.md b/README_zh.md
index 90ee1ae9..4ea2d82b 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -401,8 +401,9 @@ Agent Skill 目录——都可以直接发布到你的注册中心：
 git clone https://github.com/anthropics/skills
 
 # ……并将其发布到你的私有 SkillHub 注册中心
-export CLAWHUB_REGISTRY=https://skillhub.your-company.com
-npx clawhub publish ./skills/<分类>/<技能名>
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./skills/<分类>/<技能名>
 ```
 
 > ⚖️ **许可提示**：转发布时请遵守每个技能各自的许可证。`anthropics/skills` 中大多数技能
@@ -431,16 +432,18 @@ npx clawhub search email
 npx clawhub install my-skill
 npx clawhub install my-namespace--my-skill
 
-# 发布到 global 空间
-npx clawhub publish ./my-skill --slug my-skill --version 1.0.0
-
-# 发布到如 my-space 这样的团队空间
-npx clawhub publish ./my-skill --slug my-space--my-skill --version 1.0.0
+# 发布请使用第一方 SkillHub CLI
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space
 ```
 
 其中 `my-space--my-skill` 是兼容层使用的 canonical slug，SkillHub 会将其解析为
 namespace `my-space` 和 skill slug `my-skill`。
 
+ClawHub 兼容范围包含搜索、查看和安装；其发布协议与 SkillHub 不兼容。
+发布请使用上面的第一方 CLI。
+
 > 💡 **提示**：上述命令不仅适用于 OpenClaw，通过指定安装目录（`--dir`），也可适用于其他的 CLI Coding Agent 或 Agent 助手。例如：`npx clawhub --dir ~/.claude/skills install my-skill`
 
 📖 **[完整 OpenClaw 集成指南 →](./docs/openclaw-integration.md)**
diff --git a/docs/openclaw-integration-en.md b/docs/openclaw-integration-en.md
index 32cb2878..3c022717 100644
--- a/docs/openclaw-integration-en.md
+++ b/docs/openclaw-integration-en.md
@@ -1,25 +1,31 @@
 # OpenClaw Integration Guide
 
-This document explains how to configure OpenClaw CLI to connect to a SkillHub private registry for publishing, searching, and downloading skills.
+This document explains how to configure the ClawHub CLI to connect to a private SkillHub registry for search, inspection, and installation. Use the first-party SkillHub CLI for publishing.
 > Not only applicable to Openclaw, but also compatible with other CLI Coding Agents (Claude Code, OpenCode, Qcoder, etc.) or Agent assistants (Nanobot, CoPaw, etc.) by specifying the installation directory.
 
 ## Overview
 
-SkillHub provides a ClawHub-compatible API layer, allowing OpenClaw CLI to seamlessly integrate with private registries. With simple configuration, you can:
+SkillHub provides a ClawHub-compatible API for common read and install flows. With simple configuration, you can:
 
 - 🔍 Search for private skills within your organization
 - 📥 Download and install skill packages
-- 📤 Publish new skills to the private registry
-- ⭐ Star and rate skills
+- ⭐ Star skills
+
+Current compatibility boundaries:
+
+- ClawHub CLI `0.23.3` uses `/api/v1/whoami`, which matches the SkillHub compatibility API.
+- ClawHub publishing depends on upload-ticket endpoints that SkillHub does not implement, so `clawhub publish` and `clawhub sync` are not supported.
+- ClawHub CLI `0.23.3` does not reliably prioritize the private Registry saved during `login`; site discovery or the default can select another target. Set `CLAWHUB_REGISTRY` in each shell session or pass `--registry` explicitly.
+- Canonical slugs use `--` between namespace and skill. SkillHub rejects new namespace or skill slugs containing consecutive `--`, keeping new coordinates unambiguous. Rename invalid legacy or externally imported coordinates before using the ClawHub CLI.
 
 ## Quick Start
 
 ### 1. Configure Registry URL
 
-Set the SkillHub registry address in your OpenClaw configuration:
+Set the SkillHub registry address for the current shell session:
 
 ```bash
-# Via environment variable (temporary)
+# Do not depend on the registry resolution order of the login configuration
 export CLAWHUB_REGISTRY=https://skillhub.your-company.com
 ```
 
@@ -29,7 +35,7 @@ For **global namespace (@global) PUBLIC skills**, no login is required to downlo
 
 - Team namespace skills (regardless of visibility)
 - NAMESPACE_ONLY or PRIVATE skills
-- Write operations like publishing, starring, etc.
+- Authenticated operations such as starring
 
 ```bash
 # Log in with an API token
@@ -107,24 +113,21 @@ npx clawhub uninstall --help
 npx clawhub list --help
 ```
 
-### 5. Publish Skills
+### 5. Publish with the SkillHub CLI
+
+The ClawHub CLI `0.23.3` publishing protocol is not compatible with SkillHub. Use the first-party SkillHub CLI:
 
 ```bash
-# Publish to the global namespace (requires appropriate permissions)
-npx clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0
-
-# Publish to a team namespace such as my-space
-npx clawhub publish ./my-skill --slug my-space--my-skill --name "My Skill" --version 1.0.0
-npx clawhub sync --all # Upload all skills in current folder
-
-# Help
-npx clawhub publish --help
-npx clawhub sync --help
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill --namespace global
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space
 ```
 
 Notes:
-- `my-space--my-skill` is the canonical compatibility slug. SkillHub parses it as namespace `my-space` plus skill slug `my-skill`
-- To avoid mismatches between CLI display text and the final persisted coordinate, keep the `name` in `SKILL.md` aligned with the canonical slug suffix
+- Publishing requires an API Token with the `skill:publish` scope and permission in the target namespace.
+- `clawhub login` and the SkillHub CLI do not share credentials; set `SKILLHUB_TOKEN` separately for the first-party CLI.
+- The first-party CLI uses a separate namespace option, but it still follows the server's slug validation rules.
 
 ## API Endpoints
 
@@ -138,9 +141,9 @@ SkillHub compatibility layer provides the following endpoints:
 | `/api/v1/download/{slug}` | GET | Download skill (redirect) | Optional* |
 | `/api/v1/download` | GET | Download skill (query params) | Optional* |
 | `/api/v1/skills/{slug}` | GET | Get skill details | Optional |
-| `/api/v1/skills/{slug}/star` | POST | Star a skill | Required |
-| `/api/v1/skills/{slug}/unstar` | DELETE | Unstar a skill | Required |
-| `/api/v1/publish` | POST | Publish a skill | Required |
+| `/api/v1/stars/{slug}` | POST | Star a skill | Required |
+| `/api/v1/stars/{slug}` | DELETE | Unstar a skill | Required |
+| `/api/v1/publish` | POST | Legacy compatibility endpoint; not used by ClawHub CLI `0.23.3` | Required |
 
 Notes:
 - The compatibility layer may still expose the term "latest" externally, but it must strictly mean "latest published version"
@@ -186,6 +189,8 @@ SkillHub internally uses `@{namespace}/{skill}` format, but the compatibility la
 
 OpenClaw CLI uses canonical slug format, and SkillHub handles the conversion automatically.
 
+The canonical format has no escaping rule, so SkillHub rejects new namespace or skill slugs containing consecutive `--`. If legacy or externally imported data bypassed that validation, rename the coordinate first; the first-party CLI does not bypass server-side slug validation.
+
 ## Configuration Examples
 
 ### ClawHub CLI Environment Variables
@@ -248,11 +253,15 @@ curl https://skillhub.your-company.com/api/v1/whoami \
 npx clawhub search ""
 ```
 
-### Q: Permission denied when publishing?
+### Q: Why does publishing with the ClawHub CLI fail?
 
-- Publishing to global namespace (`@global`) requires `SUPER_ADMIN` permission
-- Publishing to team namespace requires OWNER or ADMIN role in that namespace
-- Contact your administrator for appropriate permissions
+ClawHub CLI `0.23.3` uses an upload-ticket protocol outside SkillHub's compatibility scope. This failure does not mean that the API Token was revoked; use the first-party SkillHub CLI instead.
+
+If the first-party CLI reports insufficient permission:
+
+- The publisher must be a member of the target namespace; `SUPER_ADMIN` is exempt
+- A regular member may submit a publication; visibility and review rules decide whether it is published immediately or enters review
+- Contact a namespace administrator to join the target namespace
 
 ### Q: Which OpenClaw versions are supported?
 
diff --git a/docs/openclaw-integration.md b/docs/openclaw-integration.md
index f85f588e..26a9b99f 100644
--- a/docs/openclaw-integration.md
+++ b/docs/openclaw-integration.md
@@ -1,25 +1,31 @@
 # OpenClaw 集成指南
 
-本文档说明如何配置 OpenClaw CLI 连接到 SkillHub 私有注册中心，实现技能的发布、搜索和下载。
+本文档说明如何配置 ClawHub CLI 连接到 SkillHub 私有注册中心，实现技能的搜索、查看和安装。发布技能请使用第一方 SkillHub CLI。
 > 不仅适用于 Openclaw，通过指定安装目录，可适用于其他的 CLI Coding Agent (Claude Code、OpenCode、Qcoder等) 或者 Agent 助手（Nanobot、CoPaw等）。
 
 ## 概述
 
-SkillHub 提供了与 ClawHub 兼容的 API 层，使得 OpenClaw CLI 可以无缝对接私有注册中心。通过简单的配置，您可以：
+SkillHub 提供 ClawHub 兼容 API，覆盖常用的只读发现和安装流程。通过简单配置，您可以：
 
 - 🔍 搜索组织内的私有技能
 - 📥 下载和安装技能包
-- 📤 发布新技能到私有注册中心
-- ⭐ 收藏和评分技能
+- ⭐ 收藏技能
+
+当前兼容边界：
+
+- 已验证的 ClawHub CLI `0.23.3` 使用 `/api/v1/whoami`，与 SkillHub 兼容层一致。
+- ClawHub CLI 的发布协议依赖 SkillHub 未实现的上传票据接口，因此 `clawhub publish` 和 `clawhub sync` 不属于支持范围。
+- ClawHub CLI `0.23.3` 不会可靠地优先使用登录时保存的私有 Registry；站点发现或默认地址可能覆盖预期目标。每个终端会话都应设置 `CLAWHUB_REGISTRY`，或在命令中显式传入 `--registry`。
+- canonical slug 使用 `--` 分隔 namespace 与 skill。SkillHub 会拒绝新建包含连续 `--` 的 namespace 或 skill slug，以保证新坐标可无歧义解析；历史或外部导入的异常坐标应先重命名，再使用 ClawHub CLI。
 
 ## 快速开始
 
 ### 1. 配置 Registry 地址
 
-在 OpenClaw 配置文件中设置 SkillHub 注册中心地址：
+为当前终端会话设置 SkillHub 注册中心地址：
 
 ```bash
-# 通过环境变量配置（临时）
+# 不依赖 login 配置的 Registry 解析顺序
 export CLAWHUB_REGISTRY=https://skillhub.your-company.com
 ```
 
@@ -29,7 +35,7 @@ export CLAWHUB_REGISTRY=https://skillhub.your-company.com
 
 - 团队命名空间的技能（无论可见性）
 - NAMESPACE_ONLY 或 PRIVATE 技能
-- 发布、收藏等写操作
+- 收藏等需要登录的操作
 
 ```bash
 # 使用 API Token 登录
@@ -107,24 +113,21 @@ npx clawhub uninstall --help
 npx clawhub list --help
 ```
 
-### 5. 发布技能
+### 5. 使用 SkillHub CLI 发布技能
+
+ClawHub CLI `0.23.3` 的发布协议与 SkillHub 不兼容。请使用第一方 SkillHub CLI：
 
 ```bash
-# 发布到 global 空间（需要相应权限）
-npx clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0
-
-# 发布到如 my-space 这样的团队空间
-npx clawhub publish ./my-skill --slug my-space--my-skill --name "My Skill" --version 1.0.0
-npx clawhub sync --all # 上传当前文件夹中所有的 skill
-
-# 使用帮助
-npx clawhub publish --help
-npx clawhub sync --help
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill --namespace global
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space
 ```
 
 说明：
-- `my-space--my-skill` 是兼容层 canonical slug，SkillHub 会将其解析为 namespace `my-space` 和 skill slug `my-skill`
-- 为避免 CLI 展示与服务端最终坐标不一致，建议让 `SKILL.md` 中的 `name` 与 canonical slug 后半段保持一致
+- 发布需要具有 `skill:publish` scope 的 API Token，以及目标 namespace 对应权限。
+- `clawhub login` 与 SkillHub CLI 不共享凭据；请为第一方 CLI 单独设置 `SKILLHUB_TOKEN`。
+- 第一方 CLI 使用独立 namespace 参数，但仍遵循服务端 slug 校验规则。
 
 ## API 端点说明
 
@@ -138,9 +141,9 @@ SkillHub 兼容层提供以下端点：
 | `/api/v1/download/{slug}` | GET | 下载技能（重定向） | 可选* |
 | `/api/v1/download` | GET | 下载技能（查询参数） | 可选* |
 | `/api/v1/skills/{slug}` | GET | 获取技能详情 | 可选 |
-| `/api/v1/skills/{slug}/star` | POST | 收藏技能 | 必需 |
-| `/api/v1/skills/{slug}/unstar` | DELETE | 取消收藏 | 必需 |
-| `/api/v1/publish` | POST | 发布技能 | 必需 |
+| `/api/v1/stars/{slug}` | POST | 收藏技能 | 必需 |
+| `/api/v1/stars/{slug}` | DELETE | 取消收藏 | 必需 |
+| `/api/v1/publish` | POST | 旧版兼容发布端点；ClawHub CLI `0.23.3` 不使用 | 必需 |
 
 说明：
 - 兼容层对外继续使用 “latest” 语义，但这里严格指向“最新已发布版本”
@@ -186,6 +189,8 @@ SkillHub 内部使用 `@{namespace}/{skill}` 格式，但兼容层会自动转
 
 OpenClaw CLI 使用 canonical slug 格式，SkillHub 会自动处理转换。
 
+canonical 格式没有转义规则，因此 SkillHub 会拒绝新建包含连续 `--` 的 namespace 或 skill slug。若历史或外部导入数据绕过了该校验，应先重命名坐标；第一方 SkillHub CLI 虽使用独立 `--namespace` 参数，也不能绕过服务端 slug 校验。
+
 ## 配置示例
 
 ### ClawHub CLI 环境变量配置
@@ -248,11 +253,15 @@ curl https://skillhub.your-company.com/api/v1/whoami \
 npx clawhub search ""
 ```
 
-### Q: 发布技能时提示权限不足？
+### Q: 使用 ClawHub CLI 发布为什么失败？
 
-- 发布到全局命名空间（`@global`）需要 `SUPER_ADMIN` 权限
-- 发布到团队命名空间需要是该命名空间的 OWNER 或 ADMIN
-- 联系管理员分配相应权限
+ClawHub CLI `0.23.3` 使用的上传票据协议不在 SkillHub 兼容范围内。该错误不代表 API Token 已撤销；请改用第一方 SkillHub CLI。
+
+如果第一方 CLI 提示权限不足：
+
+- 发布者必须是目标命名空间成员；`SUPER_ADMIN` 例外
+- 普通成员可提交发布，是否直接发布或进入审核由可见性和审核规则决定
+- 联系命名空间管理员加入目标空间
 
 ### Q: 支持哪些 OpenClaw 版本？
 
diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md
index 7cc4500f..83ba79f2 100644
--- a/docs/skillhub/en/faq.md
+++ b/docs/skillhub/en/faq.md
@@ -65,8 +65,10 @@ npx clawhub search email
 # Install a skill package
 npx clawhub install my-skill
 
-# Publish a skill package
-npx clawhub publish ./my-skill
+# Publish a skill package (the ClawHub CLI publishing protocol is not compatible)
+export SKILLHUB_REGISTRY=http://your-skillhub-host:8080
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill
 ```
 
 ## Q: How do I configure HTTPS?
diff --git a/docs/skillhub/en/guide/skill-publish.md b/docs/skillhub/en/guide/skill-publish.md
index c217485b..3224f4d7 100644
--- a/docs/skillhub/en/guide/skill-publish.md
+++ b/docs/skillhub/en/guide/skill-publish.md
@@ -57,16 +57,19 @@ Ensure skill package conforms to SkillHub specification:
 2. **Publish via CLI (Recommended)**
 
 ```bash
-# Configure registry
-export CLAWHUB_REGISTRY=http://localhost:8080
+# Configure the SkillHub registry
+export SKILLHUB_REGISTRY=http://localhost:8080
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
 
 # Publish to default namespace
-npx clawhub publish ./my-skill
+npx @astron-team/skillhub@latest publish ./my-skill
 
 # Publish to specific namespace
-npx clawhub publish ./my-skill --namespace my-team
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
 ```
 
+> The ClawHub CLI publish and sync protocols are not compatible with SkillHub. Use the SkillHub CLI above for publishing.
+
 3. **Publish via Web UI**
 
 Visit `http://localhost:3000/dashboard/publish`, select namespace, upload zip file, choose visibility, and click "Publish".
diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md
index b16ecd81..10d255b2 100644
--- a/docs/skillhub/faq.md
+++ b/docs/skillhub/faq.md
@@ -65,8 +65,10 @@ npx clawhub search email
 # 安装技能包
 npx clawhub install my-skill
 
-# 发布技能包
-npx clawhub publish ./my-skill
+# 发布技能包（ClawHub CLI 的发布协议不兼容 SkillHub）
+export SKILLHUB_REGISTRY=http://your-skillhub-host:8080
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
+npx @astron-team/skillhub@latest publish ./my-skill
 ```
 
 ## Q: 如何配置 HTTPS？
diff --git a/docs/skillhub/guide/skill-publish.md b/docs/skillhub/guide/skill-publish.md
index 19233eaf..72249d60 100644
--- a/docs/skillhub/guide/skill-publish.md
+++ b/docs/skillhub/guide/skill-publish.md
@@ -57,16 +57,19 @@ SkillHub 提供了类似 npm 的发布体验，但增加了企业级的权限控
 2. **使用 CLI 发布（推荐）**
 
 ```bash
-# 配置注册中心
-export CLAWHUB_REGISTRY=http://localhost:8080
+# 配置 SkillHub 注册中心
+export SKILLHUB_REGISTRY=http://localhost:8080
+export SKILLHUB_TOKEN=YOUR_API_TOKEN
 
 # 发布到默认命名空间
-npx clawhub publish ./my-skill
+npx @astron-team/skillhub@latest publish ./my-skill
 
 # 发布到指定命名空间
-npx clawhub publish ./my-skill --namespace my-team
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
 ```
 
+> ClawHub CLI 的发布与同步协议与 SkillHub 不兼容。发布请使用上面的 SkillHub CLI。
+
 3. **使用 Web UI 发布**
 
 访问 `http://localhost:3000/dashboard/publish`，选择命名空间、上传 zip 文件、选择可见性后点击「发布」。
diff --git a/web/src/docs/skill.md b/web/src/docs/skill.md
index b8ed8bcf..4727508e 100644
--- a/web/src/docs/skill.md
+++ b/web/src/docs/skill.md
@@ -1,13 +1,13 @@
 ---
 name: skillhub-registry
-description: Use this when you need to search, inspect, install, or publish agent skills against a SkillHub registry. SkillHub is a skill registry with a ClawHub-compatible API layer, so prefer the `clawhub` CLI for registry operations instead of making raw HTTP calls.
+description: Use this when you need to search, inspect, install, or publish agent skills against a SkillHub registry. Use ClawHub for compatible read/install workflows and the first-party SkillHub CLI for publishing.
 ---
 
 # SkillHub Registry
 
 Use this skill when you need to work with a SkillHub registry: search skills, inspect metadata, install a package, or publish a new version.
 
-> Important: Prefer the `clawhub` CLI for registry workflows. SkillHub exposes a ClawHub-compatible API surface and a discovery endpoint at `/.well-known/clawhub.json`, so the CLI is the safest path for auth, resolution, and download behavior. Only fall back to raw HTTP when debugging the server itself.
+> Important: Use `clawhub` for search, inspection, and installation. Its publish protocol is not compatible with SkillHub, so use the first-party SkillHub CLI for publishing. Only fall back to raw HTTP when debugging the server itself.
 
 ## What SkillHub Is
 
@@ -111,13 +111,16 @@ npx clawhub install team-name--my-skill
 
 ### Publish
 
-Prepare a skill package directory, then publish it:
+ClawHub's upload-ticket protocol is not compatible with SkillHub. Publish with
+the first-party SkillHub CLI instead:
 
 ```bash
-npx clawhub publish ./my-skill
+export SKILLHUB_REGISTRY=https://skillhub.your-company.com
+export SKILLHUB_TOKEN=sk_your_api_token_here
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
 ```
 
-Publishing requires authentication and sufficient permissions in the target namespace.
+Publishing requires authentication and membership in the target namespace.
 
 ## Authentication And Visibility
 
diff --git a/web/src/docs/skill.md.template b/web/src/docs/skill.md.template
index 1d13200f..74e6a581 100644
--- a/web/src/docs/skill.md.template
+++ b/web/src/docs/skill.md.template
@@ -1,13 +1,13 @@
 ---
 name: skillhub-registry
-description: Use this when you need to search, inspect, install, or publish agent skills against a SkillHub registry. SkillHub is a skill registry with a ClawHub-compatible API layer, so prefer the `clawhub` CLI for registry operations instead of making raw HTTP calls.
+description: Use this when you need to search, inspect, install, or publish agent skills against a SkillHub registry. Use ClawHub for compatible read/install workflows and the first-party SkillHub CLI for publishing.
 ---
 
 # SkillHub Registry
 
 Use this skill when you need to work with a SkillHub registry: search skills, inspect metadata, install a package, or publish a new version.
 
-> Important: Prefer the `clawhub` CLI for registry workflows. SkillHub exposes a ClawHub-compatible API surface and a discovery endpoint at `/.well-known/clawhub.json`, so the CLI is the safest path for auth, resolution, and download behavior. Only fall back to raw HTTP when debugging the server itself.
+> Important: Use `clawhub` for search, inspection, and installation. Its publish protocol is not compatible with SkillHub, so use the first-party SkillHub CLI for publishing. Only fall back to raw HTTP when debugging the server itself.
 
 ## What SkillHub Is
 
@@ -111,13 +111,16 @@ npx clawhub install team-name--my-skill
 
 ### Publish
 
-Prepare a skill package directory, then publish it:
+ClawHub's upload-ticket protocol is not compatible with SkillHub. Publish with
+the first-party SkillHub CLI instead:
 
 ```bash
-npx clawhub publish ./my-skill
+export SKILLHUB_REGISTRY=${SKILLHUB_PUBLIC_BASE_URL}
+export SKILLHUB_TOKEN=sk_your_api_token_here
+npx @astron-team/skillhub@latest publish ./my-skill --namespace my-team
 ```
 
-Publishing requires authentication and sufficient permissions in the target namespace.
+Publishing requires authentication and membership in the target namespace.
 
 ## Authentication And Visibility