SkillHub 上架助手
帮开发者把一个本地 Skill 从零发布到腾讯 SkillHub（skillhub.cn），并在发布前后做规范检查与故障排查。
适用于免费技能（CLI 发布）和付费技能 Pay Skill（网页后台发布）两条通道。
何时使用
用户说以下任意一种意图时启用本技能：
- "把我的技能发布到 SkillHub" / "上架 Skill" / "发布 Skill"
- "帮我写 SKILL.md" / "SKILL.md 格式对不对"
- "skillhub publish 报错" / "发布失败" / "slug 被占用"
- "我想做个 Pay Skill / 付费技能怎么上架"
- "发布后详情页看不到" / "审核多久"
执行流程
严格按顺序执行，不要跳步。
第 1 步：确认前置条件
逐项检查，缺哪项就引导用户补哪项（不要替用户跳过）：
| 前置项 | 检查方式 | 缺失时怎么办 |
|---|---|---|
| SkillHub 账号 + 实名认证 | 网页登录 skillhub.cn → 个人中心看实名状态 | 手机号验证码注册 → 人脸核身。未实名无法建 Token、无法发布 |
| API Token（skh_ 开头） | 个人中心 → API keys（/dashboard/keys） | 点"创建 API key"，完整 Token 只显示一次，立即保存 |
| SkillHub CLI | skillhub --version |
curl -fsSL https://skillhub.cn/install/install.sh \| bash -s -- --cli-only |
| CLI 已登录 | skillhub auth whoami |
skillhub login --key <Token> --host https://api.skillhub.cn |
> Windows 用户需先装 WSL。装完若报 command not found: skillhub，执行
> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc。
第 2 步：校验 SKILL.md
Skill 根目录下必须有 SKILL.md，头部 frontmatter 必填字段：
---
slug: your-unique-slug # 全网唯一，小写字母/数字/连字符
displayName: 技能展示名称
version: 1.0.0 # 语义化版本
summary: 一句话简介
license: MIT
---
校验规则：
slug必须全网唯一。建议带上作者 handle 前后缀避免冲突，如pdf-tools-wanxiang。- 正文用 Markdown，写清：何时使用、执行流程、异常处理。
- 正文中不要写死 prompt 注入语句或诱导 Agent 忽略用户指令的内容。
可直接运行本技能自带的预检脚本做静态检查：
python3 scripts/check_skill.py <skill目录路径>
脚本会检查：SKILL.md 是否存在、frontmatter 必填字段、slug 命名合法性、包内是否混入密钥文件。
第 3 步：本地预检（不发起网络请求）
skillhub publish <skill目录> --dry-run
看到 ✓ Dry-run passed: <slug>@<version> 才算通过。
报 Error: SKILL.md 缺少 ... 就回第 2 步补字段。
第 4 步：正式发布（免费技能）
skillhub publish <skill目录> --changelog "首次发布"
成功标志：✓ Published: skillId=xxxxx status=pending_review
迭代更新时保持 slug 不变，改 version 即可：
skillhub publish <skill目录> --changelog "修复 xxx，新增 yyy"
第 5 步：付费技能走网页后台（重要差异）
CLI 不能发布付费技能——publish 的 payload 里没有计费字段，走 CLI 发出去的一定是免费技能。
Pay Skill 的通道是：
- 登录 skillhub.cn 后台 → 上传 skill 的 zip 包
- 手填 slug / 显示名 / 图标
- 分类选
pay-skill（付费技能） - 计费模式选「按调用量计费」→ 填单价（元/次）
- 提交审核
Pay Skill 的三条硬约束：
- 核心能力必须在服务端执行，源文件脱离后端无法独立使用（否则用户拿到包就能白嫖）
- 服务端用 402 协议：未付费请求返回
402 + WeixinPay-Required触发授权，用户付款后携带payment_code重试，服务端验付后履约 - 三处单价必须完全一致：服务端 SkillCatalog 配置 / 支付平台登记单价 / 上架表单标价。不一致会导致买家付款被拒
收款通道二选一：
| 通道 | 资质要求 | 说明 |
|---|---|---|
| 微信支付 | 需微信支付商户号，个体户/企业可办，不支持无照小微商户 | SkillHub 企业认证 → 绑定商户号 → 拿 x402 密钥 |
| 支付宝 AI 付 | 个人实名即可 | 支付宝开放平台签约「AI 按量付费」，RSA2 密钥，私钥仅存服务端 |
平台暂不收技术服务费，实时结算到绑定账户，无需手动提现。
第 6 步：上架后自测与推广
- 详情页显示"未找到"通常是仍在审核中，去「个人中心 → 我的 Skill」看实时状态
- 审核通过后分享到技术社区、视频号等渠道做冷启动
- 在技能结尾留一句反馈引导话术，持续迭代版本
异常处理
| 现象 | 原因 | 处理 |
|---|---|---|
command not found: skillhub |
PATH 未生效 | source ~/.zshrc；或用完整路径 ~/.local/bin/skillhub |
401 invalid api key |
Token 失效/被撤 | 去 API keys 重新创建，再 skillhub login --key <新Token> |
403 请先完成实名认证 |
未做人脸核身 | 浏览器完成实名后重试 |
409 slug 已被占用 |
重名 | 改 slug，加 handle 前后缀 |
429 请求过于频繁 |
触发限频 | 等约 1 分钟后重试 |
| 发布成功但详情页 404 | 审核中 | 去我的 Skill 看状态，审核通过自动可见 |
| CLI 无撤回/删除命令 | 设计如此 | 发错了只能去网页后台处理，发布前先确认通道 |
status 查 slug 返回 404 |
无法区分"审核中"和"已驳回" | 让用户看后台技能列表定性 |
上架前核验清单
发布前逐项过一遍：
- [ ] SKILL.md frontmatter 五个必填字段齐全
- [ ] slug 全网唯一且命名合法
- [ ]
skillhub publish --dry-run通过 - [ ] 包内无密钥、无 .env、无支付账号字段
- [ ] 免费技能走 CLI；付费技能走网页后台（通道别选错）
- [ ] 若是 Pay Skill：三处单价一致 + 402 全链路已用 0.01 元真实交易验证
参考链接
- SkillHub 官网：https://skillhub.cn/
- 使用指南（含 CLI 全流程）：https://skillhub.cn/tutorials
- SkillPay 接入页：https://skillhub.cn/skillpay
- 微信支付 AI 专属卡接入准备：https://pay.weixin.qq.com/doc/v3/merchant/4035576711
