何时使用
- 打包：用户要求打包技能、创建发布包、生成 zip、准备分发时
- 配置备份目录：首次打包或用户想修改备份位置时
核心规则
- 先确认源路径：执行前向用户展示源技能路径，确认后再调用脚本
- 运行时配置不进发布包：技能在
_meta.json中声明excludeFiles，打包时自动排除，不影响新用户 - 走脚本，不手动：所有机械操作（读取 frontmatter、写 _meta.json、创建 zip、验证）全部由
scripts/pack.mjs完成 - 输出到约定目录：默认
MySKILLs/（可配置），禁止输出到源技能目录内部
脚本涵盖的 6 步流程：
| 步骤 | 操作 |
|---|---|
| ① | 读取 SKILL.md frontmatter slug + version |
| ② | 更新 _meta.json（保留扩展字段，更新 slug/version/publishedAt） |
| ③ | 清理 {backupDir}/{slug}-*.zip 旧包 |
| ④ | 创建 zip |
| ⑤ | 逐项验证（_meta.json slug/version 一致、SKILL.md slug 一致、文件列表完整等） |
| ⑥ | 输出结果或报错退出 |
数据存储
打包输出到 {backupDir}/{slug}-{version}.zip，同时更新技能目录的 _meta.json。
备份目录优先级：
1. 脚本第 2 个参数（显式指定）
2. 本技能目录下 packager.json 的 backupDir 字段（项目约定）
3. 默认 MySKILLs/（fallback）
配置存储
技能目录下的 packager.json 是运行时配置，打包时自动排除，不进发布包：
{
"backupDir": "MySKILLs"
}
- 不存在 → 首次打包时 AI 询问用户并创建
- 存在 → 直接读取
- 用户可随时修改此文件或要求 AI 修改
脚本辅助
node .opencode/skills/opencode-skill-packager/scripts/pack.mjs <skill-dir> [output-dir]
省略 [output-dir] 则从 packager.json 读取。AI 负责确认源路径，脚本执行具体操作。
工作流程
首次打包
- 用户给出源技能路径 → AI 读取
packager.json - 不存在 → 询问用户「打包备份放哪个目录？」→ 创建
packager.json - 存在 → 直接读取
backupDir - 执行
scripts/pack.mjs→ 汇报结果
后续打包
- 用户给出源技能路径 → 读
packager.json - Pre-flight：读取 SKILL.md frontmatter 的 description，对照当前技能功能做一致性检查。 如果功能迭代后 description 未同步（如新增类型/命令但描述仍写旧数量），先更新 description 再继续
- 执行
scripts/pack.mjs→ 汇报结果
常见陷阱
| 陷阱 | 原因 | 解决 |
|---|---|---|
| cd && Compress-Archive | PowerShell 不支持 && |
使用 scripts/pack.mjs 自动处理 |
| version 不匹配 | SKILL.md vs _meta.json 不一致 | 以 SKILL.md frontmatter 为准 |
| 输出目录选错 | AI 把第 1 个参数（源路径）当输出路径 | 第 1 个参数是源技能目录；默认输出到 {backupDir}/ |
| 跨项目存放备份 | 发起打包的项目是 A，却输出到项目 B 的技能目录下 | 打包输出属于发起项目 |
| zip 含多余临时文件 | collectFiles 未排除 .tmp-vld、backups/、*.zip |
已修复 |
| 运行时配置进发布包 | packager.json 等本地配置文件被打包进 zip，新用户拿到别人的配置 |
pack.mjs 在 collectFiles 和 Compress-Archive 中均排除运行时配置 |
反馈
在 opencode-skill-suite 提交 Issue 或 PR。
