SkillHub 上架助手·发布排错
把任意一个本地 skill 目录，走完「预检 → 发布 → 校验」全流程，交付到腾讯 SkillHub 社区。
本 skill 的价值不在"告诉你点哪个按钮"，而在把踩过的坑变成可执行的预检。
执行原则
- 预检先行。 发任何网络请求前先跑
check_skill_md.py；不要靠重试绕过预检失败，预检不过就先修SKILL.md。 - 凭据零留存。 token 由用户自行生成与输入；不要索取、不要转述、不要写进任何文件、不要写进交付报告。
- 分步留证据。 每一步的原始返回如实转述，尤其是
skillId、reviewStatus与错误码；不要把失败笼统说成「校验失败」，要给出具体字段名和修法。 - 不代做认证与创作。 实名/企业认证、SkillPay 收款配置在网页端完成；不要替用户提交认证材料，也不要代写 skill 内容。
- 审核状态如实报。
pending是审核中的正常状态；不要把它说成发布失败，更不要反复重发——重复提交只会产生多个版本。
何时使用
CRITICAL: 只要用户提出「把这个 skill 上架 / 发布到 SkillHub / 打包成技能 / 确认能不能过审」，就必须使用本 skill，即使看起来可以用别的方式解决。
- 用户说「把这个 skill 上架」「发布到 SkillHub」「上传到技能市场」「打包成技能」。
- 用户已有 skill 目录，想确认它能不能过审（而不是提交后被 400 拒掉）。
- 用户问 skill 怎么变现、怎么接 SkillPay 按次收费。
何时不该使用
| ✅ 使用 | ❌ 不用（改用什么） |
|---|---|
| 已有 skill 目录，走发布流程 | 从零创作 skill 内容（属内容创作任务） |
| front matter / 结构合规预检 | 优化命名与 description 的选词策略（先定策略再发布） |
| 客户端 + 服务端已知坑排错 | 从 GitHub 搬运第三方 skill（涉及许可证判断，另议） |
查询 skillId 与审核状态 |
申诉审核结果、联系平台人工（走官方渠道） |
| 说明 SkillPay 接入路径 | 定价与收款配置本身（在 <https://skillhub.cn/skillpay> 网页端完成） |
易混淆场景
| 用户说的 | 实际意图 | 正确路由 |
|---|---|---|
| 「帮我上架这个 skill」 | 要端到端发布 | 按第 1~5 步走：预检 → CLI → 登录 → 发布 → 校验 |
| 「预检过了是不是就能发」 | 担心服务端再拒 | 明确：--dry-run 只查 3 个字段，服务端还查 name / description |
| 「搜不到我的包」 | 以为发布失败 | 查 reviewStatus，pending 属正常，不要重发 |
| 「能不能收费」 | 关心变现 | 说明免费 skill 只引流，按次收费需接 SkillPay 并在网页端配置 |
| 「token 发你了，帮我登录」 | 想省事 | 提醒 token 已出现在对话中、用完轮换，不转存不写入文件 |
执行流程
第 1 步：定位 skill 目录并预检（必做）
python3 scripts/check_skill_md.py <skill目录>
这一步在发任何网络请求之前拦掉最常见的一类失败。
它会校验 front matter 的必需字段、slug 合法性、SemVer 版本号，并识别折行块标量这种解析器不支持的写法。
必须在预检通过后再往下走。 预检不通过就直接修 SKILL.md，不要试图靠重试绕过。
第 2 步：确保 CLI 可用
command -v skillhub && skillhub --version
未安装则运行随包脚本（已处理 Git Bash 下的已知安装故障）：
bash scripts/install_cli.sh
export PATH="$HOME/.local/bin:$PATH"
第 3 步：登录
skillhub login --key skh_xxxxxxxx
skillhub auth whoami
- token 由用户在 <https://skillhub.cn/> 自行生成，不要索取、不要转述、不要写入任何文件。
- 每次涉及用户凭据的操作，都提醒用户「token 已出现在对话中，用完请轮换」。
- 发布需要账号完成实名认证（个人）或企业认证（企业）。
第 4 步：本地预检 → 正式发布
skillhub publish <skill目录> --dry-run # 客户端预检，无网络请求
skillhub publish <skill目录> --changelog "版本说明" --json
⚠️ --dry-run 通过 ≠ 能发布。 客户端只查 3 个字段，服务端还会查 name / description。
详见 references/pitfalls.md。
第 5 步：确认与校验
skillhub verify <skill目录> # 本机文件与平台签名是否一致
skillhub search <displayName> # 审核通过后应能召回
返回结果先看三件事：ok 是否为 true、skillId、以及 reviewStatus / contentAuditStatus / securityScanStatus 是否为 pending。
pending 是正常的——审核通过前搜不到，不要反复重发，重复提交只会产生多个版本。
输出约定
- 每一步的原始返回要如实转述，尤其是
skillId、reviewStatus、错误码。 - 报错时给出具体字段名和修法，不要只说"校验失败"。
- 交付三段：做了什么 → 当前状态（含等待中的审核）→ 用户待办。
- 不要把 token、API key 等凭据写进报告或任何文件。
变现（SkillPay）
免费 skill 只能引流，按次收费要额外接 SkillPay：
- 本 CLI 没有定价/支付相关子命令，收款配置在 <https://skillhub.cn/skillpay> 网页端完成。
- 准入：企业需企业认证 + 绑定微信支付商户号；个人需实名认证并开通收款能力。
- 计费：单次价格由服务方自定，平台暂不收取技术服务费，按所选渠道实时结算。
- 改造：已有 skill 可平滑升级为 Pay Skill，需配置支付确认链路（返回支付触发标识），支付确认留在任务流内、不跳转站外。
免责声明
本 skill 只负责把你的目录按平台要求送审，不保证审核通过，也不构成对 skill 内容合规性、
许可证适用性或变现收益的任何承诺；审核结论以平台为准，实名/企业认证与收款资质需你本人完成。
依赖
Python 3.8+（标准库）；curl + tar 用于安装 CLI。无需第三方包。
更多细节见 references/pitfalls.md。
