umbraco-17-starter-facts

Provides verified Umbraco 17 platform facts covering silent failures in Management API, content models, and AI search configuration.

Updated May 26, 2026
One-click install
npx skills add https://github.com/robot-denny/ai-sketchlab --skill umbraco-17-starter-facts-robot-denny
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: umbraco-17-starter-facts
Source: https://github.com/robot-denny/ai-sketchlab/tree/main/.agents/skills/umbraco-17-starter-facts
Command: npx skills add https://github.com/robot-denny/ai-sketchlab --skill umbraco-17-starter-facts-robot-denny

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Umbraco 17 has behaviors that fail silently — no errors, no warnings, no logs — such as an unset toggle property being indistinguishable from an explicit false, an index rebuild reporting success with zero documents, or a configuration key being silently refused. These facts cost hours to diagnose because the symptom surfaces far from the cause. This Skill supplies version-tagged, provenance-tracked facts so you can recognize these traps immediately when writing code, authoring tests, or debugging. ## Core Features & Use Cases - Management API facts: Token expiry at 299 seconds, flat property arrays instead of nested groups, Playwright test-helper quirks like getByName() returning false instead of null, and the intentional STORAGE_STAGE_PATH typo. - Content model facts: Reserved property aliases like level, the correct dropdown UI alias, HasValue guards for default-on toggles, and block editor palette membership rules. - AI and Search facts: Allow-listed $-referenced configuration keys, zero-document index rebuilds that return 200, secret placeholder handling, and per-environment vector index rebuilds. - Use Case: While writing an E2E test against the Umbraco Management API, your assertion expect(x).toBeNull() fails on a missing entity. Consulting this Skill reveals the test-helper returns false on a miss, so you switch to .toBeFalsy() and avoid a test that would silently pass against nonexistent entities. ## Quick Start Ask the assistant to check your Umbraco 17 code or test against the starter facts for silent failure patterns before committing.

Frequently Asked Questions about umbraco-17-starter-facts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my Umbraco Management API test fail intermittently?

Umbraco 17 access tokens expire in 299 seconds, so multi-step setup routines fail partway through on whichever call crosses the boundary. Re-authenticate before each logical group of operations rather than reusing one token for a whole sequence.

How do I assert entity absence with the Umbraco Playwright test helpers?

The getByName() helper returns false, not null, when nothing matches. Use .toBeTruthy() for presence and .toBeFalsy() for absence, because .toBeNull() fails on a miss while .not.toBeNull() would pass against a missing entity.

Why does my Umbraco toggle property return false when it defaults to on?

An Umbraco.TrueFalse property with Default Value set to On returns false from the generated model when never saved, making unset indistinguishable from explicitly off. Use IPublishedContent.HasValue(alias) to detect unset properties and pass null up inheritance chains.

Why does Umbraco AI search return no results after a rebuild?

Without a default embedding profile, an index rebuild completes with zero documents while reporting success, and the rebuild API returns 200 even when misconfigured. Always verify the document count is non-zero after any rebuild.

Does the Umbraco vector index deploy between environments?

No, the vector index is per-environment and does not deploy, even though every other AI entity deploys as schema. After deploying to an environment, rebuild the index there and verify a non-zero document count before promoting further.

When should I not trust these Umbraco starter facts?

Treat a fact as suspect when its Applies version range does not cover your project's version, since several describe bugs fixed in later patches. Facts marked fixed-with-guard or tied to specific beta versions are the most likely to have expired and need re-verification.