content-migration

Files (3)

• SKILL.md
• _claude-frontmatter-extras.yaml · references/
• migration-runbook.md · references/

SKILL.md (first lines)

# Content Migration

Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic.

---

## When to use

- Migrating from one CMS to another (e.g., WordPress to a headless setup)
- Consolidating multiple sites into one
- Splitting one site into multiple
- Changing URL structures
- Domain migration (one brand to another, mergers, rebrands)
- Migrating from a custom build to a platform (or vice versa)
- Content audit-driven cleanup as part of a larger move

## When NOT to use

- A net-new site with no existing content (no migration needed)
- Single-page edits or content updates within an existing site (use `content-and-copy`)
- Performance or technical SEO improvements without URL changes (use `seo-technical`)
- Routine content audits (use `seo-content-audit`)

---

## Required inputs

- The source: current platform, current URL structure, current content inventory
- The destination: target platform, target URL structure, target capabilities
- The reason for migration (drives priority of what to preserve)
- Constraints (timeline, budget, downtime tolerance)
- Stakeholders (SEO, content, dev, comms, support)

---

## The framework: 6 phases

Every content migration follows the same arc. Skipping a phase is how migrations go badly.

### Phase 1: Inventory

You can't migrate what you don't know. Build a complete map of what exists.

For each piece of content:
- URL
- Title
- Content type (article, landing page, product, doc, etc.)
- Status (live, draft, archived, scheduled)
- Last modified
- Author or owner
- Traffic (last 12 months), or state the gap per the data-availability rule
- Backlinks (top external referrers)
- Internal links pointing to it
- Embedded assets (images, video, downloads)

Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool.

The inventory is a spreadsheet. It's the source of truth for the rest of the migration.

### Phase 2: Audit and decide

For each piece of content, decide:

- **Keep:** migrate as-is
- **Update:** migrate with edits (refresh, expand, fix)
- **Merge:** combine with another piece, redirect both old URLs to the new
- **Redirect:** don't migrate; redirect to a related page
- **Delete:** don't migrate, no redirect (use sparingly; only for clearly low-value pages)

This is `seo-content-audit` work. The migration is the time to do it; not the time to skip it.

For each "Update" or "Merge," document the specific changes.

### Phase 3: Map URLs

The URL map is the most important migration artifact.

| Old URL | New URL | Status code | Reason |
|---|---|---|---|
| /old/path | /new/path | 301 | Direct equivalent |
| /old/page-1, /old/page-2 | /new/merged | 301 | Merged content |
| /old/deprecated | /related/replacement | 301 | Closest replacement |
| /old/junk | (none) | 410 | Intentionally gone |

Rules:
- 301 (permanent redirect) for content that has a new home
- 410 (gone) for intentionally deleted content
- Avoid 404 (not found) where 410 is more accurate
- Never redirect everything to the homepage; specific is always better
- Map every URL with traffic or backlinks; lower-priority URLs can be patterned

For domain migrations, use a 1:1 path mapping by default (`old.com/page` → `new.com/page`) with specific overrides where structure changes.

### Phase 4: Build and stage

Build the destination. Don't skip a staging environment.

- Set up the new platform with the new content
- Implement the URL map (most platforms support a redirect file or rule)
- Verify a representative sample of redirects work
- Test critical user flows (signup, purchase, contact)
- Validate analytics, monitoring, and integrations
- Test from search engine perspective: robots.txt, sitemap, canonicals

If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip.

### Phase 5: Cut over

The actual switch. Plan it like a launch (and use `launch-runbook` alongside this skill).

Pre-cutover:
- Comms to stakeholders (date, expected impact)
- Comms to users if downtime expected
- Support team prepped for likely questions
- Lower DNS TTL the day before (1-3 days for safety)
- Backup of source platform (in case rollback is needed)

Cutover:
- Redirect rules go live

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills