docs(compat): clarify supported ClawHub workflows

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>

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
 
+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 does not restore a private Registry saved by `login`. Set `CLAWHUB_REGISTRY` in each shell session or pass `--registry` explicitly.
+- Canonical slugs use `--` between namespace and skill. If either component itself contains `--`, the coordinate is ambiguous; use the first-party SkillHub CLI with its explicit `--namespace` option.
+
 ## 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)
+# ClawHub does not restore this value from its 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,18 @@ 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
+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.
+- The first-party CLI uses a separate namespace option and is not affected by canonical-slug delimiter ambiguity.
 
 ## API Endpoints
 
@@ -140,7 +140,7 @@ SkillHub compatibility layer provides the following endpoints:
 | `/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/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 +186,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. A namespace or skill slug containing `--` can map to the same string as another coordinate; use the first-party SkillHub CLI for such coordinates.
+
 ## Configuration Examples
 
 ### ClawHub CLI Environment Variables
@@ -248,7 +250,11 @@ 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?
+
+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:
 
 - Publishing to global namespace (`@global`) requires `SUPER_ADMIN` permission
 - Publishing to team namespace requires OWNER or ADMIN role in that namespace

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 不读取登录配置中保存的私有 Registry。每个终端会话都应设置 `CLAWHUB_REGISTRY`，或在命令中显式传入 `--registry`。
+- canonical slug 使用 `--` 分隔 namespace 与 skill。坐标任一部分自身包含 `--` 时无法无歧义解析，请改用第一方 SkillHub CLI 的显式 `--namespace` 参数。
+
 ## 快速开始
 
 ### 1. 配置 Registry 地址
 
-在 OpenClaw 配置文件中设置 SkillHub 注册中心地址：
+为当前终端会话设置 SkillHub 注册中心地址：
 
 ```bash
-# 通过环境变量配置（临时）
+# ClawHub CLI 不会从 login 配置中恢复该地址
 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,18 @@ 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
+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 对应权限。
+- 第一方 CLI 使用独立 namespace 参数，不受 canonical slug 分隔符歧义影响。
 
 ## API 端点说明
 
@@ -140,7 +140,7 @@ SkillHub 兼容层提供以下端点：
 | `/api/v1/skills/{slug}` | GET | 获取技能详情 | 可选 |
 | `/api/v1/skills/{slug}/star` | POST | 收藏技能 | 必需 |
 | `/api/v1/skills/{slug}/unstar` | DELETE | 取消收藏 | 必需 |
-| `/api/v1/publish` | POST | 发布技能 | 必需 |
+| `/api/v1/publish` | POST | 旧版兼容发布端点；ClawHub CLI `0.23.3` 不使用 | 必需 |
 
 说明：
 - 兼容层对外继续使用 “latest” 语义，但这里严格指向“最新已发布版本”
@@ -186,6 +186,8 @@ SkillHub 内部使用 `@{namespace}/{skill}` 格式，但兼容层会自动转
 
 OpenClaw CLI 使用 canonical slug 格式，SkillHub 会自动处理转换。
 
+canonical 格式没有转义规则。namespace 或 skill slug 自身包含 `--` 时可能映射到相同字符串，必须改用第一方 SkillHub CLI。
+
 ## 配置示例
 
 ### ClawHub CLI 环境变量配置
@@ -248,7 +250,11 @@ curl https://skillhub.your-company.com/api/v1/whoami \
 npx clawhub search ""
 ```
 
-### Q: 发布技能时提示权限不足？
+### Q: 使用 ClawHub CLI 发布为什么失败？
+
+ClawHub CLI `0.23.3` 使用的上传票据协议不在 SkillHub 兼容范围内。该错误不代表 API Token 已撤销；请改用第一方 SkillHub CLI。
+
+如果第一方 CLI 提示权限不足：
 
 - 发布到全局命名空间（`@global`）需要 `SUPER_ADMIN` 权限
 - 发布到团队命名空间需要是该命名空间的 OWNER 或 ADMIN