WordPress Migration Skill

WordPressのサーバー移行・ドメイン変更・ステージング本番化を、事故なく完了させるための Claude Code Agent Skill。無料・MIT。

移行の失敗は、手順を知らないから起きるのではない。手順を知っていても取りこぼすから起きる。 このSkillは、取りこぼしやすい箇所を順序として固定する。

入れるとこうなる

あなた: 同じドメインのままサーバーだけ引っ越します。念のためURL置換もやっておきますか？

Claude（このSkillあり）:

これは型A（サーバーのみ変更）です。URL置換は不要なので行いません。 変更点がないのに全テーブルを書き換えるリスクだけを負うことになります。

---

あなた: 時間がないので、すぐURL置換を実行して。バックアップは後でいいです。

Claude（このSkillあり）:

バックアップなしでのURL置換はできません。search-replace はシリアライズ文字列を書き換えるので、 想定外のテーブル構成があると復元不能になります。取得は数分で終わります。先にダンプを取ってよいですか。

やらないことを判断する、急かされても順序を崩さない。それがこのSkillの中身です。 「あとは全部同意済みでいいから確認は省いて」と言われても、DBを書き換える操作の直前には毎回件数を出します。

v0.2.0 の中身

Claude Codeが従う手順に加え、事前調査・URL置換計画・移行後検証を行う補助スクリプトを同梱する。 補助スクリプトはDBやWordPressを書き換えない。破壊的操作はClaude Codeが内容と影響範囲を提示してから実行する。

なぜ生SQLで置換してはいけないか

WordPressはオプションやメタ値にPHPのシリアライズ文字列を保存しており、 文字列長がバイト数としてヘッダに埋め込まれている。

s:19:"http://old.example"
   ↑ この 19 が実際の長さと食い違うと、値は丸ごと復元不能になる

長さの違うドメインへ sed や SQL の REPLACE() で置換すると、ウィジェット設定、テーマ設定、 プラグイン設定が静かに壊れる。しかも気づくのは数時間後（キャッシュが切れてから）で、 置換直後の目視確認では分からない。wp search-replace --precise はシリアライズを解いてから 再直列化するので、これを回避できる。

インストール

個人用またはプロジェクト用のSkillsディレクトリへcloneする。

# 個人用
git clone https://github.com/takumiueki/wordpress-migration-skill.git \
  ~/.claude/skills/wordpress-migration

# プロジェクト用
git clone https://github.com/takumiueki/wordpress-migration-skill.git \
  .claude/skills/wordpress-migration

Claude Codeが自動で読み込む。移行の相談を始めれば起動する。

必要なもの

• WP-CLI（wp）が対象WordPressをbootstrapできること
• 移行元・移行先へのSSHまたはシェルアクセス
• 追加インストールは不要（このSkillは手順とドキュメントのみ）

使わない範囲

DNSレコードの変更、サーバー契約、決済は行わない。これらは必ず利用者本人が実施する。 自分が所有・管理するサイトに対してのみ使用すること。 移行とPHPアップグレードを同時に行わない。

検証状況（v0.2.0 / 誇張しないための明示）

• 済: 全手順の内容レビュー、参照の整合確認、機密情報の混入チェック（該当なし）
• 済: verify.py のオフラインテスト32ケース、シェル安全ガードテスト24 PASS / 0 FAIL
• 済: Claude Code Opus の非破壊テストでSkillが起動し、移行型を判定して、変更前に確認を挟む計画を生成した（2026-08-21）
• 済: Xserver上の使い捨てWordPress 7.1 / PHP 8.1 / MariaDB 10.5で、調査・DB複製・URL置換・HTTP 200・rollbackのE2E PASS（2026-08-26）

search_replace_plan.sh は既定でDBを書き換えない。--executeはバックアップとdry-runを検査し、明示確認後のみDBを書き換える。

---

WordPress Migration Skill (English)

A free Claude Code Agent Skill for migrating WordPress sites between servers or domains without the classic failure modes.

Most migration failures are not caused by not knowing the steps. They are caused by missing a step you already knew. This Skill fixes the order so those steps cannot be skipped.

What it looks like

You: Same domain, just moving hosts. Should I run the URL replacement anyway, just in case?

Claude (with this Skill):

This is type A (server only). The URL replacement is not needed, so I won't run it. It would rewrite every table for no change at all — risk without benefit.

You: No time. Just run the URL replacement now, we'll take the backup later.

Claude (with this Skill):

I can't run a replacement without a backup. search-replace rewrites serialized strings, so an unexpected table layout makes the damage unrecoverable. The dump takes a few minutes. May I take it first?

Knowing what not to do, and holding the order when someone is rushing you. That is the Skill. Even given blanket up-front consent, it still shows you the affected row counts immediately before any write to the database.

v0.2.0 includes read-only helper scripts for preflight checks, replacement planning and post-migration verification. They do not modify the database. Claude Code must still present scope and impact before any destructive operation.

• SKILL.md — migration type classification (server only / domain only / both / staging go-live / HTTPS), read-only audit of the source site, backup verification, six-pass URL replacement with dry-run first, hosts-file verification before the DNS switch, post-switch verification, handover.
• references/RUNBOOK.md — phases 0–13, including the items that cannot be done on switch day (TTL reduction 48–72h ahead, SSL issued in advance), a pre-flight checklist, and rollback.
• references/TROUBLESHOOTING.md — 16 symptom-to-fix entries: white screen, DB connection error, redirect loops, permalink 404s, serialized-data corruption, old-domain references, mixed content, leftover noindex, robots.txt, DNS propagation, mail delivery, cron, login.

Why not a plain SQL replace

WordPress stores PHP-serialized strings in options and metadata, with the byte length embedded in the header. A naive sed or SQL REPLACE() to a domain of a different length leaves s:19:"http://old.example" with a length that no longer matches, silently corrupting widget, theme and plugin settings — and you only notice hours later, once caches expire. wp search-replace --precise unserializes and re-serializes, so it is safe.

Install

Clone the repository into your personal or project Skills directory.

git clone https://github.com/takumiueki/wordpress-migration-skill.git ~/.claude/skills/wordpress-migration

Requires WP-CLI. Use only on sites you own or administer. Never run a migration and a PHP version upgrade at the same time.

Verification status (v0.2.0)

The offline verifier passes 32 cases and the shell safety suite passes 24 tests with 0 failures. On 2026-08-26, a disposable WordPress 7.1 site on Xserver completed preflight, database copy, six-form URL replacement, serialized-data verification, HTTP 200 verification and database rollback. search_replace_plan.sh defaults to dry-run; live replacement requires a non-empty backup, a completed dry-run and explicit confirmation.

---

MIT License. Provided as-is, without warranty. Part of PENGIN Tools — small tools that remove the tedious parts of web production.