用途
本技能为 Umbraco 17+ 站点添加单个元素类型。元素类型是“存在于其他内容之中、从不单独出现在内容树上的内容结构”。一个元素可以是四种角色之一，角色决定它的文件夹、别名、容器和允许组合的内容：
- 内容元素（content element）：由编辑人员填写的内容；
- 重复器子项（
...Item）：重复器的子项； - 设置模型（settings model）；
- 设置组合（settings composition）。
元素类型不等同于块（block）。块是注册在块区域中的内容元素，可能带一个可选的设置元素，重复器还带其子项。重复器子项、设置模型和设置组合都是元素但从来不是块；内容元素只有在被注册后才成为块。决定一个块需要哪些元素是 umbraco-add-block 的职责，它会为每个组成部分调用本技能一次。元素可以在何处使用属于块区域，由 umbraco-configure-block-editor 负责。
主要能力与工作流程
技能采用需求先行的六步流程：
- 检查：查看现有元素、文件夹、设置组合与模型、数据类型、媒体类型和语言；
- 决策：先确定角色，再确定名称、别名、文件夹、容器、字段、图标、描述、组合和文化设置；
- 编写与检查：写出元素、所需的数据类型和一份变更集，并通过 linter 检查；
- 停下来等待批准：用户批准变更集后才继续；
- 应用：创建元素、移动到其文件夹并做修正；可通过 MCP 或手动走查完成；
- 验证与报告：回读结果，设置状态行并报告。
已连接 MCP 时使用 MCP，否则按同一份需求文档进行手动走查。
被其他技能调用
umbraco-add-block 会为块的每个元素调用本技能；umbraco-add-page 会为页面所需的、没有设置也没有重复器的单个元素调用它。被调用时只执行第 1 至 3 步（检查、决策、编写），返回写好的需求页面、依赖标记和检查清单行（create、move、fix-up）供调用方合并；不自行停下等待批准，也不执行应用，变更集、唯一的批准关口和应用都由调用方负责。
最佳实践
- 内容与样式分离：内容元素只放编辑人员填写的内容，不放颜色、间距或对齐字段；这些属于设置组合，再组合进设置模型。
- 内容元素不带选项卡：只有一个 Content 组，sort 为 0；设置组合是唯一可以带选项卡的元素类型（Style 50 或 Settings 100）。
- 别名为普通名词；仅当名词与媒体类型、数据类型或保留字冲突时才加
...Block后缀。 - 每个设置组合只关注一件事，设置模型本身没有自己的属性。新建设置组合由
umbraco-add-block或umbraco-change-document-type组合进设置模型，此处只把它记为后续事项。 - 元素上的字段别名简短通用，例如用
title而不是accordionTitle。 - 元素先在树根创建，再移入其文件夹；排序和描述在修正阶段设置。
- “直接创建元素”并不等于批准了一份用户尚未看到的变更集，批准关口仍然适用。
依赖与限制
- 需要与
umbraco-content-model-conventions（规则来源）和umbraco-content-requirements-documentation（需求文档格式与六步流程）一起安装；若无法读取指向二者的链接，应停止并说明。 - 目标版本为 Umbraco 17+；MCP 工具名称以已连接的工具列表为准。
- 技能不附带代码和资源，需求文档由配套技能的 linter 检查，指南经过评估；未在真实站点上运行过。
- 评估夹具中保存了
umbraco-add-block所用site-context.md的副本，因评估文件路径相对于技能解析，副本可能发生漂移。