Commands

---
description: Generic skill-version migration — works for hardened/v2/experimental→stable promotions across MCP servers, skills, hooks, commands. Mirrors /migrate-to-hardened with broader detection.
argument-hint: <skill-name> [--dry-run] [--rollback]
allowed-tools: Bash, Read, Edit, Write, Glob
model: claude-sonnet-4-6
---

# Migrate skill version

Generalize the unhardened→hardened cutover pattern (see /migrate-to-hardened) to ANY skill upgrade. Detects migration type by directory naming convention, runs build + smoke-test + register + archive, supports --dry-run preview + --rollback reversal.

## Detection

Scan `~/.claude/plugins/heymegabyte-claude-skills/` for siblings matching one of:

| Pattern | Migration type |
|---|---|
| `<name>-hardened-mcp/` next to `<name>-mcp/` | hardening promotion |
| `<name>-v2/` next to `<name>/` | major version bump |
| `<name>/` with `metadata.stage: stable` next to one with `metadata.stage: experimental` | promotion |
| `<name>-next/` next to `<name>/` | preview → current |

If none detected, exit with usage.

## 7-step flow (forward migration)

1. Verify the NEW version directory exists; bail if missing
2. Build: if `package.json` → `npm install && npm run build`; if `Cargo.toml` → `cargo build --release`; else just verify file existence
3. Smoke-test by skill type:
   - MCP server: spawn + send `tools/list` JSON-RPC, expect non-empty result within 5s
   - Slash command: render markdown (no-op smoke)
   - Hook: dry-run with sample stdin
   - Template util: `node --check`
4. Interface comparison: parse OLD + NEW surface (tool list / command frontmatter / hook exports). Warn on REMOVED interfaces (breaking change for consumers)
5. Register: patch the right config file
   - MCP server → `~/.claude.json` mcpServers entry path swap
   - Hook → `~/.claude/settings.json` hooks block path swap
   - Slash command → no-op (auto-discovered)
   - Skill → no-op (auto-discovered)
6. Archive old: `mv <old-path> <old-path>.archived-{timestamp}`
7. Print confirmation + rollback command

## Flags

- `--dry-run`: print 7-step plan with absolute paths; no writes
- `--rollback`: reverse everything (un-archive + restore registration + remove new entry from config + remove new dir)
- (no flag): run forward migration with user confirmation prompt before destructive steps

## Composition

`/migrate-to-hardened <name>` is equivalent to `/migrate-skill <name>-hardened`. Use the more specific command when the migration is specifically a hardening; use this generic command for v2/stable/preview transitions.

## Rollback safety

Every archived directory keeps a timestamp suffix so multiple rollbacks coexist without overwriting. `~/.claude.json` and `~/.claude/settings.json` get a `.bak-{timestamp}` copy before any write.

## See also

- `commands/migrate-to-hardened.md` — specialization for hardening
- `rules/no-staging-doctrine.md` — instant rollback is the only acceptable safety net
- `rules/main-only-branch.md` — same instant-rollback principle applied to migrations
- `rules/agent-resilience-discipline.md` — file-by-file write ordering survives connection drops