Skill Packager · 技能整包化安装与管理

把「一堆技能」装成一个「包」:一个目录搞定安装、更新、卸载、迁移。

何时使用

• 用户从 GitHub 仓库(或本地目录)拿到一个包含多个 Agent Skills 的合集,希望统一安装和管理
• 用户想减少技能目录的平铺混乱,用「一个父目录 + git」管理一组技能
• 已装过平铺副本,想整理成整包

核心原理(必须先理解)

WorkBuddy 递归扫描技能目录:只要 ~/.workbuddy/skills/<任意深度>/SKILL.md 存在,该技能就会被识别
(实测证据:本机 nature-review-studio/skill/SKILL.md 位于二级目录,仍被正常加载)。

因此整包结构 ~/.workbuddy/skills/<包名>/<skill-name>/SKILL.md 是完全可用的——技能功能不变,
而管理动作(更新/卸载/迁移)收敛到一个目录。

但有两个必须处理的边界(实测踩坑):
1. 整包根必须有自己的 SKILL.md,否则 WorkBuddy 无法把整包识别为可安装的技能;
2. 部分小包的 SKILL.md 位于更深层级(如 <skill>/skill/SKILL.md、<skill>/docs/SKILL.md),
单靠递归识别可能漏掉 → 必须依赖整包根的父级索引 SKILL.md 兜底。

打包脚本会自动:① 把 skills/ 下所有子目录(无论内部 SKILL.md 在几层)提升到整包根;
② 在整包根生成父级索引 SKILL.md(名字=包名),内含子技能索引表(实际相对路径)
与 AI 使用指引——AI 按索引用文件读取工具直接打开子技能 SKILL.md 并严格遵循执行,
不依赖子技能是否被单独注册。

整包结构

~/.workbuddy/skills/
├── <包名>/                    ← 整包(推荐保留 .git 以便 git pull 更新)
│   ├── SKILL.md               ← ★ 父级索引 SKILL.md(安装入口,自动生成)
│   ├── <skill-1>/SKILL.md     ← 子技能(可能位于更深层级,如 <skill>/skill/SKILL.md)
│   ├── <skill-2>/SKILL.md
│   ├── 技能汇总表.html        ← 中文汇总表(搜索/分类筛选,自动生成)
│   ├── 技能汇总表.json        ← 汇总元数据(含待填中文字段)
│   ├── README.md / docs/      ← 仓库自带文件(可保留)
│   └── .git/                  ← 若来源是 git 仓库,保留之
├── <其他独立技能>/            ← 未打包技能,保持原样,绝不动
└── _bm_skillid_migration.json ← WorkBuddy 标记文件,勿动

工作流(8 步)

第 0 步:确认来源与目标

• 来源:git clone URL 或本地目录
• 目标包名:短横线命名,如 scientific-agent-skills;若包名会与包内某个子技能同名
  (如 ponytail 仓库内含 ponytail 技能),加 -skills 后缀区分(先例:ponytail-skills、
  nature-skills),避免整包根索引与子技能注册重名互相混淆

第 1 步:克隆/定位来源

git clone --depth 1 <URL> <临时目录>
# 或直接使用本地目录(注意:本地目录若无 .git,后续无法整包更新)
# 临时目录必须放在【工作区内】(如 <workspace>/.pack-tmp/),不要用系统 /tmp——见常见坑

第 2 步:安全审计(必做,不能跳)

两条线并行:

a. 官方报告(若仓库有):
- 查看 SECURITY.md、docs/security-report.md、docs/security-triage.md
- 区分「真实问题」与「扫描器系统性误报」(如 API-key 认证、model.eval() 常被误判)

b. 本地静态扫描(无条件执行,只读):

# 危险调用:应全部为零
grep -rnoE "(^|[^a-zA-Z_\.])(eval|exec)\(" --include="*.py" skills/ | head
grep -rnoE "os\.(system|popen)" --include="*.py" skills/ | head
grep -rnoE "shell\s*=\s*True" --include="*.py" skills/ | head
# 硬编码凭证(应只有环境变量名,无真实密钥)
grep -rnoiE "(api[_-]?key|secret|token|password)\s*[=:]\s*['\"][A-Za-z0-9_\-]{16,}['\"]" --include="*.py" skills/ | head
# 网络外联目标(应均为技能声称调用的服务)
grep -rhoE "https?://[a-zA-Z0-9\.\-]+" --include="*.py" skills/ | sort | uniq -c | sort -rn
# 反向shell/挖矿/持久化/prompt注入
grep -rnoiE "(reverse[_ ]?shell|/dev/tcp/|cryptominer|ignore (previous|prior|above))" skills/ | head

审计结论分三档:✅ 通过 / ⚠️ 有需注意项(记录后仍可装) / 🔴 有风险(拒绝安装并汇报)。

第 3 步:目录重组(关键一步)

目标:把 skills/ 下的所有子目录(无论其中 SKILL.md 在几层)提升到整包根,
使技能目录扁平化。

若技能原本在仓库 skills/ 子目录,且有 .git:

cd <仓库目录>
git mv skills/* ./        # 提升所有子目录(含深层),git 记录为重命名
git add -A && git commit -m "chore: flatten skills/ to repo root for recursive discovery"

无 .git 的本地目录:直接 mv skills/* ./ 即可。

第 4 步:迁移到技能目录

mv <仓库目录> ~/.workbuddy/skills/<包名>

第 5 步:清理顶层冲突副本(慎!)

若用户技能目录顶层已有同名平铺技能(通常是此前平铺安装的副本):

1. 先 MD5 校验一致性(内容一致才可处理,避免误删用户数据):

# 逐目录对比:顶层 <name> vs 整包 <name> 的每个文件 MD5 是否完全一致

2. 处理方式:优先「移动」到备份目录,而非「删除」:
   - 原因:WorkBuddy 的 safe-delete 机制会拦截单轮批量删除(>50 目标需命令级确认,用
   AskUserQuestion 确认也无效),而 shutil.move 不触发拦截
   - 移动后告知用户备份位置,由用户决定是否彻底删除
3. 绝不误动与本次打包无关的独立技能(判断标准:不在打包来源清单内,如用户已有的
   nature-* 等),即使它们与打包技能名字相似

第 6 步:验证

# 1) 数量:整包内 SKILL.md 总数(递归,含深层)== 来源技能数
# 2) frontmatter:每个 SKILL.md 都有 ^name: 和 ^description:
# 3) git:整包目录内 git status 干净
# 4) 结构:所有技能目录已在整包根(深层 SKILL.md 保留其原相对路径)

第 7 步:生成安装入口与汇总表(自动 + AI 填充)

打包脚本在整包根自动生成两个文件:

a. 父级索引 SKILL.md(安装入口,必生成)
- 递归扫描整包内所有 SKILL.md(含深层),生成索引表(实际相对路径 + 名称 + 用途简介)
- frontmatter 的 name = 包名,description 指引 AI:按索引用文件读取工具打开子技能
SKILL.md 并严格遵循执行;子技能未注册也不影响使用
- 作用:① 整包根有 SKILL.md → WorkBuddy 可识别安装;② 深层子技能有兜底入口
- license 字段自动识别:从包内 LICENSE 文件推断(APACHE/MIT/GPL/BSD/MPL),
识别不出才回退 MIT——避免把 Apache-2.0 的上游仓库标成 MIT(实测踩坑)
- 中文优先:若同目录 技能汇总表.json 已被 AI 填好 zh_name/zh_desc/category,
build_pack_index 会自动改产按分类分组的中文索引(共享/支持包排最后),
否则回退单一英文表;填完中文后重跑 --repair <包目录> 即可刷新为中文索引
- 入库判定:--repair 以 frontmatter 块内的 skill-author: SkillPackager 标记
判断「本工具生成」,检测窗口是整个 frontmatter 而非前 800 字符——子技能很多时
description 极长,800 字符窗口会把标记挤出而误判跳过(实测踩坑)

b. 技能汇总表.json(中文由 AI 填充)
1. 读取 <包名>/技能汇总表.json
2. 为每个技能填写 zh_name(中文名)、zh_desc(1-2 句中文说明,基于 desc 翻译提炼)、
category(领域分类,如「生信·基因组学」「机器学习·AI」,同类技能归一类便于筛选;
分类建议合并到 8-12 组,过碎会让索引分组失去意义)
3. 运行渲染命令生成 技能汇总表.html(深色主题、实时搜索、分类筛选):
bash python scripts/pack_skills.py --render <包名>/技能汇总表.json
> HTML 是纯生成物:重跑本命令即按最新模板刷新(含历史 bug 修复),
> 例如旧版表头错位的 HTML 重渲染即自动修复;JSON 中已填中文不受影响。
4. 渲染时 zh_name/zh_desc 为空的技能会自动回退显示英文原文,方便检查漏填项
5. 填完中文后重跑 --repair <包目录>,让父级索引同步升级为中文分组版

第 8 步:收尾汇报

• 告知用户:重启/新会话后技能才会出现在技能列表(当前会话是启动时快照)
• 管理方式:更新 = cd <包名> && git pull;卸载 = 删除整个包目录;迁移 = 复制整个目录
• 汇总表 HTML 已随包存放在整包根目录
• 若仓库 README 含作者商业推广链接(如代充/赞助广告),提醒用户只进人读文档、
  不进任何 SKILL.md 与可执行代码,技能触发时不会进入 AI 上下文

常见坑与对策(实测踩坑记录)

脚本用法

本技能附带 scripts/pack_skills.py,封装了第 1~7 步的可自动化部分(已在本机端到端验证):

# 打包模式(自动提取技能元数据到 <包名>/技能汇总表.json)
python scripts/pack_skills.py \
  --source "https://github.com/xxx/skill-collection.git" \
  --name my-skill-pack \
  [--skills-dir "C:/Users/Miracle R/.workbuddy/skills"] \
  [--no-scan]          # 跳过安全静态扫描(不推荐)

# 渲染模式(AI 填充中文后,生成 <包名>/技能汇总表.html)
python scripts/pack_skills.py --render <包名>/技能汇总表.json [--out 自定义路径.html]

# 修复模式(为已有整包补全父级索引 SKILL.md,如旧包缺安装入口)
python scripts/pack_skills.py --repair <包目录> [--name 包名] [--index-mode auto|flat|category]

脚本行为:
- 零删除:安装用复制,冲突副本只检测(MD5 一致性)并提示,删除动作一律交给用户——规避平台 safe-delete 钩子
- 重组后自动 git commit,整包 git 状态保持干净
- flatten 提升 skills/ 下所有子目录(含深层 SKILL.md 结构)
- 打包完成自动生成:父级索引 SKILL.md(安装入口,递归索引全部子技能)+ 汇总元数据 JSON
- --repair 可为旧包/已有整包补全父级索引;汇总表 JSON 已存在时保留(不覆盖已填中文)
- --index-mode(大包必用):
- auto(默认):子技能 > 120 个且 80% 以上位于「分类/<技能>/SKILL.md」两层结构时,
自动生成两级分类索引
- category:强制两级索引。根 SKILL.md 只列分类(分类目录 / 中文分类名 / 技能数 /
一句话简介 / 该分类 README.md 入口),AI 先开分类 README 看技能表,再开具体
SKILL.md —— 上下文按需加载。适用于 100+ 技能的大包
(实测:bioSkills 562 技能,两级索引根文件 17 KB;若平铺成单行表会到 100 KB+)
- flat:强制单一全量表格(几十个技能的小包)
- 中文填充后 --render 生成可搜索 HTML 汇总表
- description 提取支持引号单行/跨行、YAML 块标量(>-/|)、缩进续行等多种 frontmatter 写法
- 输出逐步日志与最终验证摘要(技能数、frontmatter、git 状态)

调试与修改指南(用户)

• 本技能是独立文件夹,可直接编辑 SKILL.md 和 scripts/pack_skills.py
• 想调整目标目录:改 --skills-dir 参数;想调整保留清单:改脚本内 KEEP 常量
• 测试:用一个小型 git 仓库(如 2-3 个技能的合集)跑一遍,观察日志输出
• 修改后无需重新安装,WorkBuddy 每次会话重新读取 SKILL.md

边界

• 本技能只做文件系统级打包与静态审计,不执行技能内含代码
• 不负责第三方技能依赖(Python 包/API Key)的安装
• 个别技能的许可证可能与仓库主许可证不同,打包前提示用户确认