scriptoriumadmin/skillhub
1
0
Fork 0
mirror of https://github.com/iflytek/skillhub.git synced 2026-09-06 08:15:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #806 from iflytek/codex/docs/issue-795-clawhub-compat

Browse source 
docs(compat): clarify supported ClawHub workflows
This commit is contained in:
XiaoSeS 2026-09-03 13:48:33 +08:00 • committed by GitHub
commit 47f3d33c65
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 130 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
README.md
View file

@ -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)**

17
README_zh.md
View file

@ -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)**

63
docs/openclaw-integration-en.md
View file

@ -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?

63
docs/openclaw-integration.md
View file

@ -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 版本？

6
docs/skillhub/en/faq.md
View file

@ -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?

11
docs/skillhub/en/guide/skill-publish.md
View file

@ -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".

6
docs/skillhub/faq.md
View file

@ -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？

11
docs/skillhub/guide/skill-publish.md
View file

@ -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 文件、选择可见性后点击「发布」。

13
web/src/docs/skill.md
View file

@ -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

13
web/src/docs/skill.md.template
View file

@ -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