WordPress to Astro Migration Skill
A Claude Code skill for migrating WordPress blogs to Astro static sites. Built from real migrations across multiple sites — a personal blog with 180+ posts (pmillerd.com), a book/podcast site with 120+ posts (pathlesspath.com), a bilingual podcast/blog (angiecreates.io), and a consulting content site (strategyu.co).
What This Skill Does
When you invoke /wordpress-to-astro in any project, Claude gets loaded with the full migration playbook: a 7-phase pipeline, ready-to-customize script templates, and a troubleshooting guide covering dozens of real issues.
Claude will walk you through the migration step by step, asking the right questions upfront and adapting scripts to your specific site.
Install
Personal (just you):
# Copy skill files to your local Claude skills directory
mkdir -p ~/.claude/skills/wordpress-to-astro
# Then copy SKILL.md, migration-scripts.md, common-issues.md, post-migration-patterns.md into it
As a plugin (shareable):
/install github:paulmil11/wordpress-blog-to-astro-skill
How It Works
The Migration Pipeline
The skill guides Claude through 7 phases, run in order:
-
Extract — Parse your WordPress XML export into structured JSON. Pulls out titles, slugs, dates, categories, tags, featured images (via _thumbnail_id postmeta lookup), and full HTML content.
-
Convert — Transform WordPress HTML to clean Markdown using Turndown with custom rules. Preserves YouTube/podcast/Substack embeds as raw HTML. Strips WordPress block comments, spacer blocks, and page builder wrappers. Generates YAML frontmatter with dual date fields (date for display, rawDate for sorting).
-
Download Images — Scan all markdown for external image URLs, download them locally to public/images/posts/, and rewrite all references. Handles CDN redirects (up to 5 hops), tracks failures, and is idempotent (safe to re-run).
-
Clean Up — Remove boilerplate (host social links, platform CTAs, subscription prompts) while intelligently preserving guest content. Standardize categories. Fix broken links from old domains. Normalize percent-encoded CJK filenames. Fix protocol-relative URLs in embeds. Convert bare Twitter/X URLs to markdown links.
-
Generate Missing Content — Auto-create landing pages for content that exists in external feeds (podcast RSS, newsletters) but has no blog post yet. Match by episode number, inject embed players.
-
Build & Deploy — Verify the Astro build, configure platform-specific redirects (Netlify _redirects, Vercel vercel.json, Cloudflare Pages), and deploy. For domain migrations, generate WordPress Redirection plugin CSV for the old site.
-
Post-Migration Polish — Fix remaining broken internal links, build standalone pages from old site content (coaching, reading lists, tools pages), implement dark mode, add blog page features (category filtering, search, sort by reading time), visual polish (gradient transitions, responsive layouts).
What Claude Asks You First
Before writing any code, the skill prompts Claude to ask about your specific setup:
| Question | Why It Matters |
|---|
| Source platform — WordPress.com or self-hosted? | Affects XML export structure and image URL patterns |
| Hosting target — Cloudflare Pages, Vercel, or Netlify? | Determines redirect config format and deploy setup |
| Content types — Blog only? Podcast? Events? Portfolio? | Controls which scripts get created |
| Languages — Monolingual or multilingual? | Affects filename handling, reading time calculation, regex patterns for cleanup |
| Old domain — Need redirects from old URLs? | Creates redirect mapping from WordPress slugs |
| External feeds — Podcast RSS? Newsletter? | Enables auto-generation of missing content pages |
| Embeds — YouTube, podcast players, Instagram, Substack? | Configures Turndown custom rules to preserve specific embed types |
| Dark mode — Light/dark theme toggle? | CSS custom properties + [data-theme] attribute approach |
| Blog features — Category filtering, search, sort, stats? | Inline JS on blog index page |
Key Architecture Decisions
The skill encodes opinions that come from doing this multiple times:
respira-press