| name | agent-migration |
| description | Guides users through migrating from OpenClaw or Hermes to NeoAgent. Run this skill when a user wants to migrate their existing agent setup. Provides step-by-step guidance, dry-run previews, and handles API key conflicts interactively. |
| version | 1.0.0 |
| metadata | {"neoagent":{"tags":["migration","openclaw","hermes","setup","import"],"related_skills":[]}} |
Agent Migration Guide
Guides users through migrating their existing OpenClaw or Hermes agent setup to NeoAgent.
When to Use This Skill
Use this skill when:
- A user says they're migrating from OpenClaw or Hermes
- A user wants to import their existing skills, memories, or API keys
- A user runs
neoagent migrate and needs guidance
How Migration Works
NeoAgent's migration system automatically detects existing OpenClaw (~/.openclaw/) and Hermes (~/.hermes/) installations and migrates:
| Data | Source | Destination |
|---|
| Skills | skills/*.md in source | ~/.neoagent/agent-data/skills/[source]-imports/ |
| Memories | SOUL.md, MEMORY.md, USER.md | ~/.neoagent/agent-data/memory/[source]/ |
| API Keys | .env files | ~/.neoagent/.env (merged with conflict prompts) |
Step-by-Step Migration Flow
Step 1: Check Migration Status
Ask the user to run:
neoagent migrate status
This will show which source agents are detected.
Step 2: Preview (Optional - Dry Run)
Ask the user to run:
neoagent migrate dry-run
This shows exactly what would be migrated without making any changes.
Step 3: Run Full Migration
Ask the user to run:
neoagent migrate
The migration will:
- Scan both sources (if present)
- Copy skills to import directories
- Copy memory files
- Merge API keys with interactive conflict resolution
Step 4: Verify Migration
After migration completes, advise the user to:
neoagent status # Check server is running
neoagent start # Start the server if not running
Imported skills appear in:
~/.neoagent/agent-data/skills/openclaw-imports/~/.neoagent/agent-data/skills/hermes-imports/
Imported memories appear in:
~/.neoagent/agent-data/memory/openclaw/~/.neoagent/agent-data/memory/hermes/
API Key Conflict Resolution
During migration, if an API key exists in multiple sources (including an existing NeoAgent config), the user will be prompted:
⚠️ Conflict: OPENAI_API_KEY
Existing in: neoagent
Incoming from: openclaw
[1] Keep existing (neoagent)
[2] Overwrite with new (openclaw)
[3] Skip this key
Guide the user to choose based on their needs:
- Keep existing: If they want to preserve the current NeoAgent configuration
- Overwrite: If the incoming key is the one they want to use
- Skip: If they want to deal with it manually later
Troubleshooting
"No OpenClaw or Hermes installation detected"
Cause: The source directories don't exist at default locations.
Solution:
- Check if the installation is at a custom path
- Manually copy data:
- Skills: Copy
*.md files to ~/.neoagent/agent-data/skills/
- Memories: Copy to
~/.neoagent/agent-data/memory/
- API keys: Edit
~/.neoagent/.env manually
"Permission denied" errors
Cause: Missing read permissions on source or write permissions on target.
Solution: Ensure the user has appropriate permissions:
chmod 755 ~/.openclaw
chmod 755 ~/.hermes
chmod 755 ~/.neoagent
Migration seems incomplete
Cause: Some files may have already existed and were skipped (migration is idempotent).
Solution: Re-run migration - it won't overwrite existing files.
Manual Migration (If Automated Fails)
If the automated migration doesn't work:
For Skills
mkdir -p ~/.neoagent/agent-data/skills/openclaw-imports
cp ~/.openclaw/skills/*.md ~/.neoagent/agent-data/skills/openclaw-imports/
For Memories
mkdir -p ~/.neoagent/agent-data/memory/openclaw
cp ~/.openclaw/workspace/SOUL.md ~/.neoagent/agent-data/memory/openclaw/
cp ~/.openclaw/workspace/MEMORY.md ~/.neoagent/agent-data/memory/openclaw/
cp ~/.openclaw/workspace/USER.md ~/.neoagent/agent-data/memory/openclaw/
For API Keys
nano ~/.neoagent/.env
Post-Migration Checklist
After successful migration, advise the user to:
