Terminal
Terminal/Skill
Checks that your site's Umbraco major version matches the major these skills target before backoffice work begins.
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-backoffice-skills --skill umbraco-version-guardThe Umbraco backoffice API changes between majors (tree data sources, auth, OpenAPI registration, and more). These skills target one specific major. Applying them to a site on a different major produces confidently-wrong code.
This skill is a preflight check: it derives the target major from the plugin itself (so it never goes stale as new majors ship), detects the target site's major deterministically, compares them, and STOPS with the correct install command on a mismatch. Nothing here hardcodes a specific major number — both sides are computed.
The plugin's own version is the source of truth, and it bumps every major at release. Read it and take the leading number:
# Primary: the installed plugin's version. First path is the Claude Code plugin layout;
# the greps are fallbacks for when the skill was copied flat into an editor's skills dir.
cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null \
|| cat ../../.claude-plugin/plugin.json 2>/dev/null \
| grep -m1 '"version"' | grep -oE '[0-9]+' | head -1
Call this TARGET_MAJOR. If none of the paths resolve (a flat copy with no
plugin.json alongside), fall back to the marketplace version, and only then to reading
the value a sibling skill states — never invent a number. If you genuinely cannot
determine it, say so and skip the guard rather than guessing.
Try these signals in order and stop at the first that yields a number. Each extracts just
the major, so it works with 18.0.0, 18.*, [18.0.0,), or plain 18.
A. Umbraco.Cms package reference (ground truth — what is actually installed). Covers
*.csproj PackageReference and central-package-management *.props (PackageVersion); the
trailing " after Cms excludes Umbraco.Cms.DevelopmentMode etc.
grep -rhoE 'Umbraco\.Cms"[^0-9]*[0-9]+' --include='*.csproj' --include='*.props' . 2>/dev/null \
| grep -oE '[0-9]+$' | sort -u
B. Fallback — the backoffice client dependency major (handles ^18.0.0, ~18.0.0, 18.0.0):
grep -rhoE '"@umbraco-cms/backoffice":[^0-9]*[0-9]+' --include='package.json' . 2>/dev/null \
| grep -oE '[0-9]+$' | sort -u
C. Last resort — a running instance's Server Information API (needs the site up; prefer A/B):
GET {baseUrl}/umbraco/management/api/v1/server/information
Call the result SITE_MAJOR. If A/B/C all return nothing, there is no Umbraco site in the workspace yet — say so and continue (nothing to guard). If multiple different majors are found (a mixed solution), surface all of them and ask which project is the target.
SITE_MAJOR == TARGET_MAJOR → ✅ Silent pass. Say one line confirming the match
(e.g. "Site is Umbraco {SITE_MAJOR}.x — matches these skills.") and proceed.SITE_MAJOR != TARGET_MAJOR → ⛔ STOP. Do not generate version-specific code. Warn
as below, then only continue if the user explicitly confirms.Which skill line to recommend follows the repo's branch convention — the latest
major lives on main; every older major N lives on a vN/main branch:
SITE_MAJOR < TARGET_MAJOR (site is older than these skills) → point at the older
line for the site's major:
/plugin marketplace add https://github.com/umbraco/Umbraco-CMS-Backoffice-Skills.git#v{SITE_MAJOR}/main
SITE_MAJOR > TARGET_MAJOR (these skills are older than the site) → the latest major
lives on the default main, so re-add and update the default marketplace:
/plugin marketplace add umbraco/Umbraco-CMS-Backoffice-Skills
If no released line exists yet for SITE_MAJOR, say so — the skills may not have caught
up to that major.Substitute the actual numbers when you present this. Template for the message:
⚠️ Version mismatch. This site is Umbraco {SITE_MAJOR}, but the loaded skills target Umbraco {TARGET_MAJOR}. The backoffice API differs between majors, so this skill set will produce incorrect code for your site. Install the matching line:
<computed command above>For the Vercel Skills CLI (Cursor/Copilot/Windsurf), point the repo URL at the matching branch (
mainfor the latest major,v{N}/mainfor an older one).
Run it once at the start of any Umbraco backoffice task, before writing code. The
entry skills (umbraco-quickstart, umbraco-backoffice, umbraco-extension-template)
reference this guard as their first step. Re-run only if the workspace changes.