SkillHub.cn 技能一键发布指南

> 适用对象：任何 Agent，拿到即可执行，无需查阅其他资料
>
> 目标平台：skillhub.cn
>
> 实战验证：deepseek-bridge（skillId=116922）、skill-sedimentation（skillId=116924）

⚠️ 核心原则：发布包与运行包必须分离

为什么必须分离？
1. skillhub.cn 是公开平台，API Key 一旦上传无法删除
2. 发布包只是模板，使用者安装后自行配置
3. 真实路径对他人无意义，不能写进发布包

铁律：Token 从 vault 运行时读取，绝不能写入发布包。

两种 CLI 的坑（Windows 必须看）

> ⚠️ Windows 必须走 WSL，不能用 npm 版本。 npm 版认证永远 401，这是导致发布失败的根因。

Token 来源

通过 credential-vault 读取 SkillHub Token：

1. Token 存在 D:\openclaw-data\.openclaw\workspace\credentials\SkillHub.json，字段 token
2. 运行时用脚本读取 vault JSON 文件，取 token 字段
3. 禁止硬编码 Token，禁止把 Token 写入任何发布包文件

当前账号：@user_310a65be（userId=557789）

完整发布流程（Windows + WSL 实战版）

第一步：安装 WSL 版 CLI（仅首次需执行）

curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only

安装完成后 CLI 路径：/home/huawei/.local/bin/skillhub（WSL 内）

第二步：在 SkillHub 网页创建 Token（如尚未创建或已过期）

1. 登录 https://skillhub.cn/dashboard/keys
2. 点「创建 API key」→ 命名（如 cli-v2）→ 创建
3. 立即复制 Token（只显示一次，错过只能重新创建！）
4. Token 格式：skh_xxx

第三步：WSL 内登录

wsl /home/huawei/.local/bin/skillhub login --key <你的Token>
# 成功输出：✓ Logged in as @user_310a65be (userId=557789)

> 注意：必须通过 wsl 前缀调用，不能直接在 Windows CMD/PowerShell 执行。
> Token 登录成功后存在 ~/.skillhub/credentials.json（WSL 内）。

第四步：整理发布包

D:\openclaw-data\workspace\skills\<slug>\
├── SKILL.md          # 必须：Frontmatter + 正文
├── <技能名>.py（或.cjs）# 核心代码（API Key 清空版）
└── README.md         # 可选

SKILL.md Frontmatter 模板：

---
slug: <slug>                    # 全网唯一，不能和已有技能冲突
displayName: <技能显示名>         # 对外展示名称
version: 1.0.0                  # 语义化版本
summary: <一句话描述>             # 摘要
license: MIT                     # 推荐 MIT
---

代码中 API Key 处理（Python）：

API_KEY = os.environ.get("API_KEY") or ""

代码中 API Key 处理（JavaScript）：

const API_KEY = process.env.API_KEY || "";

SKILL.md 环境变量表格写法：

| 变量 | 默认值 | 说明 |
|:---|:---|:---|
| `API_KEY` | （必填，无默认值） | 从 xxx 平台申请 |

真实路径处理：

# 错误（泄露真实路径）：
path = "D:\\ollama-intel\\models"

# 正确（占位符）：
path = os.environ.get("OLLAMA_MODEL_PATH") or "<真实运行路径>"

第五步：发布前自检（5 项）

• [ ] 代码中无硬编码 API Key（用 os.environ.get("KEY") or ""）
• [ ] SKILL.md 环境变量表格无默认值（或写"必填"）
• [ ] 真实路径全部替换为占位符（如 <真实路径>）
• [ ] SKILL.md 中没有真实 API Key 片段
• [ ] README.md 无真实凭证

第六步：执行发布

> ⚠️ 路径格式必须是 /mnt/d/...，不能用 Windows D:\ 格式。

wsl /home/huawei/.local/bin/skillhub publish "/mnt/d/openclaw-data/workspace/skills/<slug>" --changelog "首次发布 v1.0.0"

成功输出：

✓ Published: skillId=116924 status=None

注意：如果提示"版本已存在"，需要升级版本号后再发布：
1. 修改 SKILL.md 顶部 version: x.x.x 为新版本
2. 重新执行 publish 命令

第七步：验证

浏览器打开：https://skill.xfyun.cn/skills/<slug>

或 CLI 验证（需指定正确 registry）：

wsl /home/huawei/.local/bin/skillhub --index https://skill.xfyun.cn/api/v1/skills.json search <slug>

第八步：通知 main

sessions_send({
  sessionKey: "agent:main:main",
  message: "[技能发布完成]\n- 技能：<name>\n- 版本：x.x.x\n- skillhub.cn：https://skill.xfyun.cn/skills/<slug>"
});

常见错误处理

Token 管理

> 当前账号：@user_310a65be（userId=557789）
>
> Token 在 SkillHub 只显示一次，创建后立刻复制保存。

一句话总结

> Windows 发 SkillHub：装 WSL CLI → 网页建 Token → WSL 登录 → /mnt/d/... 路径发布。