metabase-database-metadata
Metabase Database Metadata Format
Metabase represents database metadata — synced databases, their tables, and their fields — as a tree of YAML files. Files are diff-friendly: numeric IDs are omitted entirely, and foreign keys use natural-key tuples like ["Sample Database", "PUBLIC", "ORDERS"] instead of database identifiers.
The format is defined by a specification bundled alongside this file as spec.md (upstream source: metabase/database-metadata). The same project ships a CLI (@metabase/database-metadata on npm) that converts the raw JSON exported from a Metabase instance into the YAML tree described by the spec.
Canonical layout
All metadata for a project lives under a top-level .metadata/ directory:
.metadata/databases/— the YAML tree. This is the canonical source for the agent. Read these files to understand the schema, columns, types, and FK relationships..metadata/table_metadata.json— the raw JSON exported from the Metabase instance. Potentially multi-megabyte (or multi-gigabyte) JSON with flatdatabases/tables/fieldsarrays. Never open, grep, or pass it to tools. It exists only as input to the extractor.
The .metadata/ directory should be gitignored. On large warehouses the extracted metadata can reach gigabytes — committing it would make the repo painful or unusable.
First-time setup
Do not run any of the steps below proactively at session start. Only run them when the user explicitly asks to fetch metadata, set up the workflow, or requests something that plainly requires knowledge of the database schema (e.g. "write a query against ORDERS", "describe what tables exist").
More from metabase/agent-skills
metabase-representation-format
Understands the Metabase Representation Format — a YAML-based serialization format for Metabase content (collections, cards, dashboards, documents, segments, measures, snippets, transforms). Use when the user needs to create, edit, understand, or validate Metabase representation YAML files, or when working with Metabase serialization/deserialization (serdes). Covers entity schemas, MBQL and native queries, visualization settings, parameters, and folder structure.
75metabase-modular-embedding-version-upgrade
Upgrades a project's Metabase Modular embedding SDK (@metabase/embedding-sdk-react) or Modular embedding (embed.js) version. Use when the user wants to upgrade their Metabase modular embedding integration to a newer version.
62metabase-embedding-sso-implementation
Implements JWT SSO authentication for Metabase embedding in a project. Supports all embedding types that use SSO — Modular embedding (embed.js web components), Modular embedding SDK (@metabase/embedding-sdk-react), and Full app embedding (iframe-based). Creates the JWT signing endpoint, configures the frontend auth layer, and sets up group mappings. Use when the user wants to add SSO/JWT auth to their Metabase embedding, implement user identity for embedded analytics, set up JWT authentication for Metabase, or connect their app's authentication to Metabase embedding.
52metabase-static-embedding-to-guest-embedding-upgrade
Migrates a project from Metabase static embedding to guest embeds (web components via embed.js). Use when the user wants to migrate/convert/switch/upgrade from static embedding to guest embeds, from signed embed iframes to web components, or replace /embed/ iframes with metabase-dashboard/metabase-question components.
49metabase-full-app-to-modular-embedding-upgrade
Migrates a project from Metabase Full App / Interactive (iframe-based) embedding to Modular (web-component-based) embedding. Use when the user wants to replace Metabase iframes with Modular embedding web components.
47metabase-modular-embedding-to-modular-embedding-sdk-upgrade
Migrates a React project from Metabase Modular embedding (embed.js web components) to the Modular embedding SDK (@metabase/embedding-sdk-react). Use when the user wants to switch from embed.js web components to React SDK components (MetabaseProvider). This is not a version upgrade — it changes the embedding technology.
46