ClawHub 同步工具

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

⚠️ ClawHub 许可证说明

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

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

详见 ClawHub Skill Format

---

前置条件

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

yaml

---

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

---

使用方式

1. 登录 ClawHub（首次使用）

bash
clawhub login

2. 验证发布内容

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

bash
clawhub sync --dry-run

3. 同步技能

同步单个技能：

bash
clawhub sync skills/

同步所有技能：

bash
clawhub sync --all

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

交互式选择同步：

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

---

单个 Skill 同步工作流

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

前置检查

1. 1. 检查登录状态

bash clawhub whoami

1. 2. 检查白名单

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

1. 3. 检查许可证

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

版本检测

比较两个版本号：

来源	位置	格式
新版本	skills/<skill-name>/SKILL.md frontmatter 的 version	1.2.0
已记录版本

skills/clawhub-sync/config/sync-records.yaml 中的 version | 1.1.0 |

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

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

执行同步

步骤 1：准备发布目录
bash
bash skills/clawhub-sync/scripts/prepare-publish.sh skills/

步骤 2：执行发布（使用 publish 命令）
bash
clawhub publish /tmp/clawhub-publish- \
--version <新版本号> \
--changelog <变更说明>

为什么用 publish 而不是 sync？

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

步骤 3：更新同步记录

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

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

示例：同步 git-batch-commit

bash

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

---

同步策略

版本号处理

• - 从技能的 CHANGELOG.md 第一行提取版本号
• 格式要求：## [x.y.z] - YYYY-MM-DD
• 自动处理 v 前缀（v1.0.0 → 1.0.0）

自动字段

字段	处理方式
homepage	自动设置为 GitHub 仓库地址
version

从 CHANGELOG.md 提取（如 SKILL.md 中未指定） |

同步范围控制（白名单机制）

配置文件： skills/clawhub-sync/config/sync-allowlist.yaml（skill 自包含）

优先级：白名单 > 默认忽略规则

• - 如果 skills/clawhub-sync/config/sync-allowlist.yaml 存在：只同步文件中列出的 skill
• 如果 skills/clawhub-sync/config/sync-allowlist.yaml 不存在：使用默认忽略规则（忽略 test/、private-skills/、node_modules/）

配置格式：

yaml

legal-qa-extractor: # 带 # 表示不发布

legal-qa-extractor: # 无 # 表示发布
litigation-analysis:

配置文件： skills/clawhub-sync/sync-allowlist.yaml（skill 自包含）

文件过滤规则

发布时会自动应用 .gitignore 过滤规则，确保敏感文件和临时文件不会被上传。

双重过滤机制：

1. 1. 项目根目录 .gitignore - 自动检测 Git 仓库根目录的 .gitignore
2. 技能内部 .gitignore - 如果技能目录有自己的 .gitignore，会额外应用

默认排除（始终生效）：

• - .git/ - Git 目录
• nodemodules/ - Node.js 依赖
• pycache/ - Python 缓存
• .DSStore - macOS 系统文件

同步流程

每次同步前，会自动：

1. 1. 创建临时目录 - 在 /tmp/clawhub-publish- 创建临时目录
2. 复制过滤后的文件 - 使用 rsync 遵循 .gitignore 规则复制文件
3. 发布到 ClawHub - 从临时目录执行发布命令
4. 清理临时目录 - 发布完成后自动清理

手动准备发布目录

如需手动检查将要发布的文件：

bash

准备发布目录（不实际发布）

bash skills/clawhub-sync/scripts/prepare-publish.sh skills/trademark-assistant

检查临时目录内容

ls -la /tmp/clawhub-publish-trademark-assistant/

安全最佳实践

发布前检查清单

• - [ ] 确认 .gitignore 包含所有敏感文件模式
• [ ] 使用 prepare-publish.sh 检查将要发布的文件
• [ ] 不要在技能中包含 API keys、密码等
• [ ] 使用 .env.example 代替 .env 文件

常见敏感文件

• - .env - 环境变量（使用 .env.example 作为模板）
• config.yaml - 配置文件（使用 config.example.yaml 作为模板）
• .db, .sqlite - 数据库文件
• logs/ - 日志目录