跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

metabase-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.

metabase · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add metabase/agent-skills --skill metabase-full-app-to-modular-embedding-upgrade

技能说明


name: metabase-full-app-to-modular-embedding-upgrade description: 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. model: opus allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion

Execution contract

Follow the workflow steps in order — do not skip any step. Create the checklist first, then execute each step and explicitly mark it done with evidence. Each step's output feeds into the next, so skipping steps produces wrong migrations.

If you cannot complete a step due to missing info or tool failure, you must:

  1. record the step as ❌ blocked,
  2. explain exactly what is missing / what failed,
  3. stop (do not proceed to later steps).

Required output structure

Your response should contain these sections in this order:

  1. Step 0: Metabase Version Detection
  2. Step 0.1: Migration Plan Checklist
  3. Step 1: Project Scan
  4. Step 2: iframe Analysis & Web Component Mapping
  5. Step 3: Migration Plan
  6. Step 4: Applied Code Changes
  7. Step 5: Validation
  8. Step 6: Final Summary

Each step section should end with a status line:

  • Status: ✅ complete or Status: ❌ blocked

Steps are sequential — do not start a step until the previous one is ✅ complete.

Evidence requirements

  • Step 0: Metabase version detected (source: Docker tag, env var, or user answer).
  • Step 1: every matched file path, every iframe location, SSO endpoint, layout/head file, Metabase config variables.
  • Step 2: per iframe — parsed URL, content type, ID, hash params, mapped web component with attributes.
  • Step 3: the complete file-by-file change plan with exact old/new code.
  • Step 4: per file — what was changed and exact diffs applied.
  • Step 5: each validation check's pass/fail result with evidence.

Architectural conformance

Follow the app's existing architecture, template engine, layout/partial system, code style, and route patterns. Do not switch paradigms (e.g., templates to inline HTML or vice versa). If the app has middleware for shared template variables, prefer that over duplicating across route handlers.

Performance

  • Maximize parallelism within each step. Use parallel Grep/Glob/Read calls in a single message wherever possible.
  • Do not use sub-agents for project scanning — results need to stay in the main context for cross-referencing in later steps.
  • Do not parse repo branches, commits, PRs, or issues.

Scope

This skill converts Full App / Interactive embedding (iframe-based) to Modular embedding (web-component-based via embed.js).

The consumer's app may be written in any backend language (Node.js, Python, Ruby, PHP, Java, Go, .NET, etc.) with any template engine. Keep instructions language-agnostic unless a specific language is detected in Step 1.

What this skill handles

  • Replacing <iframe> elements pointing to Metabase with appropriate web components (e.g. <metabase-question>, <metabase-dashboard>)
  • Adding the embed.js script tag (exactly once at app layout level)
  • Adding window.metabaseConfig setup code (exactly once at app layout level)
  • Modifying SSO/JWT endpoints to support modular embedding's JSON response format
  • Mapping iframe URL customization parameters to theme config and component attributes

What this skill does not handle

  • Migrating from Static (signed/guest) embedding

Allowed documentation sources

Fetch the version-specific llms-embedding-full.txt using this URL:

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

The version in the URL uses the format v0.58 (normalize: strip leading v or 0., drop patch — e.g., 0.58.1 → 58 → URL uses v0.58). This single file contains all embedding documentation for that version, optimized for LLM consumption.

Other constraints:

  • No GitHub PRs/issues or npm pages
  • Do not follow changelog links to GitHub or guess URLs

AskUserQuestion triggers

Use AskUserQuestion and halt until answered if:

  • The Metabase instance URL cannot be determined from project code or environment variables
  • Always ask for the Metabase instance version — do not rely solely on code detection
  • An iframe URL pattern does not match any known resource type (dashboard, question, collection, home)
  • No SSO/JWT endpoint can be identified in the project
  • No layout/head file can be identified (unclear where to inject embed.js)
  • Multiple layout files exist and it is unclear which one(s) to use
  • The backend language cannot be determined
  • Multiple iframes specify different locale values (ask user which locale to set in window.metabaseConfig)

Pre-workflow steps

Migration Plan Checklist

Create a checklist to track progress. In Claude Code, use TaskCreate/TaskUpdate tools:

  • Step 0: Detect Metabase version
  • Step 1: Scan project + fetch target version docs
  • Step 2: Analyze iframes and map to web components (using docs)
  • Step 3: Plan migration changes
  • Step 4: Apply code changes
  • Step 5: Validate changes
  • Step 6: Final summary

Workflow

Step 0: Detect Metabase instance version

Always AskUserQuestion for the Metabase instance version — even if a version appears in Docker tags or env vars, confirm it with the user. Abort if v52 or older (modular embedding was introduced in v53).

Then fetch llms-embedding-full.txt for the confirmed version (see "Allowed documentation sources" for URL format).

Before anything else, determine the Metabase version. Grep the project for Docker image tags (metabase/metabase:v, metabase/metabase-enterprise:v), METABASE_VERSION, or version references. If undetected, AskUserQuestion (options: v52 or older, v53, v54–v58, v59+). Abort if v52 or older (modular embedding not available — it was introduced in v53). Record the version — it controls `jwtP

阅读完整来源 ↗