Umbraco Upgrade Skill

Umbraco upgrades have a reputation. Any development team that has shepherded a site from one major version to the next will know the feeling: hours of readiness audits, package incompatibility rabbit holes, content schema migrations, and a backoffice that looks entirely different on the other side. For Umbraco v13 to v17, the scale of that challenge is significant — four intervening major versions, a complete backoffice rewrite at v14, and a Block Editor auto-migration at v15 that can take several minutes on a large content tree.

We decided to do something about it. We've built a Claude Code skill that orchestrates the entire upgrade process — from initial codebase audit through to a reviewed, verified pull request — with the rigour a major version jump demands but without the week-long slog.

What is a Claude Code skill?

Claude Code is Anthropic's agentic coding tool — it runs in your terminal, reads and writes files, executes commands, and can be given structured instructions via reusable skills. A skill is essentially a detailed prompt file that defines a workflow: what to check, what to do, what to refuse, and in what order. Think of it as a very experienced developer with a very good memory, working through a checklist you've spent considerable time perfecting.

Our Umbraco upgrade skill is one of a growing library we've built for common but high-effort development tasks. It lives in our internal skills directory and can be invoked with a single slash command: /umbraco-major-upgrade 13 17. What follows is hours of careful, automated engineering work.

Why v13 to v17 is genuinely complex

Umbraco v13 and v17 are both Long Term Support releases. The four versions in between — v14, v15, v16, and the latest v17 — each introduced meaningful breaking changes. The good news is that Umbraco's migration runner means you can jump directly from 13 to 17 in a single boot, with every intermediate migration applied automatically in order. The less good news is that you still have to reckon with everything that changed across those four versions before that boot happens.

The headline challenges are:

• The v14 backoffice rewrite. The entire backoffice was rebuilt from AngularJS to Web Components. Every custom extension in App_Plugins/ stops working at v14 and needs porting. The site may still boot, but editors will find blank panels where their dashboards and property editors used to be.
• The v15 Block Editor migration. All Block Editor content is automatically rewritten to a new internal format on first boot. On a large content tree, this can take several minutes. Interrupting it leaves the database in a mixed state.
• API and namespace changes across every major. Types get moved, method signatures change, appsettings.json keys shift. On a direct jump from v13 to v17, none of these surface as gradual deprecation warnings — they all appear as compile errors at once.
• Package ecosystem gaps. Not every third-party package has a v17-compatible release. Knowing this before you bump the package version saves a lot of pain.

How the skill works

The skill is built around a strict sequence of steps, each with its own guardrails. Here's what it does from start to finish.

1. Preconditions

Before touching a single file, the skill reads the current Umbraco version directly from the .csproj — it doesn't trust what the developer tells it. It checks for a clean git working tree, confirms the database engine is supported, and refuses to proceed until a database backup has been explicitly confirmed. Major upgrades are not reversible; that confirmation step is non-negotiable.

2. Readiness audit

A companion skill — /umbraco-upgrade-readiness-audit — greps the entire codebase for every v13-specific pattern that breaks between v14 and v17. It produces a written report listing each issue by file, line, the major version that breaks it, and a suggested action. This runs before any code changes. If the report is substantial, the skill pauses and asks the developer to confirm scope before any package is bumped.

3. Applying fixes

Working from the readiness report, the skill applies all the code and config fixes it can handle automatically: renamed namespaces and APIs, appsettings.json key changes, startup and composer registration updates, and mechanical code rewrites with a clear path. These land as a dedicated commit, separate from the package bump, so they're reviewable and revertible on their own.

Content-schema transformations — Grid to Block Grid, Nested Content to Block List — are deliberately not auto-applied. They have real blast radius and go through a gated path using uSyncMigrations, or a human edit. The skill routes them there rather than silently rewriting content models.

4. Direct jump or stepped mode

The default path is a single direct jump from v13 to v17 — one branch, one package bump, one boot. This is Umbraco's sanctioned approach and the right choice for most sites.

For sites with a large custom backoffice extension surface, a very heavy content tree, or a codebase that leans heavily on APIs deprecated in intermediate versions, the skill can switch to stepped mode: one major at a time, a commit and smoke test after each hop. The choice is made based on what the readiness audit found, and the skill states its reasoning explicitly.

5. The upgrade itself

The skill creates a branch (upgrade/umbraco-v17), bumps Umbraco.Cms and every sub-package to the latest v17 patch, updates <TargetFramework> from net8 to net10, and runs dotnet restore && dotnet build. Build errors that only surface once the v17 packages are present are fixed here against the readiness report.

Before the first boot, any custom backoffice extensions are ported via a sibling skill. Then the site boots once, and the skill tails the logs watching for migration plan lines. It stops immediately on any error or exception — a partial migration is worse than no migration.

6. Verification and PR

Once the smoke test passes (homepage 200, backoffice login, content tree loads), a full verification run compares pre- and post-upgrade API parity, backoffice end-to-end tests, and content integrity. The result feeds directly into the PR body, alongside a summary of every breaking change surfaced across the v13 to v17 span. The skill will not push directly to a protected branch. It opens a PR and requests review.

What the skill won't do (and why that matters)

Good automation knows its limits. The skill is deliberately opinionated about what it won't touch without human sign-off:

• Content-schema transformations are never silently applied. Grid to Block Grid and Nested Content to Block List migrations go through uSyncMigrations with a review step, not a quiet automated rewrite.
• Database backups are not automated. The skill refuses to proceed until a human confirms they have one. Backups need judgement about where, when, and what counts as a good restore point.
• Protected branch pushes don't happen without explicit approval. A major upgrade is a multi-commit PR, not a direct push to main.
• Low-confidence fixes are surfaced and proposed, not applied. If the readiness audit marks something as needing human judgement, the skill asks rather than guesses.

This isn't timidity — it's the right model for work with real blast radius. The goal is to handle everything that can be handled confidently and automatically, while being clear about the decisions that need a human in the loop.

Part of a broader skills library

The Umbraco upgrade skill doesn't exist in isolation. It's part of a growing library of Claude Code skills we're building to handle the high-effort, high-stakes tasks that development teams do repeatedly — the kind of work where experience and process matter as much as raw execution speed.

Sibling skills include a standalone readiness audit you can run at any time without committing to an upgrade, a backoffice extension migration tool for porting v13 AngularJS extensions to v14+ Web Components, a minor version upgrade skill for v17.x patch updates, and a full verification skill that runs a test pyramid comparison across pre- and post-upgrade states.

Together they represent a meaningful shift in how upgrade and maintenance work gets done: less repetitive groundwork, more time spent on the decisions and quality checks that actually need human expertise.

What this means for your Umbraco site

Umbraco v13 reaches end of life in December 2026. For any business running on v13 today, the upgrade to v17 is a question of when, not whether. The skill makes that work significantly faster and more predictable — but it still requires the right technical context, a solid test environment, and a team that knows what it's reviewing in the PR.

If you're on Umbraco v13 and starting to think about the upgrade path, we'd be happy to talk through what's involved for your specific site. The readiness audit can be run independently as a first step, giving you a clear picture of scope before any commitment to the full upgrade.