1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | Metabase Database Metadata（metabase-database-metadata-metabase-agent-skills） |
| 作者/维护者 | Metabase（metabase 官方组织），核心维护者为工程师 ranquild |
| 来源链接 | github.com/metabase/agent-skills/tree/main/skills/metabase-database-metadata |
| 许可证 | MIT（GitHub API 确认，仓库根目录 LICENSE 文件核实） |
| GitHub Stars | 合集仓库整体 38（GitHub API）；该数字属整个 agent-skills 合集，不代表本技能自身热度 |
| Forks | 合集仓库整体 0（GitHub API） |
| 最新版本 | 配套 npm 包 @metabase/database-metadata 当前版本 1.0.6（npm registry 确认） |
| 安装方式 | npx skills add metabase/agent-skills --skill metabase-database-metadata -a claude-code |
2. 功能介绍与亮点
Metabase Database Metadata 让 Agent 读取并缓存一份 Metabase 实例的数据库结构——数据库、表、字段及其类型信息，以 diff 友好的 YAML 文件树落盘，供 Agent 编写查询、排查字段类型时直接查阅，不必每次猜测或反复调用 API。
核心能力：
- 结构化 YAML 元数据树：按
数据库/schema/表分层落地，外键采用可读的自然键元组（如["Sample Database", "PUBLIC", "ORDERS"]）而非数字 ID，便于人与 Agent 阅读、也方便版本对比。 - 按需获取、不主动刷新：仅在磁盘元数据缺失且用户明确提出需求时才触发导出；数据看似过时也只提醒用户手动刷新，不会静默重拉。
- 类型体系完整：区分原生类型、Metabase 归一类型、强制转换类型与业务语义标签（主键/外键/邮箱等），配套随附规范文档
spec.md详解完整类型层级。 - 体积控制：原始 JSON 导出可能达数 GB，SKILL.md 明确要求只读提取后的 YAML 树、不直接打开原始 JSON，并建议加入
.gitignore。
亮点：官方一线机构出品；该子技能是同仓库内提交最多（18 次）、维护最活跃的技能之一，近 4 个月内仍有更新；曾有非 Metabase 员工的外部用户通过 issue 反馈使用问题，证明确有真实用户在生产环境中使用。
3. 适用场景
所属分类：数据分析与可视化
适合已在用 Metabase 搭建仪表盘或做数据探索的分析师、数据工程师与产品团队——需要 Agent 协助编写 SQL/MBQL 查询、核对字段类型与外键关系、或诊断“字段名幻觉”问题时，先跑一次本技能生成结构元数据，后续对话即可基于真实 schema 回答。
4. 跨 Agent 兼容性
- Claude Code：原生支持，README 给出官方安装命令，SKILL.md 的
allowed-tools/model字段是 Claude Code 技能规范的标准写法。 - Codex：未验证。README 提到“可能也适用于 Cursor、Windsurf”，未点名 Codex；格式标准通用但未见针对性验证。
- OpenClaw / Hermes Agent：未验证。官方材料未提及；仓库 issue 中有开发者提到用“pi coding agent”（非本次四生态之一）试用同仓库另一子技能，说明确有跨 Agent 使用案例，但非直接证据。
5. 推荐理由
Metabase 官方出品，让 Agent 提前掌握 Metabase 实例的真实数据库结构，从根源上减少编写查询与分析数据时因臆造字段名、误判类型而导致的返工。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Metabase 官方账号出品；合集仓库整体星数不高（38★），但已有非 Metabase 员工的外部用户通过 issue 反馈使用中遇到的问题，且已被第三方技能市场 skillsmp.com、skills.sh 收录展示 |
| 可用性 | 8 | 一条 npx skills add 命令即可安装；文档详尽（SKILL.md 正文 + 随附 spec.md 规范文档，逐项说明类型体系与文件夹结构）；该子技能是仓库内提交最活跃的一个，近 4 个月内仍有更新；仅需用户自备可访问的 Metabase 实例与 API Key，无强制付费依赖 |
| 安全性 | 8 | 全部操作只针对用户自己指定的 Metabase 实例（METABASE_URL）与自备 API Key（经环境变量传入，不写死在文件中），不涉及任何第三方外发；MIT 协议、仓库完全开源可审计；SKILL.md 通读未见可疑指令 |
安全检查清单：① Shell 权限——仅 curl 调用用户自己 Metabase 实例导出接口 + npx 本地格式转换，范围明确；② 联网外发——只连用户自行指定的 $METABASE_URL，无第三方外发；③ 凭据——METABASE_API_KEY 经环境变量传入，不写入文件；④ 可疑指令——通读未发现；⑤ 作者信誉——官方组织出品，具名工程师维护；⑥ License——MIT，仓库核实；⑦ 维护——近 4 个月内仍有提交。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| Metabase CLI（同仓库子技能） | 通过官方 mb 命令行工具驱动 Metabase 实例——查数据、跑查询、管理内容 |
面向“直接操作 Metabase”的场景，且需要额外安装 mb CLI 才能运行；本技能只负责让 Agent 预先理解 schema，不直接操作实例内容，二者可配合使用 |
| Business Intelligence（个人开发者技能，聚焦 BI 方法论） | 提供仪表盘设计、KPI 框架定义、报表自动化的通用方法论指导 | 是工具无关的流程模板，不连接任何真实数据源或 BI 产品实例；本技能则专门同步 Metabase 一款具体产品的真实 schema，两者一个讲方法论、一个讲实际数据对接 |
| MongoDB Schema Design（MongoDB 官方技能） | 指导开发者在应用开发阶段设计合理的 MongoDB 文档 schema、规避性能反模式 | 解决的是“如何设计一个新 schema”的前置问题，面向应用开发场景；本技能解决的是“如何让 Agent 准确认识一个已存在的 BI 工具实例的 schema”，二者面向的产品与开发阶段都不同 |
差异化在于：它既不是通用数据库设计建议，也不是操作 Metabase 的自动化工具，而是专门解决“Agent 对着真实存在的 Metabase 实例却不知道有哪些表和字段”这一痛点——用磁盘持久化的结构化元数据，让后续对话锚定在真实 schema 上。
8. 用户评价
该技能所在仓库有非 Metabase 员工的外部用户通过 GitHub issue 反馈过实际使用问题（如文档链接失效），存在真实的仓库外用户群体；但尚未见到独立第三方平台上的具名评测文章。
9. 其他补充
该技能是 metabase/agent-skills 官方合集仓库的一部分，同一仓库内还包含 CLI、嵌入式 SSO 实现、嵌入方案升级迁移、内容表示格式理解、语义校验器等其他技能，可按需单独安装；仓库内另有面向初学者的教学技能 Metabase Learning，一个教产品概念、一个同步真实 schema，功能互补。
10. 安装使用方式
方式一：官方 CLI 安装（推荐）
npx skills add metabase/agent-skills --skill metabase-database-metadata -a claude-code方式二：安装整个合集
npx skills add metabase/agent-skills -a claude-code方式三：手工安装
git clone https://github.com/metabase/agent-skills.git
# 将 skills/metabase-database-metadata 目录复制到对应 Agent 的 skills 目录安装后无需重启。首次需要了解某个 Metabase 实例的表结构时，直接向 Agent 提出相关请求（如“帮我看看 ORDERS 表有哪些字段”），技能会询问 METABASE_URL 与 METABASE_API_KEY 后自动完成导出与提取；之后的会话会直接复用磁盘上已有的元数据树，不会重复拉取。
11. 注意事项
- 需要用户自备可访问的 Metabase 实例及具备序列化导出权限的 API Key，无实例则无法使用。
- 原始导出的
table_metadata.json在大型数据仓库场景下可能达数 GB，需加入.gitignore，否则拖慢仓库。 - 元数据不会自动刷新，实例 schema 变更后 Agent 可能基于过时结构作答，需用户主动要求刷新。
- 未针对 Codex、OpenClaw、Hermes Agent 做过验证，跨 Agent 使用效果未知。