SkillHub 发布与操作规范

> Goal: 帮助用户使用 API Key 登录腾讯 SkillHub 平台，完成 skill 的云端存储、在线操作、发布、更新与共享。所有操作通过 skillhub CLI（腾讯官方版）执行。

When to Use

仅当用户要求操作腾讯 SkillHub（skillhub.cn）平台的 skill 时触发：
- "登录 SkillHub"、"用 API key 发布 skill"
- "把某个 skill 发布/更新到 SkillHub"
- "在 SkillHub 上存储/管理/共享 skill"
- "上传 skill 到云端"、"发布 skill 到社区"

When NOT to Use（重要）

以下场景不要使用本 skill：
- 用户提到的是其他 SkillHub 实现（如科大讯飞 skill.xfyun.cn 的 npm @astron-team/skillhub 版）——那是不同平台，命令和 token 不通用。
- 用户只是本地整理 skill 文件、不需要发布到云端。
- 用户要操作的是 GitHub/工蜂/CNB 等其他代码托管平台。

关键前置条件（硬性，缺一不可）

1. 账号已注册：手机号登录 skillhub.cn 即可自动注册。
2. 已完成实名认证：未实名认证无法创建 API Token，也无法发布 skill。实名认证在 skillhub.cn 网页端「个人中心 → 实名认证」完成（人脸核身）。这是最常见的失败原因，遇到 403 请先完成实名认证 即代表未实名。
3. 已创建 API Key（Token）：在 skillhub.cn 网页端「个人中心 → API keys」（直链 /dashboard/keys）创建，格式为 skh_xxx。Token 只显示一次，需立即保存。

操作流程

第 1 步：安装腾讯版 SkillHub CLI

> ⚠️ 必须用腾讯官方安装脚本，不要用 npm 的 @astron-team/skillhub（那是科大讯飞版，连的是 skill.xfyun.cn，token 不通用）。

# 安装 CLI（不带预置 skill 集合）
curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only

# 让终端能找到 skillhub 命令（首次使用）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
skillhub --version

看到版本号（如 skillhub 2026.8.5）即安装成功。

第 2 步：使用 API Key 登录

skillhub login \
  --key <你完整的 skh_xxx Token> \
  --host https://api.skillhub.cn

• 成功：✓ Logged in as @你的handle (userId=xxx)
• 验证身份：
  bash skillhub auth whoami
  输出 userId / handle / role 三行即登录成功。

第 3 步：准备 Skill 文件（存储结构）

Skill 是一个目录，根目录必须有 SKILL.md，frontmatter 至少包含：

---
slug: <全网唯一标识>          # 必填，kebab-case，建议带个人 handle 避免冲突
displayName: <展示名称>       # 必填
version: 1.0.0              # 必填，合法 SemVer
summary: <一句话简介>         # 必填
license: MIT                # 建议
tags: [标签1, 标签2]          # 可选
description: <详细描述>       # 可选
---

可选子目录：scripts/、references/、docs/。

第 4 步：发布前本地预检（dry-run）

skillhub publish <skill目录路径> --dry-run

• 成功：✓ Dry-run passed: <slug>@<version>
• 失败（如 Error: SKILL.md 缺少 slug）：补齐 frontmatter 后重试。

第 5 步：正式发布到 SkillHub

skillhub publish <skill目录路径> --changelog "首次发布"

• 成功：✓ Published: skillId=xxxxx status=pending_review，进入审核流程。
• 审核通过后，其他智能体可通过 skillhub search/install 安装，或网页端访问详情页。

第 6 步：更新 Skill

更新与首次发布一致：保持 slug 不变，按需修改 version/displayName/summary 等字段，再发布：

skillhub publish <skill目录路径> --changelog "修复xxx，新增yyy"

第 7 步：共享给其他智能体

发布到 SkillHub 后，其他智能体可用以下方式安装共享的 skill：

skillhub login --key <token> --host https://api.skillhub.cn   # 先登录
skillhub install <slug>                                       # 安装
skillhub search <关键词>                                      # 搜索
skillhub list                                                 # 查看本地已安装

安全要求（强制）

1. 发布包与运行包分离：API Key 一律用 os.environ.get("KEY") or ""，不得写真实默认值；真实路径用 <占位符>。
2. 严禁把 token/密钥写入 skill 包：发布前用 grep 扫描 token|secret|api_key|password|/root/|/home/ 等敏感模式。
3. Token 保管：Token 只在 CLI 登录时使用，不写入 skill 文件或仓库。

常见错误与排查

参考

• 详细发布流程与案例：见 references/publish-guide.md
• 官方教程：https://skillhub.cn/tutorials#publish-via-cli