Skill Bundle - Skill 打包管理

管理和打包多个 skill，支持清单生成、依赖验证、安装、更新、卸载及版本兼容检查。

skill-bundle

Skill 打包管理 — 借鉴 Claude Plugins Official 的 marketplace.json 集中式目录模式，实现 skill 集合的打包、验证、安装和版本管理。

概述

Claude Plugins Official 将所有插件元数据集中在 marketplace.json 中。本 skill 用 bundle-manifest.json 管理 skill 集合，支持打包分发和版本控制。

bundle-manifest.json 格式

json

{
  "name": "my-bundle",
  "version": "1.0.0",
  "description": "Bundle description",
  "author": "author-name",
  "license": "MIT",
  "skills": [
    {
      "name": "skill-a",
      "version": "1.0.0",
      "path": "skills/skill-a",
      "description": "Skill A 功能说明",
      "dependencies": []
    },
    {
      "name": "skill-b",
      "version": "2.1.0",
      "path": "skills/skill-b",
      "description": "Skill B 功能说明",
      "dependencies": ["skill-a"]
    }
  ],
  "dependencies": {
    "runtime": "python>=3.8",
    "platform": ["windows", "linux", "darwin"]
  },
  "metadata": {
    "created_at": "2026-06-26T22:00:00Z",
    "updated_at": "2026-06-26T22:00:00Z",
    "clawhub_compatible": true
  }
}

工作流

1. 创建 Bundle

bash

# 从现有 skills 目录生成清单
python scripts/bundle-validator.py generate \
  --skills-dir skills/ \
  --output bundle-manifest.json \
  --name "coding-tools" \
  --version "1.0.0"

2. 验证 Bundle

bash

# 检查清单格式、依赖冲突、版本兼容性
python scripts/bundle-validator.py validate \
  --manifest bundle-manifest.json \
  --skills-dir skills/

验证内容：

• 清单 JSON 格式是否合法
• 每个 skill 的 SKILL.md 是否存在
• 依赖关系是否有环
• 版本号是否符合 semver
• 平台兼容性

3. 安装 Bundle

bash

# 安装到目标 skills 目录
python scripts/bundle-installer.py install \
  --manifest bundle-manifest.json \
  --source ./bundle-source/ \
  --target ~/.openclaw/skills/

# 从 ClawHub 安装
python scripts/bundle-installer.py install \
  --from-clawhub "coding-tools@1.0.0" \
  --target ~/.openclaw/skills/

4. 管理已安装 Bundle

bash

# 列出已安装的 bundle
python scripts/bundle-installer.py list --target ~/.openclaw/skills/

# 更新 bundle
python scripts/bundle-installer.py update \
  --manifest bundle-manifest.json \
  --target ~/.openclaw/skills/

# 卸载 bundle
python scripts/bundle-installer.py uninstall \
  --name "coding-tools" \
  --target ~/.openclaw/skills/

版本管理

Semver 规则

• MAJOR.MINOR.PATCH（如 1.2.3）
• 不兼容变更 → MAJOR
• 新增功能（向后兼容）→ MINOR
• Bug 修复 → PATCH

兼容性检查

json

{
  "dependencies": {
    "runtime": "python>=3.8",
    "openclaw": ">=0.9.0",
    "platform": ["windows", "linux"]
  }
}

安装时自动检查：

• Python 版本是否满足
• OpenClaw 版本是否兼容
• 目标平台是否支持

与 ClawHub 的关系

Bundle 可以发布到 ClawHub：

bash

# 发布到 ClawHub
clawhub publish --bundle bundle-manifest.json

# 从 ClawHub 搜索
clawhub search "coding-tools"

ClawHub 上的 bundle 包含：

• bundle-manifest.json
• 所有 skill 文件（打包为 tar.gz）
• 版本历史和 changelog

命令参考

bundle-validator.py

命令	说明
generate	从 skills 目录生成清单
validate	验证清单和依赖
check-deps	仅检查依赖冲突

bundle-installer.py

命令	说明
install	安装 bundle
uninstall	卸载 bundle
list	列出已安装 bundle
update	更新 bundle

注意事项

• Bundle 内的 skill 路径使用相对路径（相对于 manifest 所在目录）
• 安装时会自动创建备份（.bak 后缀）
• 卸载时保留用户配置文件（不删除 .learnings/ 等用户数据）
• 版本冲突时提示用户选择，不自动覆盖