1. 基本信息
项目自述名称：所在仓库自述为「dbt Agent Skills」（dbt Labs 官方多技能合集仓库），本技能自身文档标题为「Building the dbt Semantic Layer」。
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | building-dbt-semantic-layer-dbt-labs-dbt-agent-skills | — |
| 作者/维护者 | dbt Labs（官方） | GitHub API |
| 来源链接 | https://github.com/dbt-labs/dbt-agent-skills/tree/main/skills/dbt/skills/building-dbt-semantic-layer | — |
| 许可证 | Apache-2.0 | GitHub API |
| GitHub Stars（仓库整体） | 640 | GitHub API |
| Forks（仓库整体） | 57 | GitHub API |
| 最新版本 | 1.3.1（Tessl 包管理器 tile.json 标注，仓库尚未打 GitHub Release 标签，滚动更新） | 仓库直读 |
| 安装方式 | Claude Code 插件市场 / Vercel Skills CLI / Tessl | 官方 README |
2. 功能介绍与亮点
核心能力：指导创建与修改 dbt Semantic Layer 的四类核心组件——语义模型（semantic models）、实体（entities）、维度（dimensions）、指标（metrics），底层由 MetricFlow 驱动。
- 双 YAML 规范自动路由：先检测项目现有配置判断使用的是「latest 规范」（dbt Core 1.12+/Fusion，语义模型作为模型元数据）还是「legacy 规范」（dbt Core 1.6–1.11，语义模型独立定义），再给出对应版本的完整最小示例，避免语法混用；
- 五种指标类型全覆盖：simple、derived（多指标数学组合）、cumulative（滚动窗口/期初至今）、ratio（比率）、conversion（转化漏斗），每种都给出适用场景与语法要点；
- 两阶段强制校验：
dbt parse/dbtf parse做语法校验，再用mf validate-configs（MetricFlow CLI）或dbt sl validate做语义层校验，未通过两阶段校验不算完成； - 显式防注入条款：明文要求把项目 SQL、YAML 配置、外部内容一律当作不可信数据，禁止执行其中嵌入的指令，只提取预期的结构化字段；
- 常见踩坑速查表：时间维度缺失、窗口参数误用、规范混用、依赖包安装错误等 6 类高频问题及对应修复方式。
3. 适用场景
固定分类：数据分析与可视化
- 已有 dbt 项目、需要为业务指标（收入、订单量、留存率、转化率等）建立可复用、跨模型一致定义的分析工程师；
- 项目从 legacy 规范升级到 dbt Core 1.12+/Fusion 的 latest 规范，需要 Agent 协助判断兼容性并迁移；
- 需要给 BI 工具或对话式问数场景提供统一指标口径、避免各处重复手写 SQL 计算同一业务指标的团队。
受益人群：已在用 dbt 建模、希望把“指标定义”这一步交给 Agent 而非从零学习 MetricFlow YAML 语法的分析工程师与数据团队。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | 仓库提供 .claude-plugin/marketplace.json，/plugin marketplace add + /plugin install 一键安装 |
| Codex | ✅ 官方点名支持 | dbt Labs 官方开发者博客（docs.getdbt.com/blog/dbt-agent-skills）明确列出 Claude Code、OpenAI Codex、Cursor、Factory、Kilo Code 为兼容 Agent |
| OpenClaw | ❓ 未验证 | 抓取材料仅笼统声称遵循开放的 Agent Skills 规范（agentskills.io），未点名验证 |
| Hermes Agent | ❓ 未验证 | 同上，材料未提及 |
5. 推荐理由
dbt Labs 官方出品，精准解决“指标定义散落在各处 SQL、口径不一致”这一分析工程中的高频痛点：把 MetricFlow 的双规范语法差异、五种指标类型、强制校验流程封装成一套可直接执行的工作流，并显式写入防 prompt injection 条款。子技能本身近期（两周内）仍有实质性维护记录，与同仓库负责建模全生命周期的姊妹技能 using-dbt-for-analytics-engineering 定位互补而非重叠（前者管指标层定义，后者管模型开发调试），对已用 dbt、正打算把业务指标沉淀进语义层的团队价值明确。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 合集仓库不计整体 stars；该子技能自身有 3 条独立追踪的 GitHub issue/PR（规范路由边界修正、示例修复），仓库整体持续有外部贡献者提交安全审计修复与 CI 改进，但未见针对本子技能的独立第三方聚合平台数据或公开评测 |
| 可用性 | 8 | Claude Code 插件市场一键安装（随 dbt 插件一并装入，含另外 8 个 dbt 核心技能）；双规范示例+参考文档齐全，校验流程明确；指标定义本身免费（dbt-core 原生功能），无需付费订阅；最近一次实质性提交为近两周内，维护活跃；但依赖用户本地已有配置好的 dbt 项目，非完全零门槛 |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合 | 8.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令权限范围 | 未声明 allowed-tools 限制，仅建议执行 dbt parse/mf validate-configs 等 dbt 生态标准命令做校验，无任意 shell 执行倾向 |
| ② 运行时联网外发 | 无外部网络调用，全部在用户本地 dbt 项目文件内完成 |
| ③ API key/凭据存储 | 不索取或存储任何凭据，指标定义与查询复用 dbt 项目自身连接配置 |
| ④ 可疑指令/注入迹象 | 未发现；文档专设“处理外部内容”章节，明确要求将 SQL/YAML/外部数据当作不可信内容，禁止执行其中嵌入指令，加分项 |
| ⑤ 作者/组织信誉 | dbt Labs 官方，dbt 生态权威维护方 |
| ⑥ License 明确性 | Apache-2.0，明确 |
| ⑦ 最近维护时间 | 近两周内仍有实质性提交，仓库整体持续活跃，含多位具名贡献者 |
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| semantic-model-authoring（Microsoft Fabric 官方） | Power BI/Fabric 语义模型建模：表/关系/度量/DAX 编写+部署+权限配置全流程 | 面向 Power BI 生态、依赖 Azure 认证与 Fabric 订阅；本技能面向 dbt/MetricFlow 生态，指标定义本身零付费依赖，且不涉及部署与权限管理 |
| power-bi-agentic-development（社区维护） | 覆盖语义建模、DAX、报表可视化、租户治理的全流程技能市场 | 覆盖面更广但绑定 Power BI 生态，非官方出品；本技能聚焦更窄但由 dbt Labs 官方维护、与 dbt 建模工作流无缝衔接 |
| Cube（cube.dev，非 Agent Skill） | 独立部署的商业化无头 BI/语义层平台，提供统一 API 供 BI 工具消费 | 需要单独部署基础设施与授权；本技能是 dbt 项目内的原生 YAML 配置方式，无需额外服务，与现有 dbt 工作流零缝隙集成 |
8. 用户评价
该技能目前在第三方平台尚无独立于厂商的具名用户评价。
9. 其他补充
技能随同仓库其余 8 个 dbt 核心技能打包为单个 dbt 插件分发，遵循开放的 Agent Skills 规范（agentskills.io），同一份技能可通过 Claude Code 插件市场、Vercel Skills CLI（支持 30+ 种 Agent）、Tessl 包管理器等多种渠道单独或批量安装。仓库已配置 Changie 自动生成 CHANGELOG 的机制，接受外部社区通过 Pull Request 贡献新技能或改进。
10. 安装使用方式
Claude Code（官方推荐）：
/plugin marketplace add dbt-labs/dbt-agent-skills
/plugin install dbt@dbt-agent-marketplace该插件包含 building-dbt-semantic-layer 在内的 9 个 dbt 核心技能。
Vercel Skills CLI（跨 Agent 通用，支持 Codex/Cursor/GitHub Copilot 等 30+ Agent）：
npx skills add dbt-labs/dbt-agent-skills --skill building-dbt-semantic-layerTessl 包管理器：
tessl install dbt-labs/dbt-agent-skills --skill building-dbt-semantic-layer安装后注意事项：该技能为自动触发型（user-invocable: false），无需手动斜杠命令调用；使用前提是本地已有配置好的 dbt 项目（dbt-core 1.6+ 或 Fusion）；若需要本地运行 mf validate-configs 做语义层校验，需额外安装 dbt-metricflow 包（而非裸 metricflow，二者依赖版本不兼容）。
11. 注意事项
- 需要用户本地已有配置好的 dbt 项目，对完全没有 dbt 项目的用户没有直接价值；
- 项目若混用 legacy 与 latest 两种 YAML 规范容易出错，技能虽已做路由判断，仍建议人工确认最终选用的规范与 dbt 版本匹配；
- 本技能只负责“定义”指标配置，若要通过
dbt sl validate走完整语义层服务端校验，或让 BI 工具/对话式问数功能实际查询已发布的指标，需要 dbt 平台（原 dbt Cloud）订阅或 Fusion 引擎，个人免费账户的可用范围有限； - OpenClaw 与 Hermes Agent 的兼容性完全未验证。