SkillHub 发布器（skillhub-publisher）
把"本地 Skill 发布到 SkillHub"这件事变成一条命令，而不是每次查教程。
何时使用
- 你写/改完一个 Skill，想发到 SkillHub 社区。
- 想先本地预检 frontmatter 是否合规（dry-run）。
- 遇到发布报错（缺字段、409 slug 冲突、网络问题）想快速定位。
不用于
- 非 SkillHub 平台（如其它市场、GitHub 直传）——流程不同。
- 代你做实名认证 / 人脸核身——那必须本人操作。
前置条件（一次性）
- 注册 + 实名认证：去 skillhub.cn，手机号 + 人脸核身。否则建不了 Token。
- 创建 API Token：个人中心 → API keys → 创建，复制完整
skh_xxx（只显示一次，妥善保存）。 - 本地 CLI 已预装：本机已存在
C:\Users\陈林\.skillhub\skills_store_cli.py（v2026.6.27）。若缺失，按官网安装指引装。
核心流程（固化步骤）
- 确认 frontmatter 合规：Skill 的 SKILL.md 头部需含 SkillHub 字段（见
references/skillhub-frontmatter.md）。WorkBuddy 字段（name/description/trigger_terms）可共存，已验证 dry-run 通过。 - dry-run 预检（不发请求，纯本地校验）：
MSYS_NO_PATHCONV=1 <managed-python> <cli.py> publish <skill目录> --token skh_xxx --dry-run - 正式发布：把
--dry-run换成--changelog "说明"。 - 查审核状态：个人中心 → 我的 Skill，待安全审核通过后详情页可见。
关键坑位（实测）
- Git Bash 路径 bug：
skillhub包装脚本会把路径拼成c:\c\...找不到脚本。
✅ 正确姿势：直接调 Python 脚本skills_store_cli.py+ 前缀MSYS_NO_PATHCONV=1，路径用C:/Users/...形式。 - 沙箱网络：
curl在沙箱内 DNS 失败会误导你以为"无网络"；但skillhubCLI 走 Python 网络栈能正常连 api.skillhub.cn，发布可在沙箱内跑通。 - Token 不持久：
publish --token是内联，不会写登录态；auth whoami显示"未登录"属正常，发布已用该 Token 成功。 - 409 slug 冲突：slug 被别人占了，在 SKILL.md 把
slug加你的 handle 前缀（如chenlin-universal-repair-loop）重发。 - 566 / "fail to fetch"（发布失败，最坑）：多为服务端内容扫描器对某文件内容处理崩溃（脚本里内嵌代码尤其危险），不是服务端宕机、也不是你断网。
✅ 别先怪服务端：先做"极简 SKILL.md + 全新独特 slug"对照实验，再逐文件二分定位。完整诊断法、触发源清单、规避写法、决策树见references/troubleshooting-566.md。
随附脚本（推荐用法）
本 Skill 目录内 publish.sh 已封装上述全流程：
# 预检（默认，不动任何东西）
SKILLHUB_TOKEN=skh_xxx bash publish.sh <skill目录>
# 正式发布
SKILLHUB_TOKEN=skh_xxx bash publish.sh <skill目录> --publish "v1.2.0：xxx"
- 默认 dry-run，必须显式
--publish才真发（防误发）。 - Token 从环境变量或
--token读，文件里不留密钥。 - 直接调
skills_store_cli.py+MSYS_NO_PATHCONV=1，规避路径坑。
首次发布 vs 版本更新（细分指南）
两种场景命令一样，差别在 frontmatter 与 changelog 纪律：
首次发布
1. SKILL.md 头部确认 SkillHub 字段齐全：slug（全站唯一，建议加你的 handle 前缀防占）、displayName、version: 1.0.0、summary、license。
2. publish.sh <dir> 预检 → publish.sh <dir> --publish "v1.0.0：首次发布"。
3. 去个人中心等安全审核，通过后详情页可见、才有评测。
版本更新（已发布过的同 slug）
1. 升 version:（如 1.1.0 → 1.2.0）——同 slug 再发即更新原 listing，不新建。
2. 先取回上轮评测 JSON 留存，按 references/eval-feedback-loop.md 改短板。
3. changelog 写清"针对哪些评测短板改了什么"，便于对比提升。
4. publish.sh <dir> --publish "v1.2.0：针对评测短板 X/Y 优化"。
5. 对比新旧评测的"升/降/平 + 唯一下降项"，不凭记忆判断。
> 真实对照见 references/cases.md：buddy-bug-fixer 靠此闭环 4.36→4.59；本 Skill 自身靠此啃下 566 发成 4.5/优秀。
评测反馈闭环（发布后持续优化）
Skill 发布并通过审核后，SkillHub 会给出 TRACE 五维评测（T/R/A/C/E）。本闭环把"取评测 → 分析 → 优化 → 重发"固化为可复用流程：
- 取回最新评测（CLI 直连，存为
<slug>_eval_latest.json）：
bash MSYS_NO_PATHCONV=1 <python> <cli.py> skill evaluation <slug> --json > <slug>_eval_latest.json
评测结构：evaluation.dimensions.<维度>.<items>.<子项>.score；维度顶层 score 为 None（由子项算）。 - 读短板：逐项看 score，标注 <4.0 的子项（如
reliability/stability、convention/antiPatternFaq）。 - 映射成改动：按
references/eval-feedback-loop.md的 T/R/A/C/E → 优化动作映射表，把每个短板翻译成具体修改
（例：R.stability→修复后加语法校验；C.antiPatternFaq→补 FAQ 章节；E.usability→默认安全模式不改原文件…）。 - 改完重发（同 slug 即更新原 listing，不新建）：
bash SKILLHUB_TOKEN=skh_xxx bash publish.sh <skill目录> --publish "vX.Y.Z：针对评测短板…" - 对比提升（可选）：保留上轮 JSON，用脚本或人工比对"升/降/平 + 唯一下降项"，不要凭记忆判断。
- 维度→优化动作映射表、反模式清单见
references/eval-feedback-loop.md。 - 本地增强：本仓库根目录的
fetch_eval.sh（未随 SkillHub 发布包分发，因其内嵌 Python 会触发 SkillHub 服务端内容扫描器的格式串解析 bug → 566）可在本机一键完成"取评测 + 解析短板 + 对比旧评测"。需用时从本地副本取用即可。 - 纪律：每次重发前保留上一次评测 JSON，下次才能精确看提升。
什么情况用哪个命令（决策表）
| 你想做的事 | 用这个 |
|---|---|
| 只想本地检查 frontmatter 合规、不发请求 | publish.sh <dir>（默认 dry-run） |
| 正式发布 / 首次上传社区 | publish.sh <dir> --publish "vX.Y.Z：说明" |
| 只看当前登录身份 | auth whoami（仅对 login 持久态有效） |
| 怀疑 Skill 结构有问题 | verify <dir>（CLI 自带校验，supplementary） |
| 发布后取回评测 | skill evaluation <slug> --json（见反馈闭环） |
| 更新已发布的 Skill | 同 slug 再发一次 + 升 version（见下节） |
可用命令速查
publish <dir> --dry-run：本地预检，不发请求。publish <dir> --token skh_xxx --changelog "..."：正式发布。skill evaluation <slug> --json：取回评测（落盘用> file.json）。auth whoami：查看当前登录身份（仅对login持久态有效）。verify <dir>：校验 Skill 结构（若有疑问时 supplementary 用）。
参考文件
references/skillhub-frontmatter.md：SkillHub 必需字段详解 + 最小 frontmatter 模板 + WorkBuddy/SkillHub 双字段共存示例。references/eval-feedback-loop.md：评测反馈闭环方法论 + T/R/A/C/E 维度→优化动作映射表 + 反模式清单。references/faq.md：高频踩坑问答（409 slug 冲突、566/fail to fetch、requests 缺失、Token 不持久等）。references/cases.md：真实发布案例 Before/After（含本 Skill 啃 566 的全过程）。references/troubleshooting-566.md：566 / "fail to fetch" 完整诊断手册——症状/误判/两类根因/十几分钟二分定位法/触发源清单/修复策略/发布前预防清单/决策树。遇发布失败必看。
