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.
In this repository29 other files it gives its agents.
- ai-bot-log-analysisSkill
- ai-crawler-policySkill
- ai-visibility-auditSkill
- best-of-listicle-pagesSkill
- canonical-duplicate-contentSkill
- comparison-alternatives-pagesSkill
- content-refreshSkill
- core-web-vitalsSkill
- ecommerce-seoSkill
- eeat-author-pagesSkill
- entity-brand-consistencySkill
- featured-snippet-passagesSkill
- glossary-definition-hubSkill
- hreflang-international-seoSkill
- image-seoSkill
- internal-linking-architectureSkill
- keyword-cannibalizationSkill
- keyword-research-briefsSkill
- link-building-outreachSkill
- local-seoSkill
- nextjs-seoSkill
- programmatic-seoSkill
- schema-markupSkill
- search-console-analysisSkill
- shopify-seoSkill
- technical-seo-auditSkill
- topical-authority-mapSkill
- video-seoSkill
- wordpress-seoSkill
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
- Distinctive: line 14
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 …
- Distinctive: line 18
If it goes ahead, change one thing at a time.
- Very specific: line 77
Every redirect goes to the final destination in one hop: If /a → /b and later /b → /c, update the first rule to /a → /c.
- Distinctive: line 97
Redirects live at the moment the new site is: Not an hour later.
- Very specific: line 98
Remove
noindexfrom production: Check it. Then check it again. - Distinctive: line 101
Use the Change of Address tool: if the domain changed. It's the fastest signal available and it's free.
- Distinctive: line 126
Keep the old site deployable for at least a month.
- Distinctive: line 130
Keep the old domain registered and redirecting indefinitely.
- Very specific: line 132
Update the entity data — social profiles, business listings, sameAs in schema, documentation, anywhere the old domain is cited.
≈ “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.
Files
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.txtThe 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, deliberateMatching 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→/band 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/ashould reachhttps://new.com/bin 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
- Redirects live at the moment the new site is. Not an hour later.
- Remove
noindexfrom production. Check it. Then check it again. This is the single most common catastrophic launch bug. - Check
robots.txtisn't the staging version withDisallow: /. - 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.
- Use the Change of Address tool if the domain changed. It's the fastest signal available and it's free.
- Verify both properties in Search Console, old and new, and keep the old one for a year.
- Update internal links to the new URLs directly. Internal links pointing at redirects work but waste crawl budget and look unmaintained.
- 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:
| Signal | Where | Means |
| 404s climbing | Search Console Pages report, server logs | Redirect map has holes. Fix same day |
| Old URLs still indexed after 4 weeks | site: search, Pages report | Redirects not being seen. Check they're 301 not JS |
| Crawl rate collapsed | Crawl stats | Server errors or robots blocking |
| Traffic down 50%+ | Analytics | Something structural. Roll back and diagnose |
| Rankings gone for one section | Search Console queries | That 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, notold.com/*→new.com/. - Update the entity data — social profiles, business listings,
sameAsin schema, documentation, anywhere the old domain is cited. Seeentity-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
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
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.

