ClawHub 同步工具

将本地开发的 Skills 批量同步到 ClawHub 平台。支持读取 .gitignore 智能忽略敏感文件和临时文件。

⚠️ ClawHub 许可证说明

ClawHub 平台强制使用 MIT-0 许可证（无需署名，允许商业使用）。

• MIT 许可证的 skill 可以同步
• CC-BY-NC-SA-4.0 等限制性许可证与 MIT-0 冲突，不应同步

详见 ClawHub Skill Format

前置条件

SKILL.md frontmatter 需包含必要字段：

---
name: skill-name
description: 技能描述
version: "1.0.0"  # 推荐但不强制
homepage: https://github.com/cat-xierluo/legal-skills  # 自动设置
---

使用方式

1. 登录 ClawHub（首次使用）

clawhub login

2. 验证发布内容

执行 dry-run 检查配置是否正确，不实际发布：

clawhub sync --dry-run

3. 同步技能

同步单个技能：

clawhub sync skills/<skill-name>

同步所有技能：

clawhub sync --all

注意：--all 会受 skills/clawhub-sync/config/sync-allowlist.yaml 约束。如果存在白名单文件，只同步其中列出的 skill。

交互式选择同步：

用户可以指定要同步的技能列表，我会逐个执行同步命令。

单个 Skill 同步工作流

当需要同步指定的 skill（而非全部）时，使用此工作流。

前置检查

1. 检查登录状态

   clawhub whoami
   

2. 检查白名单

   • 读取 skills/clawhub-sync/config/sync-allowlist.yaml
   • 确认目标 skill 在白名单中（未被 # 注释）

3. 检查许可证

   • 读取目标 skill 的 SKILL.md frontmatter 中的 license 字段
   • 只有 MIT 许可证的 skill 才能同步
   • CC-BY-NC-SA-4.0 等限制性许可证不应同步

版本检测

比较两个版本号：

版本比较逻辑（语义化版本）：

new_version > recorded_version → 需要同步
new_version == recorded_version → 跳过（无变化）
new_version < recorded_version → 警告（版本回退？）
recorded_version 为 null → 需要同步（首次发布）

执行同步

步骤 1：准备发布目录

bash skills/clawhub-sync/scripts/prepare-publish.sh skills/<skill-name>

步骤 2：执行发布（使用 publish 命令）

clawhub publish /tmp/clawhub-publish-<skill-name> \
  --version "<新版本号>" \
  --changelog "<变更说明>"

为什么用 publish 而不是 sync？

• clawhub sync 会扫描所有目录的 skills，可能遇到 slug 冲突
• clawhub publish <path> 只发布指定路径的单个 skill，更精确

步骤 3：更新同步记录

更新 skills/clawhub-sync/config/sync-records.yaml：

<skill-name>:
  version: "<新版本号>"
  last_sync: "<ISO 8601 时间>"
  git_hash: "<当前 commit hash>"
  status: synced
  changelog_summary: "<变更说明>"
  url: "https://clawhub.ai/skills/<skill-name>"
  publish_id: "<从命令输出获取>"

示例：同步 git-batch-commit

# 1. 检查白名单
grep "git-batch-commit:" skills/clawhub-sync/config/sync-allowlist.yaml
# 输出：git-batch-commit:           # MIT

# 2. 比较版本
# SKILL.md: version: "1.2.0"
# sync-records.yaml: version: "1.1.0"
# 结论：1.2.0 > 1.1.0，需要同步

# 3. 准备发布
bash skills/clawhub-sync/scripts/prepare-publish.sh skills/git-batch-commit

# 4. 执行发布（使用 publish 命令）
clawhub publish /tmp/clawhub-publish-git-batch-commit \
  --version "1.2.0" \
  --changelog "添加 ClawHub 同步工作流"

# 5. 更新记录
# 编辑 sync-records.yaml，更新 git-batch-commit 条目

失败处理

• 同步失败时记录 status: failed
• 不重试，让用户决定后续操作
• 记录失败原因到 changelog_summary

同步策略

版本号处理