用途
本技能用于在 Umbraco 17+ 站点中新增一个区块。区块由一组元素构成：内容元素承载编辑器填写的内容；设置元素用来控制外观，属于可选部分，只有提供样式选项的区块才有；如果区块要重复一组字段，还需要子元素以及容纳子元素的 Block List。该技能负责判断区块需要哪些部件、这些部件如何组合，然后编写需求文档，暂停等待批准，再执行并回读检查结果。
主要能力与部件构成
- 内容元素（如 accordion）：始终需要，位于 Elements/，由 umbraco-add-element-type 以 content element 角色创建。
- 设置模型（如 accordionSettings 或共享模型）：可选，仅当区块有样式选项时需要，位于 Elements/Settings/，由 settings-models.md 决定、umbraco-add-element-type 以 settings model 角色创建。
- 设置组合（如 backgroundColourSettingsComposition）：当某个样式选项无法由现有设置组合提供时需要，位于 Elements/Compositions/。
- 子元素及其 Block List（如 accordionItem、Accordion Items）：当区块需要重复一组字段时需要，位于 Elements/、Data Types/Block List/。
- 在现有块区域中注册：用户指定区域时进行，位于 Data Types/Block Grid/，遵循 umbraco-configure-block-editor 的方案 A。
每个元素的创建规则属于 umbraco-add-element-type，本技能对每个部件调用该技能，并负责把各部件配对起来。区块可在哪里使用由块区域决定，属于 umbraco-configure-block-editor；新建区域由该技能单独处理。规则来自 umbraco-content-model-conventions，需求文档格式与六步工作流来自 umbraco-content-requirements-documentation 的 change-workflow.md，二者必须与本技能一同安装；如果无法读取指向任一者的链接，应停止并说明。
使用方式
每个区块的步骤相同：检查（inspect）、决策（decide）、编写需求文档、暂停等待批准、应用（apply）、验证（verify）。如果已连接 Umbraco Developer MCP，则使用该 MCP；否则按同一需求文档进行手动操作，详见 change-workflow.md。
被其他技能调用时（如 umbraco-add-page 遇到尚不存在的区块），只执行 workflow.md 的第 1 至 3 步：读取站点现状、决定区块部件、编写各部件需求页；然后交回所写页面、其携带的依赖标记以及本技能应用顺序中的检查清单行，供调用方合并（combined-changeset.md）。此时本技能不暂停审批、不执行；变更集、唯一的审批关口与应用均由调用方负责，但本技能工作流中的应用与验证说明仍适用于它所写的产物。在调用方的块区域中注册是调用方的步骤。
最佳实践
- 元素不等于区块：区块是注册在块区域中的内容元素；设置模型、设置组合和重复项元素也是元素，但只是区块的部件，本身永远不是区块。
- 设置是可选的：没有样式选项的区块不加设置元素，注册时设置记为 —；不要以防万一先加设置模型。
- 内容与样式分离：颜色、间距和锚点不放在编辑器填写的内容元素上，而放在由设置组合构建的设置元素上。
- 先复用再新建：多数区块可复用站点两个共享设置模型之一；专属的 <block>Settings 仅用于共享模型缺少的样式选项。
- 元素上不加选项卡。
- 重复项采用父元素加 ...Item 子元素的 Block List，而不是编号字段或组合。
- 叶子优先：依次为设置组合、设置模型、子元素、Block List、父元素、注册它的块区域，每一步都需要前一步的 id。
- 放置区块是对现有数据类型的 Update，注册内容元素及其设置模型（如有），并保留该区域已有的全部区块。
- “直接构建区块”只是对区块的请求，不等于批准用户尚未看到的需求文档。
版本与验证
目标版本为 Umbraco 17+；MCP 工具名称已按 umbraco-content-requirements-documentation 所述核对，以已连接工具列表为准。客观断言位于 evals/evals.json，可用 umbraco-skill-evaluator 运行。覆盖层级为 Documented。本技能不包含代码与资源；其编写的需求文档由 umbraco-content-requirements-documentation 中的 linter 检查，另有一项评估对指导内容评分。未在真实站点上运行。evals/files/ 下的评估夹具是本技能自己的副本，umbraco-add-element-type 与 umbraco-add-page 保留各自的副本，因为评估文件路径相对于技能解析，副本可能产生偏差。