企业官网建设流程全解析

如何把技能打包成zip加SHA-256？Garden Skills pack-skill.mjs全解析

【免费下载链接】garden-skillsConardLi's open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址: https://gitcode.com/GitHub_Trending/we/garden-skills

在 Garden Skills 这个开源 Agent 技能仓库中，发布流程的核心是 pack-skill.mjs：一条命令，就能把skills/目录下的任意技能打包成规范的zip 发布包，并自动生成配套的SHA-256 校验文件，保证用户下载后可以验证完整性。本文将用零代码门槛的方式，带你完整读懂这个打包脚本的每一步。

一、先搞懂：一个技能是怎么"住"在仓库里的

Garden Skills 采用统一的技能目录结构，每个技能都是一个独立文件夹，例如 skills/web-design-engineer/，里面至少包含两样东西：

• SKILL.md：技能的说明书（带 YAML 头信息，声明name和description）
• manifest.json：技能的"身份证"，记录 name、version、category、compat 等字段

打包脚本就是围绕这些约定工作的——它读取 manifest 里的版本号，决定产出的 zip 叫什么名字。

二、打包三步走：最常用的 3 条命令 🚀

打包入口文件是 scripts/release/pack-skill.mjs，仓库在 package.json 中已经预置了快捷脚本，三种玩法覆盖 99% 的场景：

跑完以后，你得到的产物固定在dist/release/下，每个技能都是"三件套"：

1. <技能名>-<版本>.zip—— 技能发布包
2. <技能名>-<版本>.zip.sha256—— SHA-256 校验文件
3. index.json—— 本次构建的汇总清单

三、打包背后发生了什么？6 步流程全解析

脚本内部是一条严谨的流水线，任何一步出问题都会立刻停下并报错。

1️⃣ 双重校验：manifest + 目录结构

打包前先"体检"。校验逻辑集中在共享库 lib/skills.mjs 中，检查内容包括：

• manifest.json 是否包含必填字段（name / version / description / category / compat）
• 版本号是否符合SemVer规范（如1.2.0）
• 技能名是否为小写连字符格式，且与文件夹名一致
• SKILL.md 的 YAML 头信息中name是否与文件夹名匹配

任何一条不通过，打包直接失败——这是"坏包"流出仓库前的第一道闸。

2️⃣ 版本漂移检查：防止"标签与版本打架"

如果你通过--version指定了版本号，而它与 manifest 中写的版本不一致，脚本会抛出Version drift错误，提示你先去修改skills/<技能名>/manifest.json的 version 字段。先改清单、再打包，这是本仓库铁律，确保 zip 文件名、git tag、manifest 三者永远一致。

3️⃣ 干净打包：自动排除"脏"文件

脚本调用系统zip命令，并按 EXCLUDE 排除清单 自动剔除不该发布的内容：node_modules、.DS_Store、Thumbs.db、*.log、.idea、.vscode等。

还有一个细节：zip 的顶层目录固定是<技能名>/，意味着用户解压后可以直接把整个文件夹丢进.claude/skills/或.agents/skills/，无需手动整理路径。

4️⃣ SHA-256 摘要：为 zip 盖上"防伪章" 🔐

打包完成后，脚本用流式读取方式计算 zip 的 SHA-256 值，并写入旁边的.sha256文件，格式是标准的 sha256sum 文本（摘要值 + 文件名）。

这有什么用？用户下载后执行sha256sum -c <文件>.zip.sha256一条命令，就能确认"你下载到的字节和官方发布的完全一致"，任何传输损坏或篡改都会校验失败。

5️⃣ 5 MB 软门槛：体积超标只提醒、不拦截

如果 zip 超过 5 MB，脚本会打印 WARNING，建议你精简捆绑的资源文件。注意这是"软"门槛——它只警告不失败，给你留出手动权衡的空间。

6️⃣ 生成 index.json：机器可读的构建清单

全部打包完成后，脚本在输出目录写入index.json，记录构建时间戳（builtAt）以及每个产物的名称、版本、文件名、SHA-256 值和字节数。这份清单是后续 CI 流程和 README 下载链接同步（见下一节）的数据来源。

四、放在更大的发布链条里看 🧩

pack-skill.mjs 只是"打包工人"，仓库用一组脚本搭起完整流水线，全部位于 scripts/release/ 目录：

典型节奏是：维护者跑npm run release触发 cut-release 打 tag → 远端 CI 执行 pack-skill 构建 zip 与校验文件 → update-readme 把 README 的下载区块指向新版本。一条命令启动，全程无人工干预。

五、新手常见疑问 FAQ

Q：为什么不用 npm 库压缩，而是调用系统zip命令？为了可移植性和尽量稳定的输出：zip -X会省略额外文件属性，让同内容在不同机器上打包出的结果更接近一致，SHA-256 因此更可预期。

Q：zip 解压出来是散文件还是一个目录？始终是"一个顶层目录 + 全部内容"，目录名就是技能名，解压后整目录拷贝即可用。

Q：遇到Validation failed报错怎么办？先运行npm run list（即 list-skills.mjs）查看是哪个字段不合规，按提示修正 manifest 或 SKILL.md 后再打包。

六、总结

Garden Skills 的 pack-skill.mjs 把"打包"这件容易踩坑的事变成了一条确定性流水线：先校验、后压缩、再哈希、末汇总。它产出的 zip + SHA-256 + index.json 三件套，让用户既能一键安装技能，又能一行命令验证完整性——这正是开源发布工具该有的样子。

【免费下载链接】garden-skillsConardLi's open-source Skills collection, featuring web design, knowledge retrieval, image generation, and more.项目地址: https://gitcode.com/GitHub_Trending/we/garden-skills