SkillHub 打包器
把一个本地 skill 目录，变成能一次过审的 SkillHub 上传包。四步：体检 → 修复 → 打包 → 发布。
适用：用户说「打包这个 skill」「上架到 SkillHub」「发布 skill」「上传被拒了帮我看看」。
30 秒上手
脚本入口 <本 skill 目录>/scripts/skillhub_pack.py，纯标准库，任何 Python 3.9+ 可跑。
# 一条链：体检 + 自动补必填项 + 打包（最常用）
python scripts/skillhub_pack.py all <skill 目录> --slug <英文标识>
# 只看不改（安全，先跑这个）
python scripts/skillhub_pack.py check <skill 目录>
# 只打包，自定义输出路径
python scripts/skillhub_pack.py pack <skill 目录> -o dist/my-skill-1.0.0.zip
目录名是中文时必须带 --slug（中文没法可靠转成英文标识，脚本会明确报错让你指定，不会瞎猜）。
例如 --slug mc-one-stop-workshop、--slug novel-pipeline。
退出码：0 = 可发布；1 = 有 FAIL 不可发布。CI / 自动化可直接判断。
Agent 工作流
check一遍，把 FAIL 项按提示处理（能自动修的直接进第 2 步）。all --slug xxx：自动补slug/version/displayName/license/summary，中文name自动挪到displayName，CRLF 自动转 LF，写前备份SKILL.md.bak。- 看报告里的
产物:行拿到 zip 路径，用present_files交给用户。 - 发布走下面两条路之一；
description含尖括号这类语义问题必须人工改文案，脚本不会替你改写。
打包结构（实测结论）
平台分发的 skill 包一律是平铺结构 —— 下载官方已上架 skill 解包验证过：SKILL.md 直接位于压缩包根，同级只有作者自己的文件（外加平台注入的 _meta.json，上传包里不需要它）。
所以默认输出平铺包：
my-skill-1.0.0.zip
├── SKILL.md ← 必须在根，不能套在文件夹里
├── scripts/...
└── references/...
--wrapped 可生成「顶层目录 = slug」的包裹结构，用于给需要目录结构的 Agent 客户端安装；SkillHub 上传不要用它（脚本会 WARN 提醒）。
打包时自动排除：.git、__pycache__、node_modules、.venv、dist、build、*.pyc、*.bak、.DS_Store、_meta.json、.packignore 等；用 --no-exclude 关闭。
skill 根目录可放 .packignore（每行一条相对路径，目录以 / 结尾，# 开头是注释）来排除不方便上架的目录。
典型用法：工程模板里含 .gradle / .properties / .bat / .jar 时，把模板整目录排除，
改为带一个 xxx.pack.txt（ZIP+Base64 文本）归档 + 还原脚本 —— 见 references/upload-spec.md §2.3。
上架必查项
| 级别 | 项 | 规则 |
|---|---|---|
| 必填 | slug |
kebab-case（小写字母/数字，单词间单连字符），长度 2-128，全网唯一（被占用返回 409，建议带自己 handle） |
| 必填 | version |
合法 SemVer，如 1.0.0；更新时新版本号必须严格大于线上版本 |
| 必填 | displayName |
展示名，可以用中文 |
| 必填 | name |
本地加载器要求 hyphen-case，不能含中文/大写 —— 中文名放 displayName |
| 必填 | description |
Agent 靠它匹配触发场景；不能含 < > |
| 建议 | summary license tags homepage iconUrl |
不阻断，但影响卡片展示与检索 |
| 硬拦 | 文件类型 | 上传页有扩展名黑名单：.jar .zip .png .jpg .pdf .exe .class .wasm 等二进制，命中直接拒；前端只看最后一段、服务端看文件名所有分段，所以文本副本不能叫 xxx.jar.b64（详见 references/upload-spec.md §2.2） |
| 体积 | 单包 | ≤ 10 MiB、文件数 ≤ 200 |
路径里不能出现 .. 或 \（会被判「文件路径不安全」）。SKILL.md 匹配方式是剥掉公共顶层目录后做精确匹配，平铺与包裹结构都能过，但默认给平铺。
细节、证据与字段全表见 references/upload-spec.md；被拒案例见 references/faq.md。
发布（两条路）
# A. CLI（需新版 CLI；本机 2026.3.18 版本太旧，不支持 publish）
skillhub login --key "$SKILLHUB_KEY" --host https://api.skillhub.cn
skillhub publish <skill 目录> --host https://api.skillhub.cn --dry-run # 先预检
skillhub publish <skill 目录> --host https://api.skillhub.cn --changelog "首次发布"
B. 网页：https://skillhub.cn/dashboard/publish 上传 zip（拖拽后平台自动解析 frontmatter 预填表单）
CLI 安装/升级：curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
脚本的 publish 子命令会先探 CLI 能力，缺 publish 就直说升级，不会瞎跑。
文件清单
| 文件 | 用途 |
|---|---|
scripts/skillhub_pack.py |
全部逻辑：check / fix / pack / publish / all，--json 输出机器可读报告 |
references/upload-spec.md |
SkillHub 上架规范速查：字段表、zip 结构实测、CLI 命令、错误码、TRACE 维度 |
references/faq.md |
被拒症状 → 根因 → 正确做法（含本工具自身踩过的坑） |
references/文档瘦身.md |
SKILL.md 去重与精简手册：砍哪儿（只砍 SKILL.md）、编号契约、token 级 diff 校验、交叉引用同步、备份收尾 |
文档瘦身（可选，非打包流程）
用户说「精简这个 skill」「文件太长了」「优化 skill」，或上架前想让包体 / 上下文更小时，读 references/文档瘦身.md：核心是先砍 SKILL.md（它每次调用都进上下文，references 是按需读、不进上下文），保留规则编号与全部数字/禁令，改完跑三重校验（token 级 diff 查漏 + 交叉引用同步 + quick_validate.py）。该手册只给 Agent 执行，脚本不自动改 skill 正文。
维护边界
- 只读体检（
check）绝不改文件；fix只动SKILL.md的 frontmatter 与行尾，且写前备份。 - 不替你改写
description文案、不生成图标、不编造 handle，语义内容交给人或调用方。 - 不代做实名认证与 token 申请；无 token 时只给网页路径。
- 不修改 skill 正文内容，不递归处理多个 skill（一次一个目录）。
