Agent skill · software engineering · metabase
metabase-data-app-semantic-layer
Use when building, creating, or editing data apps that should query Metabase tables and metrics through generated schema files like metabase.data.ts or *.metabase.data.ts.
Why this skill is useful
Provides specific patterns and practices for building Metabase data apps that the AI wouldn't reliably generate on its own.
What it needs
About 10k tokens when loaded. Last updated 2026-08-07. 48,568 stars on the source repository.
What this skill does
Metabase Data App Semantic Layer Core Rules Keep the semantic layer and presentation layer separate. All Metabase context must come from the generated schema file, usually src/metabase.data.ts or src/.metabase.data.ts. Do not discover data through MCP tools, create Metabase content, create tables, or edit the semantic layer while building the React UI. Import data app query helpers from @metabase/embedding-sdk-react/data-app. Prefer generated schema objects over raw IDs or strings. Extract local constants for top-level table objects. Never hand-write DatasetQuery/MBQL objects in app code. Do not pass inline query objects like { type: "query", query: { "source-table": table.id } }, raw source-table clauses, raw field IDs, bare table IDs, or metric IDs to SDK components, useMetabaseQuery, or useMetabaseQueryObject. Prefer generated table and metric schema objects; for simple table-source queries, an explicit source reference like { type: "table", id: table.id } is also valid. Build queries with source: schema.tables.<name> or source: schema.questions.<name>, generated fields, generated segments, generated measures, generated metrics in aggregations, generated metric dimensions, generated question columns, filter(...), breakout(...), orderBy(...), and aggregations helpers such as aggregations.count() and aggregations.sum(...). Do not use source: schema.metrics.<name>; metrics are aggregation expressions, not query sources. Prefer semantically rich table queries over shallow table dumps. Use curated table measures, segments, filters, and breakouts when they make the generated app more useful. Prefer semantic-layer definitions over React-side inference. If the schema has a segment or measure for a concept, use it instead of recreating the concept from raw rows. Filter UI must default to showing data. Empty controls, "All" options, and incomplete custom ranges should produce no filter instead of blocking queries or showing a blank dashboard. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills metabase/metabase-data-app-semantic-layer