name: skill-migrator description: | 让 OpenClaw 学会把 Claude Code 和 Hermes skill 转成 OpenClaw skill。 Use when: the user asks to convert a Claude Code skill or Hermes skill into an OpenClaw skill. Use when: OpenClaw should analyze first, then convert or phased-migrate the source skill into OpenClaw format. Handles: source detection, analysis, tool mapping, state migration, validation, and manual review notes.

Skill Migrator

让 OpenClaw 学会把 Claude Code 和 Hermes skill 转成 OpenClaw skill。

Goal

读取现有的 Claude Code 或 Hermes skill，并产出一份可继续使用的 OpenClaw skill 骨架。目标结果至少包括：

• 合法的 SKILL.md
• 需要时生成 scripts/
• 需要时生成 references/
• 有状态时生成 state.yaml
• 在分阶段迁移时生成 MIGRATION_REPORT.md

重点不是解释迁移思路，而是让 OpenClaw 真正把结果落成可验证的文件结构。

Scope

• 第一优先支持：Claude Code .md
• 第一优先支持：Hermes config.toml + Python
• 扩展支持：CloudCode .cs + YAML
• 不适用：从零创建全新 OpenClaw skill
• 不适用：简单修改已有 OpenClaw skill

Trigger Hints

遇到下面这类请求时，应优先使用本 skill：

• "把这个 Claude Code skill 转成 OpenClaw skill"
• "帮我迁移这个 Hermes skill"
• "分析这个 skill 能不能迁移到 OpenClaw"
• "先分析，再分阶段迁移成 OpenClaw skill"

Quick Decision Tree

收到迁移请求
    ↓
先运行 analyze_skill.py
    ↓
结果是否低风险且映射清晰？
    ├─ 是 -> 直接使用 convert_skill.py
    ↓ 否
是否存在未知工具、复杂状态或多入口？
    ├─ 是 -> 使用 migrate_skill.py --phased
    ↓ 否
继续直接转换
    ↓
运行 validate_skill.py --strict
    ↓
若仍有 warning / error -> 输出 partial 或 failed，并列出人工审查项

Workflow

1. 先识别源系统。
   • Claude Code：优先选择带 SLASH_COMMANDS 的 markdown
   • Hermes：读取 config.toml、声明的 tools、以及实现脚本
   • CloudCode：读取 .cs、@tool、状态和依赖
2. 先分析，再决定是否直接转换。

python scripts/analyze_skill.py \
  --source /path/to/skill \
  --system claude-code \
  --output ./analysis/

1. 审查 analysis.json、compatibility_report.md、mapping.yaml。
2. 根据复杂度选择迁移模式。
   • 简单场景：

python scripts/convert_skill.py \
  --analysis ./analysis/analysis.json \
  --output ./converted/

• 复杂场景：

python scripts/migrate_skill.py \
  --analysis ./analysis/analysis.json \
  --output ./converted/ \
  --phased

1. 严格验证结果。

python scripts/validate_skill.py \
  --skill ./converted/my-skill/ \
  --strict

1. 向用户明确说明：
   • 哪些内容已迁移
   • 哪些工具或状态仍需人工处理
   • 当前结果是 completed、partial 还是 failed

Review Checkpoints

Checkpoint 1: After Analysis

• 必须审查 compatibility_report.md、mapping.yaml、以及 analysis warnings
• 必须确认入口文件选择是否合理
• 必须判断应该直接转换，还是改走 phased migration

Checkpoint 2: After Conversion

• 必须确认输出目录结构完整
• Claude Code 必须确认 references/original.md 已保留
• Hermes 必须确认脚本已复制到 scripts/
• 有状态时必须确认 state.yaml 是否已经生成

Checkpoint 3: After Validation

• 如果 validate_skill.py --strict 仍有 warning 或 error，不要宣称迁移完成
• 结果必须落到 completed、partial 或 failed
• 需要人工处理的项必须明确列出

Source-Specific Rules

Claude Code -> OpenClaw

• 优先使用带 SLASH_COMMANDS 的 markdown
• 将 slash commands 转成 OpenClaw 能理解的使用说明
• 保留原始 markdown 到 references/original.md
• 如果有多个候选 markdown，明确记录选择了哪一个
• 如果没有 SLASH_COMMANDS，可以继续，但必须保留 warning

Hermes -> OpenClaw

• 用 config.toml 提取 name、description、declared tools
• 把实现脚本复制到 scripts/
• 只把声明过的 tool 或 tools/ 目录中的实现视为 tool
• 不要把普通 helper function 全部误判成 tool
• 如果发现状态文件，尽量转换为 state.yaml

CloudCode -> OpenClaw

• 这是扩展支持，不是第一目标
• 提取 .cs 中的 @tool
• 对已知工具做自动映射
• 未知工具标记为 manual review
• 不要把未知工具伪装成已完成映射

Common Mappings

search_web: web_search
fetch_url: web_fetch
read_file: read
write_file: write
edit_file: edit
run_command: exec
search_memory: memory_search
get_memory: memory_get

Boundary Conditions

如需更细的诊断步骤、修复选择和场景说明，按需读取 references/migration-playbook.md。

If Analysis Shows High Risk

• 未知工具很多、状态复杂、或平台特有能力缺少等效时，优先使用 migrate_skill.py --phased
• 如果核心能力无法可靠映射，明确建议部分迁移或重写
• 只有在选项会显著改变结果时才暂停等待用户决策
• 如果可以安全继续，就保持 partial 并记录 warning，而不是假装完全成功

If Source Files Look Corrupted

• 先确认是解析问题还是显示问题，不要先假设文件已经损坏
• 在 PowerShell 中优先这样检查：

Get-Content -Raw -Encoding UTF8 source_file

• 如果脚本仍然无法解析，记录问题并停留在 analysis 或 partial 阶段
• 不要承诺当前脚本并不存在的通用自愈或自动补救能力

If Tool Mapping Conflicts

• 先查看 mapping.yaml
• 如果多个源工具映射到同一个 OpenClaw 工具，先评估功能差异是否影响核心流程
• 能接受差异时，明确记录限制
• 不能接受差异时，输出 manual review，必要时再补 wrapper
• 不要为了“看起来完成”而伪造等价映射

If State Migration Is Unclear

• 当前实现会尽量把检测到的状态文件转换为 state.yaml
• 如果结构复杂、字段含义不清、或存在潜在丢失风险，保留 warning
• 不要静默丢弃关键字段
• 无法确认时，告诉用户需要人工审查或重建状态

If Validation Finds Issues

• 先修正文档或生成结果中明显、本地可修的错误
• 然后重新运行 validate_skill.py
• 如果仍有 warning 或 error，不要宣称迁移完成
• 根据结果返回 partial 或 failed

If User Says "Stop" or "Rollback"

• 立即停止当前迁移
• 保留已经生成的分析或输出目录
• 简要说明已完成、部分完成、以及未完成的部分
• 不要承诺当前仓库没有实现的备份、归档或自动回滚流程

Minimal Examples

Example 1: Claude Code, Low Risk

• 用户请求：把一个带 SLASH_COMMANDS 的 Claude Code skill 转成 OpenClaw
• 处理方式：先分析，再直接转换，最后严格验证
• 预期结果：SKILL.md 保留 slash command 说明，references/original.md 存在

Example 2: Hermes, Declared Tools Only

• 用户请求：迁移一个 config.toml + Python 的 Hermes skill
• 处理方式：从 config.toml 取 name、description、declared tools，再复制实现脚本
• 预期结果：只有声明过的 tools 被视为 tool，helper function 不会被误判

Example 3: CloudCode, Partial Result

• 用户请求：迁移一个含未知工具的 CloudCode skill
• 处理方式：优先使用 phased migration，保留 manual review 项
• 预期结果：生成 MIGRATION_REPORT.md，最终状态可能是 partial

Manual Review Triggers

遇到以下情况时，不要直接宣称“迁移完成”，而是输出人工审查项：

• 未知工具或无法安全映射的工具
• 复杂状态结构
• 自定义 memory 或 scheduling 行为
• 多个候选入口文件
• validation 出现 warning 或 error

Output Requirements

转换结果至少要满足这些要求：

• SKILL.md frontmatter 合法
• description 包含明确的 Use when
• skill 名称符合 OpenClaw 约定
• Python 脚本无语法错误
• 有状态时，stateful: true 与状态说明保持一致
• 不把部分成功伪装成完全成功

References

• 详细映射参考：references/cross-system-mappings.md
• 详细诊断与场景参考：references/migration-playbook.md
• 人类说明文档：README.md

Remember

迁移的目标不是形式上生成文件，而是让 OpenClaw 最终得到一份能继续使用、能继续修改、并且风险清楚可见的 skill。

v4.5 - 保持真实边界，补回决策树、检查点与最小示例。