metabase-representation-format
Understands the Metabase Representation Format — a YAML-based serialization format for Metabase content (collections, cards, dashboards, documents, segments, measures, snippets, transforms, actions, and data apps). 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.
- Installs
- 535
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/metabase/agent-skills --skill metabase-representation-format- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads metabase-representation-format automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Metabase Representation Format
Metabase represents user-created content as a tree of YAML files. Each file is one entity (a collection, card, dashboard, etc.). The format is portable across Metabase instances: numeric database IDs are replaced with human-readable names and entity IDs.
The format is defined by a spec bundled alongside this file as spec.md (upstream source: the @metabase/representations npm package). The same package ships a CLI (npx @metabase/representations validate-schema) that validates a tree of YAML files against the format.
Entities
The format defines 14 entity types.
| Entity | SerDes Model | Description |
|---|---|---|
| Collection | Collection | Folder-like container for organizing content. Hierarchy via parent_id. Namespaces: null (main), "snippets", "transforms", "data-actions", "data-apps". |
| Card | Card | Question, model, or metric. Holds an MBQL or native dataset_query. Display types: table, bar, line, pie, scalar, etc. Card types: "question", "model", "metric". |
| Dashboard | Dashboard | Grid layout (24 columns) of cards with filter parameters and optional tabs. Contains dashcards array for card placement and parameters array for filter controls. |
| Document | Document | Rich text page using ProseMirror AST. Can embed cards via cardEmbed nodes and link to entities via smartLink nodes. |
| Segment | Segment | Saved filter definition scoped to a table. Definition is a pMBQL query with a single stage containing only source-table and filters. |
| Measure | Measure | Saved aggregation definition scoped to a table. Definition is a pMBQL query with a single stage containing only source-table and exactly one aggregation. |
| Snippet | NativeQuerySnippet | Reusable SQL fragment referenced in native queries via {{snippet: Name}}. |
| Transform | Transform | Materializes query or Python script results into a database table. Source is either MBQL/native query or Python script. |
| TransformTag | TransformTag | Label for categorizing transforms. Built-in types: "hourly", "daily", "weekly", "monthly", or null for custom. |
| TransformJob | TransformJob | Scheduled job (cron) that executes transforms matching specific tags. |
| TransformTest | TransformTest | Runs a transform against test inputs and checks its output against expectations. Stored next to its transform: collections/transforms/{transform_slug}/{test_slug}.yaml. |
| PythonLibrary | PythonLibrary | Shared Python source file available to Python-based transforms. |
| Action | Action | Writes to a database. type is "query" (parameterized native SQL); "implicit" and model_id are deprecated. Without a model_id it lives in the data-actions namespace (its root or a data actions collection) or in a data app's collection, set by collection_id; data apps run only those. Exactly one of the nested query and implicit arrays holds the definition its type names; the other is []. |
| Data App | DataApp | A custom React app that runs inside Metabase, in data_apps/<slug>/: a data_app.yaml manifest (with serdes/meta [{model: DataApp}], and slug equal to the directory name), its built bundle beside it, and a root Collection of the data-apps namespace under collections/data_apps/ holding the Cards and Actions it runs. |
Ownership and hierarchy
Critical — folder layout is decorative. Where an entity lands in Metabase is decided entirely by its fields, not by where its YAML file sits in the tree. Moving a file without updating the fields changes nothing. Updating the fields without moving the file still works correctly. Always treat the fields below as the source of truth.
The fields that actually determine placement:
collection_id(entity_id of a collection) — places the entity in that collection.nullor omitted → root collection.parent_idon a collection — this, and only this, sets the collection's own parent. A collection's position in the folder tree is ignored on import; withoutparent_id(or withparent_id: null) the collection becomes a root-level collection, no matter how deep its folder is nested. To nest one collection under another, setparent_idto the parent collection'sentity_id.dashboard_id/document_idon a card — nests a card under a dashboard or document. Such a card must also setcollection_idto match the parent'scollection_id. A card never sets both.
On disk, cards nested under a dashboard or document live in a subfolder next to the parent YAML (e.g. my_dashboard/card.yaml sitting next to my_dashboard.yaml) — but again, this is purely for human navigation; the fields are what Metabase reads.
Import paths
Metabase only imports YAML from these top-level directories; anything outside is ignored:
collections/— all user content (cards, dashboards, documents, actions, snippets, transforms, etc.), partitioned by namespace:main/,snippets/,transforms/,data_actions/,data_apps/.databases/— thesegments/andmeasures/subdirectories under each table, and each Library-published table's metadata.python_libraries/(also accepted aspython-libraries/).glossary/— glossary terms (not covered by the spec).transforms/— containstransform_jobs/andtransform_tags/.actions/— legacy location for actions, still read on import. New exports write an action in its collection's directory, beside that collection's cards, not in anactions/subdirectory.data_apps/<slug>/— a data app'sdata_app.yamland its built bundle. The app's collection, with its cards and actions, is undercollections/data_apps/.
serdes/meta
Every entity carries a top-level serdes/meta array with a single entry naming its model; Metabase derives the identity from the entity's own fields (entity_id, or name and table_id for a Field). Older exports carry the full identity path instead ({id, model, label?} per entry), which Metabase still imports. Example:
serdes/meta:
- model: Card
validate-schema reads serdes/meta to determine which entity type each file represents. The full rules (including nested entities and composite identity paths) are in spec.md.
Reading the spec
This skill ships with a local snapshot of the spec as spec.md alongside SKILL.md.
Beyond the per-entity shapes summarized in this SKILL, spec.md also covers: MBQL query form (stages, field references, joins, expressions, aggregations, filter/expression operators, temporal bucketing, binning), native queries and template tags (text, number, date, boolean, dimension, temporal-unit, card, snippet, table), visualization settings, click behavior, dashboard/card parameters, and the data app layout (data_apps/<slug>/data_app.yaml and the app's collection under collections/data_apps/). Reach for spec.md whenever edits touch any of those.
Read on demand, not eagerly. Open spec.md only when you are about to read or modify content files for the entities listed above — e.g. the user asks to edit a card, add a dashcard, tweak a transform, or similar work that implies YAML edits. Do not open it at session start or for tasks unrelated to representation YAML.
If the bundled copy looks out of date with the upstream package, the skill's own README.md documents how to refresh it with extract-spec.
Validating
Validate edits with the built-in CLI:
npx @metabase/representations validate-schema --folder <path>
Pass the top-level export folder, or the git repository root. The tool walks the import paths listed above, reads serdes/meta on each file to pick the right validation rules, and exits non-zero on failure. Prefer running this over manually cross-checking field shapes. It's essentially instant, so invoke it whenever useful — after each edit, between edits, whenever the shape of a file feels uncertain. No reason to batch.
Generating entity IDs
Every entity needs a 21-character NanoID for entity_id. Generate one (or several) with the bundled CLI:
npx @metabase/representations generate-entity-id
# → LZfXLFzPPR4NNrgjlWDxn
npx @metabase/representations generate-entity-id --count 5
Generating UUIDs
Some fields in the format require v4 UUIDs rather than NanoIDs — notably lib/uuid on MBQL aggregation clauses (referenced from order-by and later stages) and the id on dashboard/card parameters. Generate them with:
npx @metabase/representations generate-uuid
# → 1d4e9fdf-49ae-4fbe-ae27-05e7c6a5cfe8
npx @metabase/representations generate-uuid --count 3
FAQ
What does the metabase-representation-format skill do?
Understands the Metabase Representation Format — a YAML-based serialization format for Metabase content (collections, cards, dashboards, documents, segments, measures, snippets, transforms, actions, and data apps). 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.
How do I install metabase-representation-format?
Run npx skills add https://github.com/metabase/agent-skills --skill metabase-representation-format in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/metabase-representation-format/ (personal) or .claude/skills/metabase-representation-format/ (project).
Which AI agents can use metabase-representation-format?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is metabase-representation-format safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains metabase-representation-format?
It is published by metabase in metabase/agent-skills. It has 535 recorded installs.
More from metabase/agent-skills
rde
metabase/agent-skills
Expert data engineering with Metabase at the center of any company's stack: explore and profile raw warehouse tables, build clean tables as Metabase transforms pinned by transform tests, build the semantic layer (models, metrics, measures, segments, metadata), design dashboards, answer questions with checked numbers, reconcile against a reference, change delivered definitions safely. Use for data work, not one mb command (metabase-cli): "make sense of my data", "model this raw schema", "set up analytics for X", "build a data model", "define MRR / active customers officially", "build a semantic layer", "go from raw tables to a dashboard", "does this number match finance", "our numbers look wrong", "two cards disagree", "test this transform", "why does this transform get case X wrong", "make Metabot answer questions about X", "explain this table", "change this definition", "build a data app", "donor retention", "event attendance", "quarterly board report", "be my data engineer / anal
rde-data-apps
metabase/agent-skills
Build or change a Metabase data app on an rde machine: settles what the metabase-data-apps skill needs from the local setup (the remote-sync repository, the Metabase URL, the API key rde stores, how the app reaches Metabase), makes sure everything the app reads is Library content already synced into that repository, confirms every sync step with the user, and hands the build to it. Use only when an app is asked for explicitly: "build me an app for X", "create a data app", "make an internal tool / portal in Metabase", "add a page / a form / a filter to my data app". A dashboard, a question, or a metric is not an app; those stay with the rde skill.
metabase-cli
metabase/agent-skills
Drive a Metabase instance from the terminal via the mb CLI: auth profiles, databases and schemas, schema sync and field-values rescan, tables, fields, cards (questions, models, metrics) run as JSON/CSV/XLSX, dashboards and dashcards, collections and their tree, snippets, segments, measures, transforms and transform-jobs, settings, search, git-sync. Use for any Metabase operation from the terminal: "log into metabase", "what profiles do I have", "list cards", "run card 42 as CSV", "create a transform", "list dashboards", "move a dashcard", "list collections", "what's in collection 4", "show the collection tree", "list snippets", "create a segment", "archive a measure", "search metabase for X", "import the latest changes", "add a directory to git sync", "set a setting", "what schemas are in this database", "trigger a sync", "rescan field values", or any mb . Whole data jobs go to rde.
metabase-database-metadata
metabase/agent-skills
Understands the Metabase Database Metadata Format — a YAML-based on-disk representation of databases, tables, and fields synced from a Metabase instance. Use when the user needs to read, edit, or understand metadata files produced by @metabase/database-metadata, or when reasoning about a project's schema (columns, types, FK relationships) through the .metadata/databases folder.
metabase-semantic-checker
metabase/agent-skills
Open the skill to read its SKILL.md instructions.
metabase-modular-embedding-version-upgrade
metabase/agent-skills
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.
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available