pack-skill

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：读取版本信息

按优先级读取版本号：

1. VERSION 文件（纯文本）
2. skill.json 的 version 字段
3. 都没有 → 报错

同时从 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>

脚本逻辑：

1. 扫描 Skill 根目录下全部文件
2. 排除下方黑名单中的路径/模式（排除模型实读自 pack.ps1，单一事实源）
3. 其余全部打入 zip
4. 产物命名：{BrandName}-Skill-v{version}.zip（BrandName 取自 skill.json displayName 品牌前缀）
5. 双包感知（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：验证产物

打包完成后检查：

1. 关键文件：zip 内必须含 SKILL.md
2. 包体大小：输出摘要供用户判断

排除清单（黑名单）

以下路径/模式始终排除：

类别	排除项
版本控制	.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"