Skip to content
Back to skills

Domain Migration

ASecurity

Plan and validate an SEO site move with a URL inventory, redirect map, canonical cutover and backlink-update drafts.

  • 50,068 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 21, 2026
ai-agentsgobashnextjsnodegitdatabase

Works with

  • cli

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned November 21, 2026

npx -y skills add sickn33/agentic-awesome-skills --skill domain-migration --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Domain Migration?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Domain Migration
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/sickn33-domain-migration/badge)](https://www.skillsdirectory.com/skills/sickn33-domain-migration)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: "domain-migration"
description: "Plan and validate an SEO site move with a URL inventory, redirect map, canonical cutover and backlink-update drafts."
category: "marketing"
risk: "critical"
source: "https://github.com/Illyism/seo-skills"
source_repo: "Illyism/seo-skills"
source_type: "community"
license: "MIT"
license_source: "https://github.com/Illyism/seo-skills/blob/a158c36a1c2c84a44ee7a1ae69c009caf73e1a35/README.md#license"
author: "Ilias Ism"
upstream_commit: "a158c36a1c2c84a44ee7a1ae69c009caf73e1a35"
date_added: "2026-11-21"
---

# Domain Migration

## When to Use

Use when changing a site's domain, consolidating slugs or moving a subdomain into a folder. Produce a URL inventory, permanent redirect map, cutover changes, verification results and optional outreach drafts. The examples use illustrative hosts.

Work on a branch or staging environment. Record the starting analytics and crawl state, affected hosts, activation order and rollback procedure. Require explicit authority before changing DNS, deploying to production, submitting Change of Address or sending mail.

## Decision tree: which migration is this

```
Migration type
├── Full domain change (billbox.io → invoicekit.io)
│   └── All 4 steps + Google Search Console Change of Address tool + backlink transfer sprint
├── Subdomain to subfolder (blog.deployfast.dev → deployfast.dev/blog)
│   └── Steps 1-3. Backlink sprint only for the top 10 referring pages to the subdomain.
├── Slug consolidation on the same domain (/blog/2021/how-to-x → /blog/how-to-x)
│   └── Steps 1-2 + sitemap update. No Change of Address.
└── Merging 2 sites into 1
    └── All 4 steps for the retired site. Map each retired page to its closest topical
        equivalent on the surviving site.
```

## Step 1: Full URL inventory

Build the union of every source below. Each catches URLs the others miss.

1. **Old `sitemap.xml`** (and nested sitemaps): the URLs the site currently advertises.
2. **Repo route tree:** every static route plus every slug generated by dynamic routes (`content/**`, data files, CMS export).
3. **Google Search Console:** Pages report, last 16 months, every URL with at least 1 click or 10 impressions.
4. **Ahrefs Best by links** (or the backlink tool the user has): every old URL with at least 1 referring domain. This is the list that saves retired posts with strong backlinks.
5. **Analytics landing pages:** every landing page with at least 1 session in the last 12 months.

Normalize before deduping: lowercase host, strip query strings and fragments, and pick one trailing-slash form. Write the result to `seo/url-inventory.csv` with columns `old_url,source,clicks_16mo,referring_domains`.

## Step 2: Deterministic 1-to-1 redirect map

Assign every inventory row a destination:

```
Old URL
├── Same content, same path on the new domain
│   └── Map the exact path
├── Same content, new slug
│   └── Explicit 1-to-1 entry
├── Content merged into another page
│   └── Explicit entry to the page that absorbed it
├── Content deleted, has referring domains or clicks
│   ├── A page on the same topic exists → explicit entry to that page
│   └── No topical equivalent → restore the page on the new domain, then map it 1-to-1
└── Content deleted, 0 referring domains, 0 clicks
    └── Let it return 410. Never point it at the homepage.
```

Then collapse chains: if the site already has redirects (`/old-slug → /new-slug`), resolve every entry to its final destination so each old URL reaches its target in exactly 1 hop.

Write `seo/redirect-map.csv` with header `old_url,new_url`. Every `new_url` must return `200` on the new domain before cutover.

### Ship the config for the user's host

**Next.js** (`next.config.mjs` on whichever deployment answers the old host). `permanent: true` returns `308`, which Google treats the same as `301`.

```js
import { readFileSync } from 'node:fs'

const explicit = readFileSync('./seo/redirect-map.csv', 'utf8')
  .trim().split('\n').slice(1)
  .map((line) => line.split(','))
  .map(([oldUrl, newUrl]) => ({ from: new URL(oldUrl).pathname, to: newUrl }))

export default {
  async redirects() {
    return [
      // Explicit 1-to-1 entries first: Next.js uses the first matching rule.
      ...explicit.map(({ from, to }) => ({
        source: from,
        has: [{ type: 'host', value: '(www\\.)?billbox\\.io' }],
        destination: to,
        permanent: true,
      })),
    ]
  },
}
```

Escape `(`, `)`, `:`, `*`, and `?` in old paths before using them as `source`; Next.js parses those characters as pattern syntax.

**Cloudflare Bulk Redirects** (CSV upload to a Bulk Redirect List, then enable a Bulk Redirect Rule for it):

```csv
source_url,target_url,status_code,preserve_query_string,include_subdomains,subpath_matching,preserve_path_suffix
billbox.io/blog/2021/send-invoices-faster,https://invoicekit.io/blog/send-invoices-faster,301,true,false,false,false
billbox.io/,https://invoicekit.io/,301,true,false,false,false
```

The last row matches the homepage only. Scope each rule to approved subdomains.

**Nginx:**

```nginx
map $uri $redirect_target {
  default "";
  include /etc/nginx/billbox-redirects.conf;  # lines like: /blog/2021/send-invoices-faster https://invoicekit.io/blog/send-invoices-faster;
}

server {
  listen 80;
  listen 443 ssl;
  server_name billbox.io www.billbox.io;
  # ssl_certificate lines stay: the old domain must keep valid HTTPS to serve its redirects.

  if ($redirect_target) { return 301 $redirect_target$is_args$args; }
  return 404;
}
```

Both listeners serve the same explicit map. Configure reviewed 410 responses for intentionally removed URLs before the 404 fallback.

### Verify the redirect map

Run the bundled [verifier](scripts/verify-redirects.sh) with Bash and curl against a reviewed map:

```bash
bash scripts/verify-redirects.sh seo/redirect-map.csv
```

Each row must contain exactly two unquoted HTTP(S) URLs with no commas, credentials, whitespace or fragments. List the HTTP variants explicitly when they should also redirect in one hop. The verifier makes bounded GET requests to the listed old and new URLs without following any redirects. It checks that the old URL returns 301 or 308 with a redirect URL equal to the destination and that the destination answers 200 directly. Check host-imposed HTTP-to-HTTPS upgrades separately if the edge prevents one-hop redirects.

Run against an authorized staging deployment before cutover and against authorized live hosts afterward. Verify coverage against the inventory, including intentional removals, separate from this positive redirect-map check.

## Step 3: Canonical, sitemap, schema, and hreflang cutover

### Pre-launch blockers

Inspect production-bound robots rules, page-level robots metadata and X-Robots-Tag headers on affected templates. Preserve staging protections and ensure intended production pages remain indexable.

### Edits in the repo

1. **Base URL:** update `metadataBase` (Next.js), `site` (Astro), `baseURL` (Hugo), or the canonical helper so every canonical, OG URL, and sitemap entry uses the new origin. `grep -rn "billbox.io" .` must return only the redirect config, the `alternateName`, and the `/about` history line.
2. **Sitemap:** the new domain's `sitemap.xml` lists only new URLs. Keep the old domain's sitemap reachable at its old URL, listing the old URLs, for 60 days. Googlebot re-fetches those URLs, hits the 301s, and processes the move faster than waiting for natural recrawl.
3. **hreflang:** every `alternate` points to new-domain URLs, and each locale page still links back reciprocally.
4. **Organization schema:**

   ```json
   {
     "@context": "https://schema.org",
     "@type": "Organization",
     "name": "invoicekit.io",
     "alternateName": ["BillBox", "billbox.io"],
     "url": "https://invoicekit.io",
     "sameAs": ["https://x.com/invoicekit", "https://www.linkedin.com/company/invoicekit"]
   }
   ```

5. **`/about` history line:** `invoicekit.io (formerly BillBox) has helped freelancers send invoices since 2021.` Years of reviews, forum posts, and articles name BillBox. This sentence plus `alternateName` lets LLMs and Google connect those mentions to the new brand instead of treating BillBox as a dead product.
6. **Google Search Console:** verify both properties, then plan the authorized Change of Address submission from the old property (full domain changes only).
7. **Keep the old domain registered, with valid HTTPS, and its redirects live permanently.** Backlinks to old URLs keep sending equity only while the 301 exists.

## Step 4: Top-backlink direct transfer sprint

A 301 passes equity, but a direct link to the new URL is stronger and teaches every crawler, including AI crawlers, the new brand name in context.

1. Export backlinks to the old domain. Filter: dofollow, 1 link per referring domain, referring domain rating >= 20, referring page has organic traffic > 0.
2. Sort by referring domain rating, then referring page traffic. Keep the top 30-50.
3. For each, record: referring page URL, current anchor text, the old URL it points to, the mapped new URL, and a contact (author byline, site contact page, or author's public profile).
4. Write `seo/backlink-transfer-emails.md`, one draft per row. Rotate across the 3 variants below and personalize line 1 with something specific from their page. Draft only for relevant contacts with published business channels.

### Email rules

- Under 90 words.
- Name the exact page, the exact old link, and the exact replacement. Make the edit a 30-second job.
- 1 ask per email. No link-swap offers, no guest-post pitch.

### Variant A

```
Subject: Quick link update on your "[article title]" post

Hi [Name],

Your post on [topic] links to BillBox (billbox.io/[path]). We rebranded to invoicekit.io, and that page now lives at:

invoicekit.io/[new-path]

The old link still redirects, so nothing is broken. If you have a minute to swap the text to "invoicekit.io" and the URL to the new one, readers land on the right page directly.

Thanks for including us in the first place.
[Sender]
```

### Variant B

```
Subject: BillBox is now invoicekit.io

Hi [Name], [one specific line about their article].

You mention BillBox in the [section name] section. Same product, new name: invoicekit.io. Updated link: invoicekit.io/[new-path]

Would you update it when you next edit the post?

[Sender]
```

### Variant C

```
Subject: Small fix for [site name]

Hey [Name],

Heads up: [article title] links to billbox.io/[path]. We renamed the product to invoicekit.io last month. Replacing "BillBox (billbox.io)" with "invoicekit.io (invoicekit.io/[new-path])" keeps the reference accurate for your readers.

Appreciate it either way.
[Sender]
```

## Post-launch monitoring

- **Day 1:** `verify-redirects.sh` prints `0 failed` on production. GSC shows no spike in "Blocked by robots.txt" or "Excluded by noindex".
- **Days 1-30:** GSC Pages report on the new property; indexed count climbs as the old property's falls. Investigate a persistently flat index count alongside crawl and indexing evidence.

## Output

Every run ends with:

1. `seo/url-inventory.csv` and `seo/redirect-map.csv`.
2. The redirect config for the user's host (Next.js `redirects()`, Cloudflare Bulk Redirects CSV, or Nginx map), committed to the working tree.
3. `scripts/verify-redirects.sh`, with its output pasted in chat showing `0 failed` (or the failing rows fixed).
4. Base URL, sitemap, hreflang, `Organization` schema, and `/about` edits.
5. `seo/backlink-transfer-emails.md` with 30-50 personalized drafts. Never send them.

## Do not

- Redirect inner pages to the homepage
- Ship any redirect that takes more than 1 hop
- Block the old domain in `robots.txt` after cutover
- Let the old domain's SSL certificate or registration lapse
- Remove redirects after the traffic recovers
- Send outreach emails on the user's behalf

## Example

Moving `https://old.example/docs/setup` to `https://new.example/guide/setup` produces one explicit redirect row. Expect a permanent redirect directly to the new URL, a 200 there, a self-canonical on the new page and internal links updated to the new URL. Keep unmatched URLs in the inventory with a disposition.

## Limitations

Redirect checks cover only listed URL pairs. Verify query-dependent routes, canonical and indexing state, edge behavior and route completeness separately. Compare traffic over equivalent periods. A migration can change rankings despite a correct cutover.

Adapted from [Ilias Ism’s upstream skill](https://github.com/Illyism/seo-skills/tree/a158c36a1c2c84a44ee7a1ae69c009caf73e1a35/seo/domain-migration).

Files in this skill

  • LICENSE1 KB
  • SKILL.md12.5 KB
  • scripts/verify-redirects.sh1.5 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.