### Install All Metabase Agent Skills

Source: https://github.com/metabase/agent-skills/blob/main/README.md

Installs all available agent skills for Metabase at once. Use this for a comprehensive setup.

```sh
npx skills add metabase/agent-skills -a claude-code
```

--------------------------------

### Load Metabase CLI Skill Content

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-cli/SKILL.md

Use these commands to load and explore the Metabase CLI skill content. Start with 'get core' to understand authentication and command groups, 'list' to see available skills, and 'get <name>' for specific skills.

```bash
mb skills get core      # start here — auth, flag conventions, every command group
```

```bash
mb skills list          # enumerate specialized skills bundled with this CLI version
```

```bash
mb skills get <name>    # load a specialized skill (workspace, transform, git-sync, …)
```

--------------------------------

### Go JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Install the 'github.com/golang-jwt/jwt/v5' package for Go projects to handle JWT operations.

```bash
go get github.com/golang-jwt/jwt/v5
```

--------------------------------

### Install Metabase CLI and Agent Skill

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-cli/README.md

Installs the Metabase CLI globally and then adds the agent-skills stub for the metabase-cli skill.

```bash
npm i -g @metabase/cli                                                # CLI itself
npx skills add metabase/agent-skills --skill metabase-cli             # this stub
```

--------------------------------

### Install Metabase CLI and Agent Skill via Plugin

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-cli/README.md

Installs both the stub and the marketplace entry directly from the CLI repo using plugin commands.

```bash
/plugin marketplace add metabase/mb-cli
/plugin install metabase-cli@metabase
```

--------------------------------

### Per-File Output Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-version-upgrade/SKILL.md

An example of the output generated during the per-file migration process, highlighting catalog matches, analysis of code changes, and applied fixes.

```text
## src/components/CollectionPage.tsx

### Catalog matches:
- SdkCollectionId type widening → affects `onClick` callback
- (no other catalog entries match this file)

### Analysis:
- `onClick: (item) => setSelectedId(item.id)`
  - `item.id` is now `SdkCollectionId` (number | "personal" | "root" | "tenant" | SdkEntityId)
  - `setSelectedId` is `useState<number | undefined>[1]`
  - 🔴 BREAKING: string variants won't fit `number` state

### Fix applied:
- Widened state: `useState<number | undefined>` → `useState<SdkCollectionId | undefined>`
- Added import: `import type { SdkCollectionId } from '@metabase/embedding-sdk-react'`

Status: ✅ complete
```

--------------------------------

### Ruby JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Install the 'jwt' gem for Ruby projects to handle JWT operations.

```bash
gem install jwt
```

--------------------------------

### Node.js JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Install the 'jsonwebtoken' library for Node.js projects to handle JWT operations.

```bash
npm install jsonwebtoken
```

--------------------------------

### Widget Products Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Example YAML definition for a widget that displays product information. It specifies the query to fetch data from the 'PRODUCTS' table with a filter on 'CATEGORY'.

```yaml
name: Widget products
entity_id: aB3kLmN9pQrStUvWxYz1a
creator_id: internal@metabase.com
definition:
  "lib/type": mbql/query
  database: Sample Database
  stages:
  - "lib/type": mbql.stage/mbql
    source-table:
    - Sample Database
    - PUBLIC
    - PRODUCTS
    filters:
    - - =
      - {}
      - - field
        - {}
        - - Sample Database
          - PUBLIC
          - PRODUCTS
          - CATEGORY
      - Widget
serdes/meta:
- id: aB3kLmN9pQrStUvWxYz1a
  label: widget_products
  model: Segment
```

--------------------------------

### Table Metadata Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-database-metadata/spec.md

An example of a table's metadata, including its name, database ID, schema, description, and fields.

```yaml
name: ORDERS
db_id: Sample Database
schema: PUBLIC
description: Confirmed Sample Company orders for a product, from a user.
fields:
  - name: ID
    base_type: type/BigInteger
    database_type: BIGINT
    semantic_type: type/PK
  - name: TOTAL
    description: The total billed amount.
    base_type: type/Float
    database_type: DOUBLE PRECISION
```

--------------------------------

### Change Catalog Format Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-version-upgrade/SKILL.md

An example of the structured format for a change catalog, detailing version differences, specific API changes, and their severity. This format is used as input for subsequent upgrade steps.

```markdown
## Change Catalog (v0.54 → v0.58)

### fetchRequestToken
- Change: signature changed
- Old: `(url: string) => Promise<any>`
- New: `() => Promise<{jwt: string}>` (resolved from `MetabaseFetchRequestTokenFn`)
- Severity: 🔴 Breaking

### SdkCollectionId (type widening)
- Change: type widened
- Old: `number`
- New: `number | "personal" | "root" | "tenant" | SdkEntityId`
- Affects: any prop/callback param typed as `SdkCollectionId`, including `item.id` in CollectionBrowser callbacks
- Severity: 🔴 Breaking for code storing in `number`-typed variables

### SdkDashboardId (type widening)
- Change: type widened
- Old: `number`
- New: `number | string | SdkEntityId`
- Affects: any prop/callback param typed as `SdkDashboardId`
- Severity: 🔴 Breaking for code storing in `number`-typed variables

### jwtProviderUri
- Change: new property added to `MetabaseProvider` authConfig
- Severity: 🟢 Info — can replace manual `fetchRequestToken`

### questionHeight
- Change: new optional prop on `StaticQuestion`
- Severity: 🟢 Info
```

--------------------------------

### Database YAML Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-database-metadata/spec.md

An example of a database entry in YAML format. This defines the database's name and the engine type it uses.

```yaml
name: Sample Database
engine: postgres
```

--------------------------------

### Document Structure Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

An example of a Metabase document structure, including headings, paragraphs, card embeds, and bullet lists.

```yaml
name: Product Analysis Report
entity_id: dOc1PrOdAnAlYsIsRpTx2
creator_id: internal@metabase.com
document:
  type: doc
  content:
  - type: heading
    attrs:
      level: 1
    content:
    - type: text
      text: Product Analysis Report
  - type: paragraph
    content:
    - type: text
      text: "Overview of product performance metrics."
  - type: cardEmbed
    attrs:
      id:
      - model: Card
        id: h5F2EjHsRd73Dqqh8sAtd
      name: Basic Aggregations
  - type: bulletList
    content:
    - type: listItem
      content:
      - type: paragraph
        content:
        - type: text
          text: Revenue increased 15% quarter over quarter
    - type: listItem
      content:
      - type: paragraph
        content:
        - type: text
          text: Widget category remains the top performer
content_type: "application/json+vnd.prose-mirror"
collection_id: null
serdes/meta:
- id: dOc1PrOdAnAlYsIsRpTx2
  label: product_analysis_report
  model: Document
```

--------------------------------

### Python JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Install the 'PyJWT' library for Python projects to handle JWT operations.

```bash
pip install PyJWT
```

--------------------------------

### Install Metabase Embedding SDK

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Install the Metabase embedding SDK package using your package manager. Replace `{package-manager}` with `npm`, `yarn`, or `pnpm`, and `{TARGET_VERSION}` with the desired SDK version.

```bash
{package-manager} add @metabase/embedding-sdk-react@{TARGET_VERSION}
```

--------------------------------

### Web Component to React Component Conversion Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Example of converting a Metabase web component to its corresponding SDK React component, including attribute-to-prop mapping and type conversion.

```typescript
src/Dashboard.tsx | <metabase-dashboard dashboard-id="1"> | <InteractiveDashboard dashboardId={1} /> | dashboard-id → dashboardId
```

--------------------------------

### Authentication and Configuration Mapping Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Maps fields from the global `window.metabaseConfig` object to the `MetabaseProvider` configuration object in the SDK, noting potential renames and required checks against the d.ts file.

```markdown
### Auth & Config
- window.metabaseConfig.instanceUrl → config.metabaseInstanceUrl (check d.ts for exact field name)
- window.metabaseConfig.jwtProviderUri → authConfig.jwtProviderUri or authConfig.authProviderUri or config.authProviderUri (check d.ts — the field was renamed from `jwtProviderUri` to `authProviderUri` in some versions)
- window.metmetabaseConfig.locale → locale prop or config field (check d.ts)
```

--------------------------------

### Example Scan Output Grouped by Category

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Illustrates the expected output format after scanning for Metabase usage, categorized by component type, configuration, and script tags.

```text
Web components (JSX/TSX):
  - src/pages/Dashboard.tsx:15 — <metabase-dashboard dashboard-id="123">
  - src/pages/Analytics.tsx:22 — <metabase-question question-id="456">
Config:
  - public/index.html:8 — window.metabaseConfig = { ... }
Script tag:
  - public/index.html:12 — <script defer src="...embed.js"></script>
```

--------------------------------

### Root Collection Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Defines a minimal root-level collection. Ensure 'name', 'entity_id', and 'serdes/meta' are provided.

```yaml
name: Minimal
entity_id: cOlMiNiMaL000ExAmPlx2
slug: minimal
serdes/meta:
- id: cOlMiNiMaL000ExAmPlx2
  label: minimal
  model: Collection
```

--------------------------------

### PHP JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Install the 'firebase/php-jwt' library for PHP projects using Composer to handle JWT operations.

```bash
composer require firebase/php-jwt
```

--------------------------------

### TransformJob Tags Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

An example of how to associate a TransformJob with specific TransformTags using entity IDs and positions.

```yaml
job_tags:
- entity_id: BPhRX8sTqcG5tZrXKeQuP
  position: 0
  tag_id: mXacguzCHQ5bBhqQPt3kd        # entity_id of the "daily" tag
  serdes/meta:
  - id: BPhRX8sTqcG5tZrXKeQuP
    model: TransformJobTransformTag
```

--------------------------------

### Column Settings Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Configure formatting for specific columns, such as currency, date styles, and link views. Use 'column_settings' keyed by column name.

```yaml
column_settings:
  '["name","TOTAL"]':
    number_style: currency
    currency: USD
    currency_style: symbol        # "symbol", "code", "name"
    number_separators: ".,"
    decimals: 2
    scale: 1                      # multiply values by this factor
    prefix: ""
    suffix: ""
    column_title: "Total Revenue"
  '["name","CREATED_AT"]':
    date_style: "MMMM D, YYYY"   # moment.js format
    date_separator: "/"
    date_abbreviate: false
    time_enabled: null            # null, "minutes", "seconds", "milliseconds"
    time_style: "h:mm A"         # "HH:mm", "h:mm A", etc.
  '["name","EMAIL"]':
    view_as: link                 # "link", "image", "email", "auto"
    link_text: "Send email"
    link_url: "mailto:{{value}}"
```

--------------------------------

### .NET JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Add the 'System.IdentityModel.Tokens.Jwt' package to your .NET project for JWT operations.

```bash
dotnet add package System.IdentityModel.Tokens.Jwt
```

--------------------------------

### Dashboard Card Configuration Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

This YAML snippet demonstrates the structure of a Metabase dashboard, including its parameters, tabs, and dashcards with parameter mappings and series overlays.

```yaml
name: Orders Overview
entity_id: Q_jD-f-9clKLFZ2TfUG2h
creator_id: internal@metabase.com
width: fixed
auto_apply_filters: true
parameters:
- id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  name: Category
  slug: category
  type: string/=
tabs:
- entity_id: tAb1dEntIdHere1234x5
  name: Overview
  position: 0
- entity_id: tAb2dEntIdHere1234x5
  name: Details
  position: 1
dashcards:
- entity_id: UkpFcfUZMZt9ehChwnrAO
  card_id: f1C68pznmrpN1F5xFDj6d
  dashboard_tab_id: tAb1dEntIdHere1234x5
  row: 0
  col: 0
  size_x: 12
  size_y: 6
  parameter_mappings:
  - card_id: f1C68pznmrpN1F5xFDj6d
    parameter_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    target:
    - dimension
    - - field
      - - Sample Database
        - PUBLIC
        - PRODUCTS
        - CATEGORY
      - null
  series:
  - card_id: OMuZ0wHe2O5Z_59-cLmn4
    position: 0
  visualization_settings: {}
  serdes/meta:
  - id: Q_jD-f-9clKLFZ2TfUG2h
    model: Dashboard
  - id: UkpFcfUZMZt9ehChwnrAO
    model: DashboardCard
serdes/meta:
- id: Q_jD-f-9clKLFZ2TfUG2h
  label: orders_overview
  model: Dashboard

```

--------------------------------

### Install Metabase Embedding SDK for React

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

Install the Metabase Embedding SDK for React using the correct dist-tag that matches your Metabase instance's major version. This command is typically found in the versioned docs index (llms.txt).

```bash
npm install @metabase/embedding-sdk-react@<VERSION>
```

--------------------------------

### Field Metadata Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-database-metadata/spec.md

An example of a field's metadata, detailing its name, database type, base type, and semantic type.

```yaml
name: CREATED_AT
description: The order creation timestamp.
base_type: type/Text
database_type: TEXT
effective_type: type/DateTime
semantic_type: type/CreationTimestamp
coercion_strategy: Coercion/ISO8601->DateTime
```

--------------------------------

### Group Mapping Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Provides an example of mapping application-specific roles to Metabase group names. This ensures users are assigned the correct permissions within Metabase.

```plaintext
App role "admin"    → Metabase group "Administrators"
App role "analyst"  → Metabase group "Analysts"
App role "viewer"   → Metabase group "Viewers"
```

--------------------------------

### Nested Field Metadata Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-database-metadata/spec.md

An example demonstrating how nested fields are represented using the 'parent_id' field.

```yaml
name: name
base_type: type/Text
database_type: TEXT
parent_id:
  - Sample Database
  - PUBLIC
  - EVENTS
  - DATA
  - user
```

--------------------------------

### Install Specific Metabase Agent Skill

Source: https://github.com/metabase/agent-skills/blob/main/README.md

Installs a particular agent skill for Metabase, such as the modular embedding version upgrade. Specify the skill name with the --skill flag.

```sh
npx skills add metabase/agent-skills --skill metabase-modular-embedding-version-upgrade -a claude-code
```

--------------------------------

### Example Question Representation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

This YAML snippet shows the structure of a Metabase question, including its name, entity ID, display type, creator, query details, and visualization settings.

```yaml
name: Products question
entity_id: f1C68pznmrpN1F5xFDj6d
display: table
creator_id: internal@metabase.com
type: question
dataset_query:
  "lib/type": mbql/query
  database: Sample Database
  stages:
  - "lib/type": mbql.stage/mbql
    source-table:
    - Sample Database
    - PUBLIC
    - PRODUCTS
visualization_settings: {}
collection_id: M-Q4pcV0qkiyJ0kiSWECl
parameters: []
parameter_mappings: []
serdes/meta:
- id: f1C68pznmrpN1F5xFDj6d
  label: products_question
  model: Card
```

--------------------------------

### Window Function Offset Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Demonstrates the use of the 'offset' window function within an aggregation clause. It retrieves a value from a specified number of rows before or after the current row.

```yaml
aggregation:
- - sum
  - {}
  - - field
    - base-type: type/Float
    - [Sample Database, PUBLIC, ORDERS, TOTAL]
- - offset
  - {}
  - - sum
    - {}
    - - field
      - base-type: type/Float
      - [Sample Database, PUBLIC, ORDERS, TOTAL]
  - -1
```

--------------------------------

### Find Table Candidates for New Dashboards

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

Use this command to find candidate tables in a specific database (ID 1 in this example) for creating new dashboards. Ensure your environment variables (.env.metabase) are sourced.

```bash
source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/database/1/candidates" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"
```

--------------------------------

### Measure Total Revenue Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Example YAML definition for a measure that calculates the total revenue. It uses an MBQL query to sum the 'TOTAL' field from the 'ORDERS' table.

```yaml
name: Total revenue
entity_id: xK7mPqR2sT4uVwXyZ9a1b
creator_id: internal@metabase.com
definition:
  "lib/type": mbql/query
  database: Sample Database
  stages:
  - "lib/type": mbql.stage/mbql
    source-table:
    - Sample Database
    - PUBLIC
    - ORDERS
    aggregation:
    - - sum
      - {}
      - - field
        - base-type: type/Float
        - - Sample Database
          - PUBLIC
          - ORDERS
          - TOTAL
serdes/meta:
- id: xK7mPqR2sT4uVwXyZ9a1b
  label: total_revenue
  model: Measure
```

--------------------------------

### Temporal Bucketing: Month

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Example of using `temporal-unit: month` to group datetime data by month.

```yaml
breakout:
- - field
  - temporal-unit: month
  - [Sample Database, PUBLIC, ORDERS, CREATED_AT]
```

--------------------------------

### Series Settings Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Configure display properties for individual series, such as color, line style, and interpolation. Useful for fine-tuning the appearance of specific data series in a chart.

```yaml
series_settings:
  Revenue:
    display: line
    color: "#509EE3"
    "line.style": solid           # "solid", "dashed", "dotted"
    "line.size": normal           # "S", "M", "L"
    "line.interpolate": linear    # "linear", "cardinal", "step-before", "step-after"
    "line.missing": interpolate   # "interpolate", "zero", "none"
    "line.marker_enabled": true
    axis: left                    # "left", "right"
    show_series_values: true
```

--------------------------------

### Transform Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

A YAML representation of a Metabase Transform, including its name, source query, target details, and collection ID.

```yaml
name: Product summary
entity_id: rT5vWxYz1aBcDeFgHiJkL
creator_id: internal@metabase.com
source_database_id: Sample Database
source:
  type: query
  query:
    "lib/type": mbql/query
    database: Sample Database
    stages:
    - "lib/type": mbql.stage/mbql
      source-table:
      - Sample Database
      - PUBLIC
      - PRODUCTS
target:
  database: Sample Database
  type: table
  schema: PUBLIC
  name: product_summary
collection_id: M-Q4pcV0qkiyJ0kiSWECl
serdes/meta:
- id: rT5vWxYz1aBcDeFgHiJkL
  label: product_summary
  model: Transform
```

--------------------------------

### Java JWT Library Installation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Add the 'io.jsonwebtoken:jjwt' dependency to your Maven or Gradle project for Java JWT operations.

```xml
Add to Maven/Gradle
```

--------------------------------

### Multi-Stage MBQL Query

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Constructs a multi-stage MBQL query where each stage operates on the results of the previous one. This example counts orders and then filters by count.

```yaml
"lib/type": mbql/query
database: Sample Database
stages:
- "lib/type": mbql.stage/mbql
  source-table:
  - Sample Database
  - PUBLIC
  - ORDERS
  aggregation:
  - - count
    - "lib/uuid": 11111111-1111-1111-1111-111111111111
  breakout:
  - - field
    - temporal-unit: month
    - - Sample Database
      - PUBLIC
      - ORDERS
      - CREATED_AT
- "lib/type": mbql.stage/mbql
  filters:
  - - ">"
    - {}
    - - field
      - base-type: type/Integer
      - count
    - 10
```

--------------------------------

### Temporal Bucketing: Day of Week

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Example of using `temporal-unit: day-of-week` to extract the day of the week from datetime data.

```yaml
breakout:
- - field
  - temporal-unit: day-of-week
  - [Sample Database, PUBLIC, ORDERS, CREATED_AT]
```

--------------------------------

### Component Migration Mapping Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Defines how to map attributes from modular embedding web components to their corresponding SDK React component props, including attribute-to-prop name conversion and type resolution.

```markdown
## Migration Mapping

### <metabase-dashboard> → {SDK dashboard component from d.ts}
- `dashboard-id` → `dashboardId` (camelCase)
- `with-title` → `withTitle` (boolean prop)
- `drills` → check d.ts for equivalent prop name
- Other attributes → map to corresponding React props from d.ts

### <metabase-question> → {SDK question component from d.ts}
- `question-id` → `questionId` (camelCase)
- Other attributes → map from d.ts

### <metabase-browser> → {SDK collection component from d.ts}
- `initial-collection` → check d.ts for prop name
- Other attributes → map from d.ts
```

--------------------------------

### Detect Metabase Version

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Use AskUserQuestion to get the Metabase instance version. Abort if the version is v52 or older, as modular embedding was introduced in v53.

```shell
AskUserQuestion(
  "What is the Metabase instance version?",
  {
    "options": [
      "v52 or older",
      "v53",
      "v54–v58",
      "v59+"
    ]
  }
)
```

--------------------------------

### Conditional Formatting Rules Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Define rules for conditional formatting in tables, specifying conditions for applying colors or highlights. Supports single value comparisons and range-based formatting.

```yaml
table.column_formatting:
- columns:
  - Total
  type: single                    # "single" or "range"
  operator: ">"                   # "=", "!=", "<", ">", "<=", ">=", "is-null", "not-null"
  value: 100
  color: "#84BB4C"
  highlight_row: false
- columns:
  - Rating
  type: range
  colors:
  - "#ED6E6E"
  - "#F9CF48"
  - "#84BB4C"
  min_type: custom                # "min", "max", "custom"
  min_value: 1
  max_type: custom
  max_value: 5
```

--------------------------------

### Fields with Expressions

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

When `fields` is present and the stage includes `expressions`, all expressions must be included in the `fields` list as `expression` references. This example shows how `Profit` is defined using fields `TOTAL` and `TAX`.

```yaml
fields:
- - field
  - {}
  - - Sample Database
    - PUBLIC
    - ORDERS
    - TOTAL
- - expression
  - {}
  - Profit
expressions:
- - "-"
  - "lib/expression-name": Profit
  - - field
    - {}
    - [Sample Database, PUBLIC, ORDERS, TOTAL]
  - - field
    - {}
    - [Sample Database, PUBLIC, ORDERS, TAX]
```

--------------------------------

### Parameter Mapping Structure Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Defines the structure for mapping values from a source (column or parameter) to a target (parameter, dimension, or variable). This is a core component for interactive filtering and drill-through.

```yaml
id: target-dimension
source:
  id: PRODUCT_ID
  name: Product ID
  type: column
target:
  id: target-dimension
  type: dimension
  dimension:
  - dimension
  - - field
    - {}
    - - Sample Database
      - PUBLIC
      - PRODUCTS
      - ID
```

--------------------------------

### Prepare and Fetch SDK

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Executes a script to download and extract the target Metabase embedding SDK package. It also fetches the relevant documentation for the SDK version.

```bash
bash <skill-path>/scripts/prepare.sh {TARGET_VERSION}
```

--------------------------------

### Fetch SDK Documentation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Retrieves version-specific embedding documentation from Metabase.com, optimized for LLM consumption. Ensure the version in the URL is correctly formatted.

```bash
https://www.metabase.com/docs/v0.{VERSION}/llms-embedding-full.txt
```

--------------------------------

### Create .env.metabase and .gitignore

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

Creates the `.env.metabase` file for storing Metabase API credentials and adds it to `.gitignore` to prevent accidental commits. This is done if the file does not already exist.

```bash
grep -qxF '.env.metabase' .gitignore 2>/dev/null || echo '.env.metabase' >> .gitignore
printf 'METABASE_INSTANCE_URL=
METABASE_ADMIN_API_KEY=
' > .env.metabase
```

--------------------------------

### JWT Expiration Timestamp Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Example of how to calculate the expiration time for the JWT as a Unix timestamp. Recommends 10 minutes.

```javascript
Math.round(Date.now() / 1000) + 600
```

--------------------------------

### Fetch Metabase Documentation

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Fetch the 'llms-embedding-full.txt' documentation for the confirmed Metabase version. This documentation is crucial for understanding web component attributes and configuration options.

```shell
Fetch("https://raw.githubusercontent.com/metabase/metabase/main/docs/llms-embedding-full.txt")
```

--------------------------------

### Configure Metabase SDK with window.metabaseConfig

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Set the `window.metabaseConfig` object before the `embed.js` script loads. This configuration object is essential for the Metabase SDK to initialize correctly. Ensure `instanceUrl` is dynamically rendered.

```html
<script>
  window.metabaseConfig = {
    instanceUrl: "{METABASE_SITE_URL}",
    // Add auth fields here only if supported by the confirmed version's docs
  };
</script>
```

--------------------------------

### Snippet Active Order Filter Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Example YAML definition for a reusable SQL snippet named 'Active Order Filter'. This snippet filters orders based on status and total amount.

```yaml
name: Active Order Filter
entity_id: xK7mPqR2sT4uVwXyZ9a1b
creator_id: internal@metabase.com
content: "STATUS = 'active' AND TOTAL > 0"
description: Filter for active orders with positive totals
archived: false
collection_id: Y6d4QwJgGKw-X1tRh3ir2
template_tags: {}
serdes/meta:
- id: xK7mPqR2sT4uVwXyZ9a1b
  label: active_order_filter
  model: NativeQuerySnippet
```

--------------------------------

### Subcollection Example with Parent ID

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Defines a subcollection, specifying its parent using 'parent_id'. This links it to an existing collection.

```yaml
name: Reports
entity_id: cOlRePorTs000ExAmPlx2
parent_id: cOlMiNiMaL000ExAmPlx2
serdes/meta:
- id: cOlRePorTs000ExAmPlx2
  label: reports
  model: Collection
```

--------------------------------

### Fetch Versioned Docs Index

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

Fetch the versioned documentation index for LLM integration using the major version obtained previously. Fallback to the 'latest' version if the specific version is not found.

```bash
curl -s https://www.metabase.com/docs/v0.<MAJOR>/llms.txt
```

--------------------------------

### Extract Substring

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Extracts a portion of a string based on a starting position and length. Note that the string indexing is 1-based.

```yaml
- substring
- {}
- - field
  - {}
  - [Sample Database, PUBLIC, PRODUCTS, TITLE]
- 1
- 3
```

--------------------------------

### Scan for Metabase Web Component Usage

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Grep for Metabase web components and global configuration patterns in project files to identify current usage. This step is for discovery and does not involve reading project files.

```bash
grep -r "<metabase-dashboard" --include="*.{jsx,tsx,js,ts}"
grep -r "<metabase-question" --include="*.{jsx,tsx,js,ts}"
grep -r "<metabase-browser" --include="*.{jsx,tsx,js,ts}"
grep -r "window.metabaseConfig" --include="*.{jsx,tsx,js,ts,html}"
grep -r "/app/embed.js" --include="*.html"
```

--------------------------------

### Field Reference with Options

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Demonstrates referencing a field with specific options, such as `base-type` or `temporal-unit`. The options map is always provided, even if empty.

```yaml
- field
- base-type: type/Float
  temporal-unit: "month"
- - Sample Database
  - PUBLIC
  - ORDERS
  - TOTAL
```

--------------------------------

### String Starts With Filter (Multiple Values)

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Filters string fields where the value begins with any of the specified prefixes. Supports case-sensitive and case-insensitive matching.

```yaml
# Multiple values (empty options)
- starts-with
- {}
- - field
  - {}
  - [Sample Database, PUBLIC, PEOPLE, NAME]
- John
- Jane
```

```yaml
# Multiple values, case-insensitive
- starts-with
- case-sensitive: false
- - field
  - {}
  - [Sample Database, PUBLIC, PEOPLE, NAME]
- John
- Jane
- Charlie
```

--------------------------------

### Find Metabase Configuration Variables

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Search for Metabase-related configuration variables prefixed with METABASE_ or MB_. Record variable names and their usage locations.

```shell
Grep("METABASE_", "MB_")
```

--------------------------------

### Identify Backend Language and Framework

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Check for common dependency files to identify the project's backend language, framework, and template engine.

```shell
Scan("package.json", "requirements.txt", "Gemfile", "pom.xml", "go.mod", "composer.json")
```

--------------------------------

### Detect Metabase Version and Properties

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

Fetches Metabase instance properties, including the version tag, using the Metabase API. Requires `METABASE_INSTANCE_URL` and `METABASE_ADMIN_API_KEY` to be set in `.env.metabase`. Parses the tag to determine the edition (OSS/Enterprise) and major version.

```bash
source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/session/properties" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" | grep -o '"tag":"[^"]*"'
```

--------------------------------

### Generate and Save a New Dashboard

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-react-sdk-setup/SKILL.md

These commands first generate a new dashboard based on a table ID and then save it to your Metabase instance. Replace <TABLE_ID> with the actual table identifier. Ensure your environment variables (.env.metabase) are sourced.

```bash
source .env.metabase && \
  DASHBOARD=$(curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/table/<TABLE_ID>" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY")

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/dashboard/save" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$DASHBOARD"
```

--------------------------------

### Read SDK Type Definitions

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-modular-embedding-to-modular-embedding-sdk-upgrade/SKILL.md

Dumps the TypeScript definition (.d.ts) files for the target Metabase embedding SDK to standard output, enabling type checking and IntelliSense.

```bash
bash <skill-path>/scripts/read-sources.sh {SDK_TMPDIR}
```

--------------------------------

### Multiple Aggregations

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Combine multiple aggregation functions, such as `count` and `avg`, to perform several calculations on the same dataset. This example calculates the total count and the average of a specific field.

```yaml
aggregation:
- - count
  - {}
- - avg
  - {}
  - - field
    - base-type: type/Float
    - [Sample Database, PUBLIC, ORDERS, TOTAL]
```

--------------------------------

### Compile Project Inventory

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-full-app-to-modular-embedding-upgrade/SKILL.md

Compile all gathered information into a structured inventory, detailing the backend, Metabase configuration, layout files, iframes, and SSO endpoints.

```json
{
  "Backend": "{language}, {framework}, {template engine}",
  "Metabase config": {
    "Site URL variable": "{name} (read at {file}:{line})",
    "Dashboard path variable": "{name} (read at {file}:{line})",
    "JWT secret variable": "{name} (read at {file}:{line})",
    "Other variables": "..."
  },
  "Layout/head file": "{path}:{line range} (or \"inline HTML in {file}:{line range}\")",
  "Iframes found": "{count}",
  "  - {file}:{line} — {brief description}",
  "  - ...",
  "SSO endpoint": "{file}:{line} — {route} ({method})"
}
```

--------------------------------

### Define Aggregations

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-representation-format/spec.md

Shows how to define aggregations like count and sum. Aggregations referenced elsewhere require a `lib/uuid`.

```yaml
aggregation:
- - count
  - {}
- - sum
  - {}
  - - field
    - base-type: type/Float
    - - Sample Database
      - PUBLIC
      - ORDERS
      - TOTAL
```

--------------------------------

### User Field Mapping Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Defines how to extract user-specific fields like email, first name, last name, and groups from the incoming request object. This is crucial for generating the Metabase JWT.

```javascript
email       ← {source} (e.g., req.user.email)
first_name  ← {source} (e.g., req.user.firstName or req.user.name.split(' ')[0])
last_name   ← {source} (e.g., req.user.lastName or req.user.name.split(' ')[1])
groups      ← {source} (e.g., [req.user.role] or req.user.groups)
```

--------------------------------

### Metabase JWT Payload Mapping Example

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-embedding-sso-implementation/SKILL.md

Illustrates how application user fields are mapped to Metabase JWT fields for SSO. This mapping is crucial for correctly provisioning user accounts and permissions within Metabase.

```markdown
| Metabase field | Source | Example value |
|---|---|---|
| email | req.user.email | "jane@example.com" |
| first_name | req.user.firstName | "Jane" |
| last_name | req.user.lastName | "Doe" |
| groups | [req.user.role] | ["Analyst"] |
| exp | Date.now()/1000 + 600 | 1700000600 |
```

--------------------------------

### Configuring Metabase Guest Embedding

Source: https://github.com/metabase/agent-skills/blob/main/skills/metabase-static-embedding-to-guest-embedding-upgrade/SKILL.md

Add this script to your layout's head section before the embed.js tag to enable guest embedding. Ensure 'isGuest: true' is set. Dynamically render 'instanceUrl' using your project's template expression syntax.

```html
<script>
  window.metabaseConfig = {
    isGuest: true,
    instanceUrl: "{METABASE_SITE_URL}",
  };
</script>
```