convez.ai
SkillAutomaçãoIntermediário
Jackeyhate9

Skills Migration

Jackeyhate9/skills-migration

Migre skills e configs de AI Agents entre máquinas com backup e rollback

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta de migração de skills, prompts e configurações entre máquinas para agentes IA (Codex, Claude Code, Hermes, opencode e outros). Exporta e restaura arquivos com suporte a backup, rollback e detecção de conflitos, com interface CLI e WebUI.

Instalação

$npx convez-ai Jackeyhate9/skills-migration

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Transferir skills customizadas entre computadores
  • Fazer backup de configurações de agentes IA antes de atualizar
  • Restaurar ambiente completo de desenvolvimento em nova máquina

Veredito

Solução prática e bem-estruturada para quem trabalha com múltiplos agentes IA e precisa sincronizar ambientes. Oferece segurança com backup automático e estratégia inteligente de conflitos, embora o suporte ainda se concentre em Windows.

README

A tradução para o português deste README ainda está na fila.

Skills Migration

Skills Migration 是一个 Windows 优先、跨平台可扩展的 AI Agent Skills 迁移工具。它聚焦跨机器迁移闭环:在源机器扫描并导出迁移 zip,在目标机器导入、生成恢复计划、处理冲突、创建备份快照,并支持 rollback。

English summary: Skills Migration exports and restores AI coding agent skills, prompts, commands, settings, and related config files across machines.

Dashboard screenshot

当前目标

  • 扫描 opencode、Hermes、Claude Code、Codex、OpenClaw、Cursor、Gemini CLI 的本地配置目录。
  • 导出 skills、prompts、commands、settings、memories,以及普通配置文件类别。
  • 默认跳过 secrets:.env、*.pem、*.key、credentials.json、token.json、secrets.json、含 API_KEY / TOKEN / SECRET / PASSWORD 的配置项。
  • 生成可复制到另一台电脑的 zip 迁移包。
  • 导入时校验 manifest 和 checksums。
  • 导入前创建 backups/YYYYMMDD-HHMMSS-before-restore/。
  • 生成 restore_plan.json 和 restore_report.md。
  • 冲突文件默认 rename 为 *_imported。
  • 支持 rollback 恢复导入前状态。

支持的 Agent

Agent / ToolWindows 扫描路径macOS / Linux 扫描路径状态
Codex%USERPROFILE%\.codex~/.codex已支持
OpenClaw / .agents skills%USERPROFILE%\.agents~/.agents已支持
Claude Code%USERPROFILE%\.claude~/.claude已支持
opencode%APPDATA%\opencode, %LOCALAPPDATA%\opencode, %USERPROFILE%\.config\opencode~/.config/opencode已支持
Hermes%USERPROFILE%\.hermes~/.hermes已支持
Cursor%USERPROFILE%\.cursor~/.cursor已支持
Gemini CLI%USERPROFILE%\.gemini~/.gemini已支持

识别类别:

  • skills
  • agents
  • commands
  • prompts
  • mcp_configs,仅作为普通配置文件类别参与导出/导入,不做 MCP 产品级迁移或机器绑定
  • settings
  • memories
  • sessions,默认不迁移,可选开启
  • secrets,默认跳过

一键跨机器迁移

源机器导出:

skills-migration.exe export --output ./exports

会生成:

exports/agent-skills-export-YYYYMMDD-HHMMSS/
├─ manifest.json
├─ restore_plan.template.json
├─ agents/
│  ├─ opencode/
│  ├─ hermes/
│  ├─ claude/
│  └─ codex/
└─ logs/
   └─ export_report.md

exports/agent-skills-export-YYYYMMDD-HHMMSS.zip

把 zip 复制到目标机器,先预览:

skills-migration.exe import ./agent-skills-export-YYYYMMDD-HHMMSS.zip --preview

确认后导入:

skills-migration.exe import ./agent-skills-export-YYYYMMDD-HHMMSS.zip

回滚:

skills-migration.exe rollback --snapshot backups/YYYYMMDD-HHMMSS-before-restore

兼容 npm bin 名:

agent-migrator export --output ./exports
agent-migrator import ./agent-skills-export-YYYYMMDD-HHMMSS.zip
agent-migrator rollback --snapshot backups/YYYYMMDD-HHMMSS-before-restore

导入冲突策略

  • skills / prompts / commands / agents / memories:默认 merge 到目标 agent 目录;同名文件冲突时写成 *_imported。
  • settings / unknown config:默认不直接覆盖,写入 restore plan,标记为需要确认。
  • mcp_configs:作为普通 JSON 配置文件处理;JSON 文件冲突时做 JSON merge,不做整文件覆盖。
  • secrets:默认 skip。

Windows 可运行包

构建:

npm install
npm run package:win

输出:

outputs\win-x64\skills-migration.exe

启动 WebUI:

outputs\win-x64\skills-migration.exe web

查看基础功能:

outputs\win-x64\skills-migration.exe features

本地开发

npm install
npm run smoke
npm run typecheck
npm run dev

WebUI:

http://localhost:5174

WebUI 页面

  • Scan
  • Export
  • Import
  • Restore Plan
  • Conflicts
  • Backup & Rollback
  • Logs

Manifest

schema 文件:

docs/manifest.schema.json

manifest.json 包含:

  • export_version
  • created_at
  • source_os
  • source_hostname
  • detected_agents
  • categories
  • file_count
  • total_size
  • checksums
  • files[].original_path
  • files[].portable_target_path
  • skipped_sensitive_files

v0.2 Status / v0.2 状态

  • WebUI now has a migration package picker. In Tauri it can choose a .zip package or an extracted export directory path; in browser fallback it uploads .zip files and keeps Advanced manual path input for directories.
  • Config Review is implemented for settings/config files. Users can choose skip, backup_then_overwrite, merge, or rename_imported; choices are written into restore_plan.json.
  • JSON config files get structured diff summaries. TOML/YAML/text files get text diff summaries.
  • MCP Runtime Check is implemented as a checker only. It parses MCP config, checks known runtimes and local paths, generates mcp_runtime_report.md, and never installs dependencies.
  • Export to Folder is implemented: latest.zip, manifest-latest.json, exports/*.zip, and history.json. If the folder is already a git repo, optional --git-commit creates a local commit. It never pushes.

Current remaining limitations:

  • Browser fallback cannot safely expose arbitrary local directory paths, so extracted-directory import is best in Tauri or via Advanced manual path.
  • Config Review UI is functional but intentionally simple; richer side-by-side diff rendering is still future work.
  • MCP Runtime Check reports missing dependencies and paths but does not install or fix them.
  • GitHub/cloud sync remains explicit user responsibility; use a private repo or private sync tool.

v0.3 Practical Release / 实用版定位

AI Agent Skills Migrator is a desktop tool for safely moving AI coding agent workflows between computers. The practical release narrows the product scope:

  • Tauri desktop is the intended full migration tool.
  • Browser fallback is preview-only: upload a zip, preview manifest.json, and preview restore_plan.json.
  • Secrets/API keys are not migrated by default.
  • MCP configs are checked, but MCP server runtimes are not installed automatically.
  • GitHub/cloud sync is not enabled by default; local git backup remains optional.

支持的 Agent:

  • opencode
  • Hermes
  • Claude Code
  • Codex
  • OpenClaw / .agents
  • Cursor
  • Gemini CLI

核心能力:

  • scan local agent homes
  • export migration zip
  • import migration zip
  • backup before restore
  • config review with practical diff summary
  • MCP runtime check with fix suggestions
  • rollback
  • local git backup

Migration Wizard flow:

Old computer:

  1. Scan local agents.
  2. Select agents/categories.
  3. Review sensitive files skipped by default.
  4. Export zip.
  5. Copy this zip to the new computer.

New computer:

  1. Select migration zip.
  2. Preview manifest.
  3. Create backup snapshot.
  4. Preview restore plan.
  5. Review settings/config actions.
  6. Check MCP runtime status and suggestions.
  7. Restore.
  8. Review result summary and rollback option.

Commands:

skills-migration.exe scan
skills-migration.exe export --output ./exports
skills-migration.exe import ./exports/agent-skills-export-YYYYMMDD-HHMMSS.zip --preview
skills-migration.exe import ./exports/agent-skills-export-YYYYMMDD-HHMMSS.zip
skills-migration.exe rollback --snapshot backups/YYYYMMDD-HHMMSS-before-restore
skills-migration.exe self-check
skills-migration.exe web

Windows packaging:

npm run package:win
npm run tauri:build

npm run package:win is the verified Windows executable-folder package. npm run tauri:build is provided for the desktop direction and requires a complete src-tauri scaffold. See PACKAGING_WINDOWS.md.

Smoke Test

npm run smoke

测试覆盖:

  1. 创建 fake opencode/hermes/claude/codex 配置目录。
  2. 写入 fake skills/prompts/settings。
  3. 执行 scan。
  4. 执行 export。
  5. 清空目标测试目录。
  6. 执行 import。
  7. 验证文件恢复成功。
  8. 验证 .env / token / secret 文件被跳过。
  9. 验证冲突文件被 rename。
  10. 验证 rollback 可恢复导入前状态。

已知限制

  • WebUI 的导入路径目前需要手动输入 zip 或导出目录路径,还没有系统文件选择器。
  • settings/config 默认不覆盖,需要后续增加逐项确认 UI。
  • MCP configs 只按普通配置文件处理,不负责安装 MCP server runtime、不做机器码绑定。
  • GitHub 同步不是默认功能;建议只把已审计迁移包放到 private repo。
Ver o original no GitHub

Bom para

Relacionados