agentleFS
keuperakeupera/seo-skills/skills/redirect-migration-plan/SKILL.md

redirect-migration-plan

Skill0 starsChanged 2 months agoMITView on GitHub

Plan and execute a site migration, replatform, domain change or URL restructure without losing rankings, including the redirect map and the rollback. Use whenever the user mentions site migration, replatforming, domain change, URL restructure, changing a CMS, merging two sites, HTTPS migration, redirect map, 301 versus 302, redirect chains, or reports a traffic collapse after a relaunch. Also use before any change that alters URLs.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask it once, plainly. A lot of URL restructures are driven by an aesthetic preference for tidier paths, and the SEO value of tidier paths …

    line 14
  2. Distinctive:

    If it goes ahead, change one thing at a time.

    line 18
  3. Very specific:

    Every redirect goes to the final destination in one hop: If /a → /b and later /b → /c, update the first rule to /a → /c.

    line 77
  4. Distinctive:

    Redirects live at the moment the new site is: Not an hour later.

    line 97
  5. Very specific:

    Remove noindex from production: Check it. Then check it again.

    line 98
  6. Distinctive:

    Use the Change of Address tool: if the domain changed. It's the fastest signal available and it's free.

    line 101
  7. Distinctive:

    Keep the old site deployable for at least a month.

    line 126
  8. Distinctive:

    Keep the old domain registered and redirecting indefinitely.

    line 130
  9. Very specific:

    Update the entity data — social profiles, business listings, sameAs in schema, documentation, anywhere the old domain is cited.

    line 132

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Redirects and Site Migrations

Migrations are the highest-risk routine work in SEO. A site that has taken four years to build can lose most of its organic traffic in a week, and the cause is almost always the same: URLs changed and the redirects were incomplete, chained, or pointed somewhere generic.

The good news is that a migration done properly loses very little. The work is unglamorous and entirely front-loaded.

Before anything: is this migration necessary?

Ask it once, plainly. A lot of URL restructures are driven by an aesthetic preference for tidier paths, and the SEO value of tidier paths is close to zero.

Migrate when: the domain is genuinely changing, the platform can't do the job, two sites are merging, or the current structure actively blocks growth. Don't migrate to move /blog/2019/03/post-title to /blog/post-title unless something else is already forcing a rebuild.

If it goes ahead, change one thing at a time. Domain, structure, platform and design all at once means that when traffic drops you have no idea which change caused it.

Step 1: Inventory everything, before you touch anything

You cannot redirect URLs you don't know about. Gather from all four sources, because each misses things the others catch:

# 1. The sitemap — what the site thinks it has
curl -s https://old.example.com/sitemap.xml | grep -oP '(?<=<loc>)[^<]+' > urls-sitemap.txt

# 2. A full crawl — what's actually linked
#    (any crawler; the point is coverage, not the tool)

# 3. Search Console — what Google has and sends traffic to. Export 16 months of pages.
# 4. Analytics — what has ever received a visit. Export 24 months of landing pages.
# 5. Backlink data — pages other sites link to. These matter most and are often orphaned.

sort -u urls-*.txt > urls-all.txt
wc -l urls-all.txt

The fourth and fifth sources are where the value is. Old pages with backlinks, no internal links and steady traffic are exactly the ones a crawl misses and exactly the ones that hurt most when lost.

Step 2: Build the redirect map

One row per old URL. No exceptions, no "the rest go to the homepage".

old_url, new_url, status, notes
/old-path/thing, /new-path/thing, 301, direct match
/blog/2019/03/post, /blog/post, 301, date removed
/discontinued-product, /category/replacements, 301, closest equivalent
/genuinely-dead-page, , 410, no traffic, no links, deliberate

Matching rules:

  • One-to-one wherever possible. The new page should serve the same intent as the old one.
  • No closest equivalent? Use the parent category, not the homepage. Redirecting everything to the homepage is treated as a soft 404 and passes nothing.
  • Genuinely dead content with no links and no traffic gets a 410, deliberately. It's a cleaner signal than a redirect to something irrelevant.
  • Never redirect many-to-one at scale. Consolidating 500 old URLs onto one page looks like an attempt to funnel equity and gets discounted.
  • 301 for permanent, 302 only for genuinely temporary. A 302 left in place for a year is a bug.

Validate the map before launch. Every new_url must return 200 on the staging build. A redirect map full of destinations that 404 is the second most common failure mode.

Step 3: The redirect rules themselves

Pattern rules for the bulk, explicit rules for the exceptions. Keep the file ordered so specific rules come before general ones.

# Specific first
location = /old-pricing { return 301 https://example.com/pricing; }

# Then patterns
location ~ ^/blog/[0-9]{4}/[0-9]{2}/(.*)$ { return 301 https://example.com/blog/$1; }

The rules that prevent chains:

  • Every redirect goes to the final destination in one hop. If /a → /b and later /b → /c, update the first rule to /a → /c. Don't leave the chain.
  • Watch for the double redirect on protocol and host. http://old.com/a should reach https://new.com/b in one hop, not four.
  • Preserve query strings where they matter, drop them where they don't, and decide deliberately.
  • Keep redirects forever. Links and bookmarks don't expire. Removing them a year later loses everything they were carrying.

Verify each one:

while IFS=, read -r old new status _; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -I "https://example.com$old")
  final=$(curl -s -o /dev/null -w '%{url_effective}' -IL "https://example.com$old")
  hops=$(curl -s -o /dev/null -w '%{num_redirects}' -IL "https://example.com$old")
  printf '%s\t%s\t%s hops\t%s\n' "$old" "$code" "$hops" "$final"
done < redirect-map.csv | awk -F'\t' '$3 != "1 hops" || $2 !~ /30[18]/'

Anything that prints is a problem. An empty output means the map is clean.

Step 4: Launch day, in order

  1. Redirects live at the moment the new site is. Not an hour later.
  2. Remove noindex from production. Check it. Then check it again. This is the single most common catastrophic launch bug.
  3. Check robots.txt isn't the staging version with Disallow: /.
  4. Submit the new sitemap in Search Console. Keep the old sitemap accessible for a few weeks so Google recrawls the old URLs and discovers the redirects.
  5. Use the Change of Address tool if the domain changed. It's the fastest signal available and it's free.
  6. Verify both properties in Search Console, old and new, and keep the old one for a year.
  7. Update internal links to the new URLs directly. Internal links pointing at redirects work but waste crawl budget and look unmaintained.
  8. Tell the ad, email and social teams. Their links break too.

Step 5: The two weeks after

Expect a dip. A 10 to 20% drop for two to four weeks is normal on a clean migration as Google recrawls and reassigns. It recovers.

What's not normal, and what to watch daily:

SignalWhereMeans
404s climbingSearch Console Pages report, server logsRedirect map has holes. Fix same day
Old URLs still indexed after 4 weekssite: search, Pages reportRedirects not being seen. Check they're 301 not JS
Crawl rate collapsedCrawl statsServer errors or robots blocking
Traffic down 50%+AnalyticsSomething structural. Roll back and diagnose
Rankings gone for one sectionSearch Console queriesThat section's redirects are broken

Pull the top 404s from logs every day for the first fortnight and add them to the map. There are always URLs the inventory missed.

Rollback

Decide the rollback plan and the trigger before launch, in writing. "We revert if organic sessions are down more than 40% at day 5" is a decision that's much easier to make in advance than at 2am.

Keep the old site deployable for at least a month.

Domain changes specifically

  • Keep the old domain registered and redirecting indefinitely. Not for a year. Indefinitely. It's a small annual fee against permanent loss of every link ever built.
  • Redirect at the URL level, not the domain level. old.com/pricing → new.com/pricing, not old.com/* → new.com/.
  • Update the entity data — social profiles, business listings, sameAs in schema, documentation, anywhere the old domain is cited. See entity-brand-consistency.
  • Expect a longer recovery than a same-domain restructure. Two to three months is normal.

Don't do these

  • Don't redirect everything to the homepage. Soft 404s, no equity, and a bad experience.
  • Don't use meta refresh or JavaScript redirects. Slow to be picked up and inconsistently honoured.
  • Don't change URLs and content at the same time. You lose the ability to diagnose.
  • Don't launch on a Friday.
  • Don't delete the old sitemap immediately. Google needs to recrawl the old URLs to find the redirects.
  • Don't remove redirects after "enough time". There's no such point.

Related skills

technical-seo-audit, canonical-duplicate-content, internal-linking-architecture, search-console-analysis, content-refresh, entity-brand-consistency

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.