[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CYG59CZN1K2KERB0SSDGSY":3,"skill-same:01M7CYG59CZN1K2KERB0SSDGSY":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7CYG59CZN1K2KERB0SSDGSY","umbraco-package-conventions",null,"Backend conventions for an Umbraco package: async naming, internal by default, Attempt-based results for routine failures, public-API backwards compatibility, and where extension methods live. Use when naming a method, choosing visibility, shaping a service's result, changing a public signature (including adding a dependency to a public class's constructor), or organizing extension methods. For extension mechanisms, see `umbraco-extensibility`.","mattbrailsford\u002Fumbraco-devkit","mattbrailsford","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F527305?v=4","01M7CY974D4XX1P90YSXQC1T39","Matt Brailsford","01M7CY9751PSRA3EHBH03G936J",3,"MIT","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-package-conventions\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: umbraco-package-conventions\ndescription: >-\n  Backend conventions for an Umbraco package: async naming, internal by default,\n  Attempt-based results for routine failures, public-API backwards compatibility, and where\n  extension methods live. Use when naming a method, choosing visibility, shaping a service's\n  result, changing a public signature (including adding a dependency to a public class's\n  constructor), or organizing extension methods. For\n  extension mechanisms, see `umbraco-extensibility`.\n\n---\n\n# Umbraco package conventions\n\n## *🎯 Why: Design for Change*\n\nA package's own internal conventions — naming, layering, namespace organization, API stability\n— don't touch its extension surface directly, but they're what makes the codebase predictable\nenough that the *next* change (by you, or by a package consumer) doesn't require re-deriving\nthe rules from scratch each time.\n\n## Async method naming: `[Action][Entity]Async`\n\n| Component | Description | Examples |\n|---|---|---|\n| Action | Verb | `Get`, `Create`, `Update`, `Delete`, `Save`, `Find`, `List`, `Validate` |\n| Entity | Noun | `Profile`, `Connection`, `Item`, `Context` |\n| Async | Suffix | Always required |\n\nQualifiers come after the entity: `GetItemByAliasAsync`, `GetAllItemsAsync`. Existence\nchecks: `[Entity][Qualifier]ExistsAsync` (e.g. `ItemAliasExistsAsync`).\n\nThis is the dominant shape across real Umbraco service interfaces, though not universal —\ntreat it as a strong default, not a rule worth blocking a PR over on its own.\n\n## Visibility: `internal` by default\n\nEvery `public` type or member is a contract. Once it ships, changing it falls under the\ndeprecation rules in \"Public API backwards compatibility\" below. So start everything\n`internal`, and make it `public` only when it is one of these:\n\n- **Public API**: something consumers are meant to call, plus the models they pass in or get\n  back.\n- **An extension point**: something others hook into, such as an interface to implement, a\n  base class, a collection builder, or a notification and its payload.\n- **Required by a base type or DI**: an override of a public member, or a type that the\n  framework, the DI container or assembly scanning can only use when it's public.\n\nSharing code between your own assemblies isn't one of these. Keep it `internal` and add an\n`InternalsVisibleTo` for the consuming assembly in the owning project. Visibility is also\nper member: a notification class and its name can be public while the factory methods that\nbuild it stay internal.\n\nBefore adding a `public` type or member, name which of the three it is. If you can't, it's\n`internal`.\n\n### Repositories: internal to the owning service\n\nRepositories should be `internal` to the persistence assembly. Only the entity's own service\nmay touch its repository — controllers and other services go through the service layer:\n\n```\nController \u002F other service ──▶ EntityService ──▶ EntityRepository (internal)\n```\n\nThis keeps caching, validation, and business rules in one place (the service), and stops a\nfuture refactor of the repository from becoming a breaking change for anyone but that one\nservice. Not a strict law — a repository can be `public` if something outside the normal\nservice layer (diagnostics, a health check) genuinely needs to reach it directly. Default to\n`internal`; make a repository `public` only for a specific, nameable reason, not by omission.\n\n## Routine failures: `Attempt\u003CTResult, TStatus>`, like Umbraco's services\n\nUmbraco's services report expected failures through the return type, not exceptions:\n`IContentEditingService.CreateAsync` returns `Attempt\u003CContentCreateResult,\nContentEditingOperationStatus>`, and the Management API controller maps the status enum to a\nresponse. A package service that can fail routinely (not found, invalid input, a duplicate)\nshould use the same shape: `Attempt\u003CT, TStatus>` with the package's own operation-status\nenum. Callers built on Umbraco already know how to branch on it, and a controller maps each\nstatus to a `ProblemDetails` response in one place. Keep exceptions for programmer errors.\n\n## Public API backwards compatibility\n\nNever break a public method's signature outright. When a new version needs new parameters,\nkeep the old signature and have it **proxy** to the new one, resolving the new parameter via\nDI\u002Fservice location if it can't be threaded through the call site:\n\n```csharp\n\u002F\u002F Simple case — the new parameter has a sensible static default, no DI needed:\n[Obsolete(\"Use GetItemAsync(id, options) instead. Will be removed in v19.0.0.\")]\npublic Task\u003CItem> GetItemAsync(Guid id) => GetItemAsync(id, ItemOptions.Default);\n\npublic Task\u003CItem> GetItemAsync(Guid id, ItemOptions options) { \u002F* real implementation *\u002F }\n\n\u002F\u002F Harder case — the new logic genuinely needs a dependency the old call site never had,\n\u002F\u002F and the old method can't take a new constructor parameter without breaking every existing\n\u002F\u002F caller's `new MyService(...)` call. Resolve it via the static service provider instead:\n[Obsolete(\"Use CreateAsync(item, permissionChecker) instead. Will be removed in v19.0.0.\")]\npublic Task\u003CItem> CreateAsync(Item item) =>\n    CreateAsync(item, StaticServiceProvider.Instance.GetRequiredService\u003CIItemPermissionChecker>());\n\npublic Task\u003CItem> CreateAsync(Item item, IItemPermissionChecker permissionChecker) { \u002F* real implementation *\u002F }\n```\n\nResolve via `StaticServiceProvider.Instance.GetRequiredService\u003CT>()` inside the obsolete\noverload, rather than duplicating the implementation, only when a static default genuinely\nisn't available — a compile-time default parameter is always simpler when one exists.\n\nThe same rule covers a public constructor, such as a Management API controller's or a\nservice's that consumers may construct themselves. Keep the old constructor, mark it\n`[Obsolete]`, and chain it to the new one, resolving the new dependency through\n`StaticServiceProvider`. Then put `[ActivatorUtilitiesConstructor]` on the new constructor.\nWith two public constructors and no marker, ASP.NET Core's `ActivatorUtilities` can't pick\none, and the controller fails at runtime on its first request, not at build time. Only a real\nrequest through the demo site proves the right constructor is picked; a unit test calling\n`new` directly doesn't.\n\n```csharp\n[ActivatorUtilitiesConstructor]\npublic ItemController(IItemService itemService, IItemPermissionChecker permissionChecker) { \u002F* ... *\u002F }\n\n[Obsolete(\"Use the constructor taking IItemPermissionChecker. Will be removed in v19.0.0.\")]\npublic ItemController(IItemService itemService)\n    : this(itemService, StaticServiceProvider.Instance.GetRequiredService\u003CIItemPermissionChecker>())\n{ }\n```\n\nGive consumers a real deprecation window — state the target version in the `[Obsolete]`\nmessage. The default target is the highest CMS major the package supports + 2. A package\nsupporting v17 and v18 that obsoletes a member in both targets v20, on both branches. Check\nthe project's `CLAUDE.md` first and follow whatever it actually states if it already commits\nto a different number.\n\n## Extension methods\n\nKeep them in a single, predictable namespace (e.g. `\u003CRootNamespace>.Extensions`), not\nscattered next to whatever class happened to need one first. A consumer should be able to\nguess where to look. (This is C#'s *extension method* language feature — an unrelated sense of\n\"extension\" from `umbraco-extensibility`'s Umbraco extension points; don't confuse the two.)\n\n## Multi-version support\n\nIf the package targets more than one Umbraco CMS major at once, that's a branching and\nrelease-versioning question, not a package-convention one — see `git-workflow`'s \"Umbraco\npackages and version tracking\" section for branch-per-major and version-alignment guidance.\nThis skill doesn't restate it.\n","# Umbraco package conventions\n\n## *🎯 Why: Design for Change*\n\nA package's own internal conventions — naming, layering, namespace organization, API stability\n— don't touch its extension surface directly, but they're what makes the codebase predictable\nenough that the *next* change (by you, or by a package consumer) doesn't require re-deriving\nthe rules from scratch each time.\n\n## Async method naming: `[Action][Entity]Async`\n\n| Component | Description | Examples |\n|---|---|---|\n| Action | Verb | `Get`, `Create`, `Update`, `Delete`, `Save`, `Find`, `List`, `Validate` |\n| Entity | Noun | `Profile`, `Connection`, `Item`, `Context` |\n| Async | Suffix | Always required |\n\nQualifiers come after the entity: `GetItemByAliasAsync`, `GetAllItemsAsync`. Existence\nchecks: `[Entity][Qualifier]ExistsAsync` (e.g. `ItemAliasExistsAsync`).\n\nThis is the dominant shape across real Umbraco service interfaces, though not universal —\ntreat it as a strong default, not a rule worth blocking a PR over on its own.\n\n## Visibility: `internal` by default\n\nEvery `public` type or member is a contract. Once it ships, changing it falls under the\ndeprecation rules in \"Public API backwards compatibility\" below. So start everything\n`internal`, and make it `public` only when it is one of these:\n\n- **Public API**: something consumers are meant to call, plus the models they pass in or get\n  back.\n- **An extension point**: something others hook into, such as an interface to implement, a\n  base class, a collection builder, or a notification and its payload.\n- **Required by a base type or DI**: an override of a public member, or a type that the\n  framework, the DI container or assembly scanning can only use when it's public.\n\nSharing code between your own assemblies isn't one of these. Keep it `internal` and add an\n`InternalsVisibleTo` for the consuming assembly in the owning project. Visibility is also\nper member: a notification class and its name can be public while the factory methods that\nbuild it stay internal.\n\nBefore adding a `public` type or member, name which of the three it is. If you can't, it's\n`internal`.\n\n### Repositories: internal to the owning service\n\nRepositories should be `internal` to the persistence assembly. Only the entity's own service\nmay touch its repository — controllers and other services go through the service layer:\n\n```\nController \u002F other service ──▶ EntityService ──▶ EntityRepository (internal)\n```\n\nThis keeps caching, validation, and business rules in one place (the service), and stops a\nfuture refactor of the repository from becoming a breaking change for anyone but that one\nservice. Not a strict law — a repository can be `public` if something outside the normal\nservice layer (diagnostics, a health check) genuinely needs to reach it directly. Default to\n`internal`; make a repository `public` only for a specific, nameable reason, not by omission.\n\n## Routine failures: `Attempt\u003CTResult, TStatus>`, like Umbraco's services\n\nUmbraco's services report expected failures through the return type, not exceptions:\n`IContentEditingService.CreateAsync` returns `Attempt\u003CContentCreateResult,\nContentEditingOperationStatus>`, and the Management API controller maps the status enum to a\nresponse. A package service that can fail routinely (not found, invalid input, a duplicate)\nshould use the same shape: `Attempt\u003CT, TStatus>` with the package's own operation-status\nenum. Callers built on Umbraco already know how to branch on it, and a controller maps each\nstatus to a `ProblemDetails` response in one place. Keep exceptions for programmer errors.\n\n## Public API backwards compatibility\n\nNever break a public method's signature outright. When a new version needs new parameters,\nkeep the old signature and have it **proxy** to the new one, resolving the new parameter via\nDI\u002Fservice location if it can't be threaded through the call site:\n\n```csharp\n\u002F\u002F Simple case — the new parameter has a sensible static default, no DI needed:\n[Obsolete(\"Use GetItemAsync(id, options) instead. Will be removed in v19.0.0.\")]\npublic Task\u003CItem> GetItemAsync(Guid id) => GetItemAsync(id, ItemOptions.Default);\n\npublic Task\u003CItem> GetItemAsync(Guid id, ItemOptions options) { \u002F* real implementation *\u002F }\n\n\u002F\u002F Harder case — the new logic genuinely needs a dependency the old call site never had,\n\u002F\u002F and the old method can't take a new constructor parameter without breaking every existing\n\u002F\u002F caller's `new MyService(...)` call. Resolve it via the static service provider instead:\n[Obsolete(\"Use CreateAsync(item, permissionChecker) instead. Will be removed in v19.0.0.\")]\npublic Task\u003CItem> CreateAsync(Item item) =>\n    CreateAsync(item, StaticServiceProvider.Instance.GetRequiredService\u003CIItemPermissionChecker>());\n\npublic Task\u003CItem> CreateAsync(Item item, IItemPermissionChecker permissionChecker) { \u002F* real implementation *\u002F }\n```\n\nResolve via `StaticServiceProvider.Instance.GetRequiredService\u003CT>()` inside the obsolete\noverload, rather than duplicating the implementation, only when a static default genuinely\nisn't available — a compile-time default parameter is always simpler when one exists.\n\nThe same rule covers a public constructor, such as a Management API controller's or a\nservice's that consumers may construct themselves. Keep the old constructor, mark it\n`[Obsolete]`, and chain it to the new one, resolving the new dependency through\n`StaticServiceProvider`. Then put `[ActivatorUtilitiesConstructor]` on the new constructor.\nWith two public constructors and no marker, ASP.NET Core's `ActivatorUtilities` can't pick\none, and the controller fails at runtime on its first request, not at build time. Only a real\nrequest through the demo site proves the right constructor is picked; a unit test calling\n`new` directly doesn't.\n\n```csharp\n[ActivatorUtilitiesConstructor]\npublic ItemController(IItemService itemService, IItemPermissionChecker permissionChecker) { \u002F* ... *\u002F }\n\n[Obsolete(\"Use the constructor taking IItemPermissionChecker. Will be removed in v19.0.0.\")]\npublic ItemController(IItemService itemService)\n    : this(itemService, StaticServiceProvider.Instance.GetRequiredService\u003CIItemPermissionChecker>())\n{ }\n```\n\nGive consumers a real deprecation window — state the target version in the `[Obsolete]`\nmessage. The default target is the highest CMS major the package supports + 2. A package\nsupporting v17 and v18 that obsoletes a member in both targets v20, on both branches. Check\nthe project's `CLAUDE.md` first and follow whatever it actually states if it already commits\nto a different number.\n\n## Extension methods\n\nKeep them in a single, predictable namespace (e.g. `\u003CRootNamespace>.Extensions`), not\nscattered next to whatever class happened to need one first. A consumer should be able to\nguess where to look. (This is C#'s *extension method* language feature — an unrelated sense of\n\"extension\" from `umbraco-extensibility`'s Umbraco extension points; don't confuse the two.)\n\n## Multi-version support\n\nIf the package targets more than one Umbraco CMS major at once, that's a branching and\nrelease-versioning question, not a package-convention one — see `git-workflow`'s \"Umbraco\npackages and version tracking\" section for branch-per-major and version-alignment guidance.\nThis skill doesn't restate it.\n",{"name":5,"description":7},"main","a2f9c28bc56802b4e6db01e03972e497b30ad001","plugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-package-conventions",1,"https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit","https:\u002F\u002Fgithub.com\u002Fmattbrailsford","https:\u002F\u002Fmattbrailsford.dev","AI Staff Engineer @umbraco ","2026-11-12 18:33:53",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add mattbrailsford\u002Fumbraco-devkit --skill umbraco-package-conventions",{"tool":39,"command":40},"bunx","bunx skills add mattbrailsford\u002Fumbraco-devkit --skill umbraco-package-conventions",{"tool":42,"command":43},"pnpm","pnpm dlx skills add mattbrailsford\u002Fumbraco-devkit --skill umbraco-package-conventions","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-package-conventions\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7CYGRPVNP8H9YNHGMZ6CP3C","user-stories","Writes, splits and refines user stories with Given\u002FWhen\u002FThen acceptance criteria in STORIES.md, feeding bdd-specs. Use when turning a feature request or a vague ask into a testable backlog entry.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fuser-stories\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7CYGJB26N83DXKMDEKY2X48","umbraco-security","What Umbraco provides for keeping a package secure, on the server and in the backoffice: Management API authorization and policies, settings that hold secrets, endpoints outside the Management API, sanitizeHTML and escapeHTML, DOMPurify rules for custom elements, and umbHttpClient instead of handling tokens in the browser. Use when writing or reviewing a Management API controller, a secret setting, a custom endpoint, a backoffice template that uses unsafeHTML, or frontend code that calls an API.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-security\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CYGBEZ2Q4AXDDNADWW4Q9H","umbraco-performance","Keeping a package fast on the sites that install it: the published cache over the services layer, tree traversal, caching lookups and clearing them, data type config and converter cache levels, output cache eviction, light hot paths, and backoffice screens that don't over-fetch. Use when writing, changing or reviewing code that runs per request, per save, per indexed item or at startup (property value converters, notification handlers, indexing), code that loops over every content item (a full rebuild, an import, a sync), or a list or search screen. Not for a site's own templates.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-performance\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CYG0J10QH8J2GS825WTTET","umbraco-marketplace","Gets a finished package listed on the Umbraco Marketplace: the NuGet tag, the dependency Marketplace reads version support from, the v14+ compatibility gotcha, and umbraco-marketplace.json. Use when a package is ready to publish, or when reviewing its packaging.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-marketplace\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CYFT7MSYW4GRDSQRDPG020","umbraco-extensibility","Umbraco's extension mechanisms (Composers, collection builders, notification handlers, attribute discovery) and a catalogue of backend CMS extension points: property value converters, Management API endpoints, content finders, health checks, search indexing, package migrations, background jobs, and more. Use when making a feature extensible or choosing which extension point fits. Not for property editor UI, dashboards, sections or trees, which the official Backoffice Skills plugin covers.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-extensibility\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7CYFM5BJ5SVK9SJB78VY6ZG","umbraco-env-sync","Moving an Umbraco package's own entities between environments with Umbraco Deploy or uSync: what moves as files and what moves over the wire, export shape and dependencies, restores, keeping secrets out, linking users by alias, translating stored ids, and keeping sync code current. Use when adding Deploy or uSync support, or changing an entity the package syncs. Not for deploying the site itself.","https:\u002F\u002Fgithub.com\u002Fmattbrailsford\u002Fumbraco-devkit\u002Fblob\u002Fmain\u002Fplugins\u002Fumbraco-devkit\u002Fskills\u002Fumbraco-env-sync\u002FSKILL.md",[],[]]