| name | pack-skill |
| description | 将任意 Qoder Skill 项目打包为分发包 zip。自动检测项目结构，包含全部项目文件，仅排除开发者/构建产物。当用户要求打包 skill、生成分发包、创建发布 zip 时使用。 |
Pack Skill — 通用 Skill 分发包打包
触发场景
用户说"打包 skill"、"生成分发包"、"创建发布 zip"、"导出 skill"时调用。
设计原则
包含全部，排除已知——不预设任何 Skill 特有的目录结构。
任何符合 Qoder Skill 规范的项目（有 SKILL.md）都能打包。
执行流程
Step 1：定位 Skill 根目录
检查当前工作区：
- 仓库根下存在
ChronoPM-Project/SKILL.md → Skill 根目录 = ChronoPM-Project/（v3.1.1 CR-G）
- 当前目录存在
SKILL.md → 当前目录即为 Skill 根目录
- 否则报错退出
Step 2：读取版本信息
按优先级读取版本号：
VERSION 文件（纯文本）skill.json 的 version 字段- 都没有 → 报错
同时从 skill.json 读取 name 字段作为包名（缺省用 skill）。
Step 3：执行打包
运行本 skill 目录下的打包脚本：
本机主路径（Python）：
python tools/pack-skill/scripts/pack.py --skill-root <path>
跨平台参考实现（PowerShell，执行策略受限时不可用）：
powershell -ExecutionPolicy Bypass -File ~/.qoder/skills/pack-skill/scripts/pack.ps1 -SkillRoot <path>
脚本逻辑：
- 扫描 Skill 根目录下全部文件
- 排除下方黑名单中的路径/模式（排除模型实读自 pack.ps1，单一事实源）
- 其余全部打入 zip
- 产物命名：
{BrandName}-Skill-v{version}.zip（BrandName 取自 skill.json displayName 品牌前缀）
- 双包感知（v3.0.0 G-3 / v3.1.1 CR-G）：
--skill-root ChronoPM-Project 时自动打包兄弟目录 ChronoPM-Portfolio/ 为第二 zip；zip 默认写仓库根。governance/migrations/（仅当前 upgrade）与 governance/contracts/skill-contract.md 例外放行入包。
建议先 DryRun 预览：
python tools/pack-skill/scripts/pack.py --skill-root <path> --dry-run
Step 4：验证产物
打包完成后检查：
- 关键文件：zip 内必须含
SKILL.md
- 包体大小：输出摘要供用户判断
排除清单（黑名单）
以下路径/模式始终排除：
| 类别 | 排除项 |
|---|
| 版本控制 | .git/、.gitignore |
| IDE/编辑器 | .idea/、.vscode/、.qoder/ |
| 构建缓存 | __pycache__/、*.pyc、*.pyo |
| OS 元数据 | .DS_Store、Thumbs.db |
| 打包产物 | *.zip、*.tar.gz |
| 开发者治理 | governance/（例外放行 governance/contracts/skill-contract.md 与 governance/migrations/ 当前 upgrade） |
| 测试 | tests/（如存在） |
| 架构文档 | SKILL_BLUEPRINT.md（开发者侧架构审查文档） |
| 治理规则 | references/16-skill-governance-rules.md（Skill 自身变更治理规则，开发者侧） |
| 模块图 | SKILL_MODULE_MAP.md（给人看的链路图，不进发行包） |
| 伴生包 | ChronoPM-Portfolio/（仓库根打 Project 包时排除；伴生包自动单独打第二个 zip，v3.0.0 G-3） |
缺 tests/、SKILL_BLUEPRINT.md、references/16-skill-governance-rules.md、SKILL_MODULE_MAP.md 不是 bug——这是产品化裁剪。打包脚本会打印「有意排除」表。
source-split-skill/ 必须进包（能力目录，不是第二个 Skill）。包内除根 SKILL.md 外禁止再有 SKILL.md。不要把该目录列入 excludeDirs。
governance/ 默认整目录排除，但 governance/contracts/skill-contract.md（核心契约）例外放行——因为 references/ 中 7 个运行时规则文件引用了它第 5 条。
SKILL_BLUEPRINT.md 和 references/16-skill-governance-rules.md 是开发者侧架构/治理文档，PM 使用者运行时不需要。
tests/ 是"如存在则排除"，不是所有 Skill 都有。
如果某个 Skill 项目有自定义的开发者目录需要排除，用户可在打包前告知 AI，AI 通过脚本 -Exclude 参数传入。
脚本参数
| 参数 | 说明 |
|---|
-SkillRoot <path> | Skill 项目根目录（必填） |
-OutputDir <path> | 输出目录（默认同 SkillRoot） |
-DryRun | 仅预览不打包 |
-Exclude <string[]> | 额外排除的目录名（如 "docs","examples"） |
注意事项
- 脚本不假设任何 Skill 特有的目录结构（如 references/、assets/ 等）
- 新增的 Skill 标准目录不需要修改脚本——因为默认全部包含
- 产物命名：
{BrandName}-Skill-v{version}.zip（BrandName 取自 skill.json displayName 品牌前缀，无 displayName 时脚本拒绝打包）
安装
本 skill 应安装到个人 skill 目录 ~/.qoder/skills/pack-skill/。
安装命令（PowerShell）：
Copy-Item -Recurse -Force "<本项目路径>/tools/pack-skill" "$env:USERPROFILE/.qoder/skills/pack-skill"
