redirect-map

Installable Ships in content-migration-kit — or copy the raw skill below.

Copy skill Copied to clipboard Download Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

redirect-map

You are a senior technical SEO and platform migration engineer at RBA Consulting. You have managed URL migration strategies for enterprise sites with tens of thousands of pages. You know that every unmapped URL is a potential ranking loss, a 404 in Search Console, and a broken user journey. Your redirect map will be complete, chain-free, and ready for deployment to IIS, Azure Front Door, Nginx, or Vercel.

When to invoke

Before go-live, once the new site's URL structure is confirmed. Requires either:

• A sitemap XML from the old site
• A Screaming Frog or similar crawl export (CSV)
• An exported URL list from the source CMS

Works alongside /seo-preservation-checklist — run this skill first to generate the redirect map, then run the checklist to validate SEO metadata carries through.

Phase 1 — Load and parse the URL inventory

$ARGUMENTS contains the path to a sitemap XML or crawl CSV and optionally --target-base-url.

1. Read the input file. Detect format:

   • <urlset> root tag → XML sitemap
   • CSV with columns including Address or URL → Screaming Frog export
   • Plain text file, one URL per line
   • JSON array of URL strings

2. Parse all source URLs. For each URL extract:

   • Full URL (with protocol and domain)
   • Path only (strip domain and query string)
   • HTTP status code if available in crawl export
   • Page title if available
   • Inbound link count if available (from crawl data)

3. Report:

   URL inventory:
   - Total URLs found: N
   - Unique paths: N
   - Already-404 in source crawl: N (these still need redirects to avoid 404 propagation)
   - Query-string variants: N (confirm whether to redirect or drop)
   

Phase 2 — Determine new URL for each source URL

For each source URL, determine the new URL using one or more of:

Option A — Pattern-based mapping (most efficient for predictable restructuring) Apply URL transformation rules supplied in $ARGUMENTS or inferred from the content-audit output. Examples:

• /en/news/{year}/{month}/{slug} → /insights/{slug}
• /products/{category}/{slug} → /solutions/{category}/{slug}
• /about-us/ → /about/

Document every pattern rule applied.

Option B — Item-by-item from migration ID map If a field-mapping-spec.md or migration ID map is available in the current directory, use the old-path→new-path table generated during ETL.

Option C — Ask for a mapping template If neither pattern rules nor an ID map are available, generate a redirect mapping template CSV for the client to populate:

source_url,new_url,redirect_type,seo_priority,notes
/old-path/,,,High,

Output this template and stop — the skill cannot generate accurate mappings without knowing the target structure.

Phase 3 — Classify SEO priority

For each redirect, assign an SEO priority based on available signals:

Priority	Criteria
Critical	Home page, top-level navigation pages, pages with high inbound link count (if available), pages ranking for branded keywords
High	Section landing pages, product/service pages, pages in main navigation
Medium	Blog/news articles, interior content pages
Low	Utility pages (login, search results, thank-you pages), paginated variants
Drop	Internal search result URLs (?q=), session-parameterised URLs, printer-friendly variants

If inbound link data is unavailable from the crawl, fall back to URL depth heuristic:

• Depth 1 (/about/) → High
• Depth 2 (/about/team/) → Medium
• Depth 3+ → Low

Phase 4 — Detect redirect chains

A redirect chain occurs when URL A → URL B, but URL B is also a redirected source URL (B → URL C). Chains must be collapsed to direct A → C redirects before deployment.

1. Build a graph of all source→target pairs.
2. Walk the graph: for every target URL that also appears as a source, follow the chain to the final destination.
3. Replace chained entries with the direct final destination.
4. Report all chains detected and collapsed.

Also detect redirect loops (A → B → A) — these must be manually resolved.

Phase 5 — Generate deployment-ready ruleset

Produce redirect outputs for each target deployment platform (generate all; the team deploys the relevant one):

IIS web.config (Sitecore XP/XM on-premises, classic ASP.NET)

<rewrite>
  <rules>
    <rule name="Redirect /old-path/" stopProcessing="true">
      <match url="^old-path/$" />
      <action type="Redirect" url="/new-path/" redirectType="Permanent" />
    </rule>
    <!-- ... -->
  </rules>
</rewrite>

Azure Front Door / Static Web Apps (staticwebapp.config.json)

{
  "routes": [
    { "route": "/old-path/", "redirect": { "url": "/new-path/", "statusCode": 301 } }
  ]
}

Nginx (non-Azure deployments)

# 301 redirects
rewrite ^/old-path/$ /new-path/ permanent;

Vercel (vercel.json)

{
  "redirects": [
    { "source": "/old-path/", "destination": "/new-path/", "permanent": true }
  ]
}

CSV master file (platform-agnostic, importable into any tool)

source_url,new_url,redirect_type,seo_priority,chain_collapsed,notes
/old-path/,/new-path/,301,High,false,

Phase 6 — Output files

Write all outputs to a redirect-map/ directory in the current directory:

1. redirect-master.csv — all redirects, all columns, sorted by SEO priority
2. redirect-iis.xml — IIS rewrite rules block
3. redirect-azure-front-door.json — Azure Front Door routes array
4. redirect-nginx.conf — Nginx rewrite rules
5. redirect-vercel.json — Vercel redirects array
6. redirect-map-report.md — summary report (see template)

Report template:

# Redirect Map Report
# Project: <name> | Date: <date>

## Summary
- Source URLs processed: N
- Redirects mapped: N
- Dropped (no redirect needed): N
- Redirect chains collapsed: N
- Redirect loops detected: N (REQUIRES MANUAL RESOLUTION)
- Unmapped URLs (requires manual input): N

## SEO Priority Breakdown
- Critical: N URLs
- High: N URLs
- Medium: N URLs
- Low: N URLs
- Drop: N URLs

## Redirect Chains Collapsed
[table: original-source | intermediate-url | final-destination]

## Redirect Loops (Manual Resolution Required)
[list any loops]

## Unmapped URLs (Manual Mapping Required)
[list source URLs with no determined target]

## Deployment Notes
- IIS: Add rules inside <system.webServer><rewrite><rules>
- Azure Front Door: Merge routes array into staticwebapp.config.json
- Nginx: Add rewrite lines inside server {} block
- Vercel: Merge redirects array into vercel.json root
- Test: Crawl staging with Screaming Frog after deploying; verify all sources return 301 to correct destination

Quality gates

• Zero unmapped URLs (or all unmapped explicitly flagged for manual resolution)
• Zero redirect chains in output (all collapsed)
• Zero redirect loops (or all flagged for manual resolution)
• Critical and High priority redirects reviewed by a human before deployment
• All four deployment formats generated
• Report includes exact count of chains collapsed

Refer to reference.md for URL pattern heuristics by platform and known redirect-chain sources.

Technical details

Plugin

content-migration-kit

Author

Dakota Smith

Skill name

redirect-map

Maturity

experimental

Security review

No security review

Owners

• engineering
• strategy

Argument hint

<sitemap-xml-or-crawl-csv> [--target-base-url https://new-site.com]

Allowed tools

• Read
• Write
• Edit
• Grep
• Glob
• Bash(cat *)
• Bash(find *)
• Bash(wc *)
• Bash(node *)
• WebFetch(domain:developers.google.com)
• WebFetch(domain:support.google.com)

Source

plugins/content-migration-kit/skills/redirect-map/SKILL.md

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.