SkillHub 技能发布
把本地 Agent Skill（含 SKILL.md 的目录）发布或更新到 SkillHub。
覆盖官方教程全流程：拿 key → 装 CLI → 登录 → 发布，发布被卡时一键定位原因。
快速上手：从零到发布成功
前提：已在 skillhub.cn 注册并完成实名认证（个人中心 → 实名认证，
未实名无法创建 key）。
① 拿 API key
浏览器打开 skillhub.cn/dashboard/keys →
「创建 API key」→ 立刻复制弹窗里的完整 Token（skh_...，只显示这一次；丢了就删掉重建一把）。
② 安装并登录 CLI
# macOS / Linux / WSL（官方安装命令）
curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
export PATH="$HOME/.local/bin:$PATH" # 让终端能找到 skillhub
skillhub --version # 验证安装
# 登录（把 skh_xxx 换成你的 key）
skillhub login --key skh_xxx --host https://api.skillhub.cn
skillhub auth whoami # 输出 userId / handle / role 即成功
Windows 用户注意：curl | bash 安装的是 bash 壳，在原生 Windows（cmd / PowerShell）
里 skillhub 命令通常不在 PATH。装完后直接用 Python 调 CLI 即可，功能完全一致：
python "%USERPROFILE%\.skillhub\skills_store_cli.py" --version
python "%USERPROFILE%\.skillhub\skills_store_cli.py" login --key skh_xxx --host https://api.skillhub.cn
（下文 skillhub ... 在 Windows 上都可替换为
python "%USERPROFILE%\.skillhub\skills_store_cli.py" ...。）
③ 准备 SKILL.md
技能根目录的 SKILL.md 头部 frontmatter，必填三项：
---
slug: my-skill # 必填。小写字母数字与连字符（kebab-case），2-128 字符，全网唯一
displayName: 我的技能 # 必填。对外展示名
version: 1.0.0 # 必填。SemVer，如 1.0.0
---
建议补上（不作为发布阻断）：summary / description / tags / license / homepage。
④ 预检 → 发布
skillhub publish <技能目录> --dry-run # 本地预检，几秒出结果，不发请求
skillhub publish <技能目录> --changelog "首次发布"
看到 ✓ Dry-run passed: <slug>@1.0.0 表示校验通过；看到
✓ Published: skillId=xxxxx status=pending_review 即发布成功，进入审核。
⑤ 确认结果
发布成功不代表已上架——status=pending_review 是审核中。等审核通过后详情页才可见。
发布被卡时用一键排错（见下文）。
首次发布 vs 更新已有版本
| 首次发布 | 更新已有技能 | |
|---|---|---|
| 版本号 | 建议 1.0.0 |
必须大于线上最新，同号重发报 409 |
| slug | 全网唯一，先确认没被占用 | 不变（变了就是另一个技能） |
| 图标 | 随发布一起绑定 | 换图标也必须升版本号（图标只在发布时绑定） |
| 名称/图标生效 | 审核通过后可见 | 审核通过后才更新 latestVersion / displayName |
| 常见失败 | slug 撞车、frontmatter 缺字段 | 409、图标没换上、搜不到以为失败 |
| 先跑什么 | publish_doctor.py <slug> |
publish_doctor.py <slug> --dir <目录> |
> 最容易误判：发布成功后立刻去搜，搜不到、名字也没变——这是审核中。
> 判断发布是否成功看回执（ok / versionId / skillId），不要看公开页。
错误速查表
报错关键词 → 一句话解法。一句话不够再跑 publish_doctor.py，详见 FAQ。
| 报错 / 现象 | 一句话解法 |
|---|---|
command not found: skillhub |
macOS/Linux source ~/.zshrc；Windows 用 Python 直调（见快速上手②） |
401 invalid api key |
key 失效，去 /dashboard/keys 重建后重新 login --key |
403 请先完成实名认证 |
浏览器完成实名认证（人脸核身） |
409 VERSION_EXISTS |
同版本号重发——升版本号 |
409 slug 已被占用 |
换 slug（建议带 handle 前缀） |
429 请求过于频繁 |
平台限频，等约 1 分钟重试 |
不允许的文件类型: _icon.png |
安装元数据混入包里——升级本技能到 2.0.0+（已自动排除） |
undefined@1.0.0 |
SKILL.md 是 CRLF，转 LF |
| 详情页搜不到 / 名字没变 | 审核中；看回执 ok/versionId，不看公开页 |
| 图标没生效 | iconAuditStatus:null=没绑上；pending=审核中；同版本换不了图标 |
| 被判「可疑 / 恶意」 | 跑 publish_doctor.py <slug> 看报告，按整改建议改后升版本重发 |
包里混进 logs/、__pycache__ |
发布前清理；publish_doctor.py --dir 体检可查 |
发布被卡？一键排错
python scripts/publish_doctor.py <slug> --dir <技能目录>
一条命令完成：
- 拉取线上状态：
displayName/latestVersion/ 图标是否绑定 - 自动下载并解析双引擎安全报告（keen / sanbu），提取「检出行为（含文件与行号）」
和「平台整改建议」，直接给出行动清单——不用人工翻文档 - 本地包体检：CRLF 行尾、
__pycache__/logs残留、frontmatter 四要素、
脚本VERSION与 frontmatter 一致性、文档与脚本的命令行参数双向比对
加 --json 输出结构化结果。只读，不上传任何内容。
FAQ（实测踩过的坑）
Q：skillhub: command not found？
A：先 source ~/.zshrc（或重开终端）；仍不行用完整路径 ~/.local/bin/skillhub --version。
Windows 原生环境见上文「Windows 用户注意」，直接用 Python 调 CLI。
Q：401 invalid api key？
A：key 被撤销或失效。回 /dashboard/keys 重建一把，重新 login --key。
Q：403 请先完成实名认证？
A：回浏览器完成实名认证（人脸核身）再发布。
Q：409 冲突？
A：两种：① 同 slug 同版本重发 → 升版本号；② slug 被其他用户占用 → 换 slug
（建议带你的 handle 作前缀，如 yourhandle-my-skill）。
Q：429 请求过于频繁？
A：平台限频，等约 1 分钟重试。
Q：发布成功但详情页「未找到」/ 搜不到 / 名字没变？
A：审核中。status=pending_review 过审后自动可见；displayName / latestVersion /
图标也在过审后才更新。判断发布是否成功看回执，不看公开页。
Q：图标传了但没生效？
A：官方 CLI 不会上传图标，不带 iconUrl 会用默认占位图。要自定义图标用
scripts/publish_with_icon.py --icon <1:1 PNG>；注意 iconAuditStatus: null 说明
图标没绑上，pending 说明在审核；同版本号换不了图标，必须升版本重发。
Q：Windows 上官方 CLI 装不上？
A：install.sh 是给 bash 环境的；Windows 原生环境改用 Python 直调（见上文），
或使用 WSL。装完后 CLI 在 %USERPROFILE%\.skillhub\skills_store_cli.py。
Q：被安全引擎判「可疑 / 恶意」怎么办？
A：跑 publish_doctor.py <slug>，它会给出具体检出行为和平台整改建议。实测两条最有效：
① 敏感行为（如读凭据、扫描进程）改为需用户显式确认的可选步骤，默认不执行；
② 文档安全边界与实际行为逐条对齐——文档宣称与实现不符几乎必被点名。
工具参考
| 脚本 | 用途 |
|---|---|
scripts/publish_with_icon.py |
推荐。带图标发布：--icon <1:1 PNG> 上传并绑定图标，--icon-url <url> 复用已上传图标；也支持 --version / --changelog / --dry-run / --json / --token / --host / --cli |
scripts/publish_skill.py |
轻量发布（不带图标）：--version / --changelog / --dry-run / --json / --allow-crlf |
scripts/publish_doctor.py |
一键排错：<slug> --dir <本地目录> [--json] |
三个脚本都会自动把 SKILL.md 归一为 LF、排除 .git / __pycache__ / *.pyc 等杂项，
并拒绝打包缺失 slug / version / displayName 的技能。
安全审核红线（实测）
平台安全引擎按文件打 恶意 / 可疑 / benign，报告里会给出具体文件与行号。
恶意 会直接卡住版本。以下为本机实测结论：
会判 恶意：
- 读取本机其它应用的登录态 / 凭据文件取账号字段（只是"读"也算）
- 解密其它应用的静态加密信封还原明文凭据
ReadProcessMemory/VirtualQueryEx/OpenProcess读其它进程内存
（哪怕只用于定位解密密钥）- 任何"自动导出他人应用凭据"
会判 可疑：
- 读取磁盘上的明文 token（即使有账号一致性校验）
- 首次运行隐式注册开机自启 / 计划任务（应改为用户显式执行设置命令才注册）
- 文档宣称与实现不符（引擎逐条比对，几乎必被点名）
过审写法：
- 凭据只由用户本人提供，脚本不代为获取
- 文档安全边界与实现逐条对齐，宁可少写不要多写
- 否定式声明（如"不扫描进程内存"）有助过审，但必须为真
- 整改后必须升版本号重发，同版本号改不了
发布前质量自检（两份 Playbook）
发布前按需跑两道自检，均只读、不发包：
| 场景 | 用哪份 |
|---|---|
| 准备上传 WorkBuddy 应用市场（skill zip） | references/market-audit-checklist.md —— 结构/frontmatter/YAML 实跑校验/密钥与危险调用扫描/合规检查/重打包，输出阻断项/建议项/已通过三档结论 |
| 想知道技能质量短板在哪、怎么修（SkillHub 或任意平台） | references/trace-eval-playbook.md —— TRACE 五维自检清单 + 常见扣分点修复手法速查 + 实测整改案例 |
整改后记住两条铁律：升版本号、changelog 直接列变更要点（不写评测话术）。
参考
- 官方教程：skillhub.cn/tutorials（「通过 CLI 和 Agent 发布 Skill」章节）
- 官方 Agent 发布规范：skillhub.cn/ai/release.md
- API key 管理：skillhub.cn/dashboard/keys
- 深入排错：references/TROUBLESHOOTING.md
