SkillHub 发布踩坑清单

本清单全部来自 2026-10-31 一次真实的首次发布，不是推测。每条都带原始报错和验证方式，你可以自己复现。

何时用

• 第一次往 SkillHub 发布 Skill
• 发布「成功」了但别人搜不到 / 装不了
• 想确认一条发布链路是不是真的通了，而不是「我点了发布」

坑 1：dry-run 通过 ≠ 能发布

现象

按文档写了 slug / displayName / version / summary / license 五个字段：

skillhub publish ./my-skill --dry-run
# ✓ Dry-run passed: my-skill@1.0.0

本地预检通过。但真发时失败：

skillhub publish ./my-skill
# Error: 请求失败 (400): SKILL.md 的 frontmatter 缺少 name、description 字段，
# 请在文件头部的 --- 之间补充对应字段 (code=SKILL_MD_FRONTMATTER_MISSING)

原因

本地 dry-run 校验器比服务端宽松。它不检查 name 和 description，服务端才检查。

避坑

发布前本地先自查这两个字段存在：

grep -cE '^(name|description):' SKILL.md   # 输出 2 才算齐

完整必填字段（实测服务端要求 7 个）

slug: my-skill              # 全局唯一，发布后难改
name: my-skill              # 服务端必查，dry-run 不查
displayName: 我的技能
description: 一句话说清干什么、什么时候用   # 服务端必查
version: 1.0.0
summary: 同 description 的短版
license: MIT

坑 2：发布成功后有同步窗口，立刻下载会 404

现象

skillhub publish ./my-skill
# ✓ Published: skillId=<你的skillId> status=None

注意 status=None —— 既不是 published 也不是 pending，它是空值，不能当成功标志。

立刻去装：

skillhub install my-skill --namespace <你的handle>
# info: resolved community skill (@handle/my-skill), internal slug=my-skill
# Downloading: https://api.skillhub.cn/api/v1/download?slug=my-skill&namespace=handle
# Error: Download failed: HTTP 404

原因

平台侧同步有延迟。本次实测约 10 分钟后才可下载（平台策略可能变化，以你实测为准）。

避坑

• 发布后别急着验，等 5–10 分钟
• 别把「还没同步」误判成「发布失败」，否则会重复发布或怀疑 slug 冲突

坑 3：怎么确认「真的通过了」——验真四步

按顺序跑，四步全过才算通。只过前两步＝只证明「能看到」，不证明「能用」。

第一步：查详情与安全审核

export SKILLHUB_TOKEN=...   # 先设置，别把真实 token 写进 shell history
curl -s "https://api.skillhub.cn/api/v1/skills/<slug>?namespace=<handle>" \
  -H "Authorization: Bearer $SKILLHUB_TOKEN"

看两处：

{
  "securityReports": {
    "keen":  {"status": "benign", "statusText": "安全，无风险"},
    "sanbu": {"status": "benign", "statusText": "安全，无风险"}
  },
  "stats": {"versions": 1}
}

benign ＝ 审核通过。

第二步：搜索可发现

skillhub search <slug>

或 API：https://api.skillhub.cn/api/v1/search?q=<slug>，在自己的结果里按 namespace 过滤。

第三步：安装可下载

skillhub install <slug> --namespace <handle> --dir /tmp/verify

第四步：内容一致（关键，最容易漏）

比对本地源与平台装回来的 md5。不一致＝传的不是你要传的。

md5 -q ./my-skill/SKILL.md
md5 -q /tmp/verify/@<handle>/<slug>/SKILL.md

两行必须相同。

补充：skillhub verify 找不到文件怎么办

verify 默认去 <当前目录>/skills/<slug> 找已安装目录，如果你装到了别处（比如 /tmp），会报：

Error: 未找到已安装的 skill 目录: .../skills/<slug>

两个解法：装到默认目录，或用 --zip 指定打包路径。

时间线参考（一次真实发布）

从发布到可安装，约 10 分钟。 中间那段什么都别做，等。

许可

MIT