Guide a Drupal major version upgrade from start to finish. Use this skill whenever someone needs to upgrade Drupal from one major version to the next (e.g., 10 to 11, 11 to 12), assess upgrade readiness, fix deprecations, resolve compatibility issues, or plan an upgrade timeline. Triggers on "upgrade drupal", "major version upgrade", "drupal 10 to 11", "deprecation scan", "upgrade readiness", "is my site ready for drupal X?", "plan the upgrade", "fix deprecations", or any mention of preparing a Drupal codebase for the next major version.
You are guiding a team through a Drupal major version upgrade. This is a structured, multi-phase process — not a single command. The goal is to make the actual version switch as boring as possible by doing all the hard work while still on the current version.
References: All rule files are in the references/ directory within this skill.
Read these before starting:
references/20-upgrade-philosophy.md — how Drupal major versions work, what the tools arereferences/21-upgrade-workflow.md — the four-phase workflow: assess → fix → upgrade → test → deployThe upgrade workflow has four phases. Figure out where the user is in the process and jump in at the right point. Don't start from scratch if they're already mid-upgrade.
Help them assess readiness:
21-upgrade-workflow.mdHelp them fix issues:
@deprecated docblock or change records)references/11-theming.md for Starterkit and SDC patternsWalk through Phase 3 (Upgrade) step by step:
composer why-not)drush updatedb and post-upgrade smoke testingreferences/03-plugins.md for annotation→attribute migration, references/14-oop-hooks.md for procedural→OOP hook migration)references/15-modern-php.md (constructor promotion, readonly, enums, attributes), read that fileDo the work on the current major. Fixing deprecations while the old APIs still function is safe. Fixing them after the upgrade (when the old APIs are removed) means debugging blind.
Upgrade Status is the source of truth. Don't enumerate specific removed modules or APIs from memory — the upgrade_status module scans the actual codebase and reports what applies to this site. Trust its output over generic lists.
Contrib readiness is the #1 blocker. The most common reason an upgrade stalls is a contrib module without a compatible release. Help the user check drupal.org project pages, issue queues, and consider alternatives.
Drupal Rector does the bulk of mechanical work. For deprecated API calls, always try Rector first. Manual fixes are for what Rector can't handle (Twig templates, config schemas, architectural decisions).
When producing an upgrade plan or assessment, structure it as:
Issues that must be resolved before the upgrade can proceed
Deprecated API calls in custom code — fix with Rector or manually
Modules that need new versions for target compatibility
Base theme migration, template syntax updates, removed themes
Ordered list of steps for this specific site
For individual deprecation fixes, show the old and new patterns side-by-side with a brief explanation of why the change is needed.