How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/metabase/agent-skills --skill metabase-custom-vizBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Metabase custom visualizations
You orchestrate. You talk to the user, pick the flow, run phases, and carry state between them. You do not write viz code outside a phase.
Paths: phases/… and references/… are under <skill-dir>, the directory holding this SKILL.md. <sdk> is node_modules/@metabase/custom-viz/dist in the project. Other paths are relative to the project root. Phase files hold the full instructions for their executor, including their Input:; knowledge lives in references/. Never restate either in a handoff — pass only the phase's input and the paths above.
Setup
- Project: the working directory has
metabase-plugin.jsonand
@metabase/custom-viz in package.json → use it. Otherwise take a name from the request (ask only if there is none) as <name>, run npx @metabase/custom-viz@latest init "<name>", and work in the directory it prints. init lowercases <name> and turns spaces into - for the directory and "name" in package.json and metabase-plugin.json; <name> as given becomes the display name. Keep <name> to letters, digits, spaces and -: init rejects most other characters.
node_modules/missing →npm install.<version>isversionin
node_modules/@metabase/custom-viz/package.json. Its major is below the major of npm view @metabase/custom-viz version → tell the user this skill targets the latest @metabase/custom-viz major, offer to upgrade it, and stop.
- Metabase source: the host rules (sandbox, colors, column types) live
in the public Metabase repo. <ref> is custom-viz-v<version>, the tag the installed SDK was released from. .claude/metabase-src/.ref holds <ref> → the files are cached, skip the download. Otherwise delete .claude/metabase-src/ (an older SDK's copy), then download each file below, keeping its path, with curl (never a web fetch tool: it summarizes); a file missing at <ref> comes from master: curl -fsSL --create-dirs -o .claude/metabase-src/<path> https://raw.githubusercontent.com/metabase/metabase/<ref>/<path> || curl -fsSL --create-dirs -o .claude/metabase-src/<path> https://raw.githubusercontent.com/metabase/metabase/master/<path>
frontend/src/metabase/utils/scripts-sandbox/distortions-dom-mutate.tsfrontend/src/metabase/utils/scripts-sandbox/distortions-event.tsfrontend/src/metabase/utils/scripts-sandbox/distortions-blocked-apis.tsfrontend/src/metabase/utils/scripts-sandbox/distortions.tsfrontend/src/metabase/ui/colors/types/color-keys.tsfrontend/src/metabase/ui/colors/constants/accents.tsfrontend/src/metabase-lib/v1/types/utils/isa.ts
Every file downloaded → write <ref> to .claude/metabase-src/.ref.
<mb> is .claude/metabase-src. Add .claude/metabase-src/ to the project .gitignore when the line is missing. Now read the four scripts-sandbox files, color-keys.ts and accents.ts, each whole with the Read tool — never grep, head, sed or cat | …. The blocked lists sit mid-file; a partial read misses entries and the viz breaks at runtime. isa.ts on demand.
Then read references/project.md and references/operations.md.
Phases
phases/refine.md— youphases/build.md— a subagent: spawn it with theAgenttool and tell
it to read and follow that file. Never write src/index.tsx yourself: build needs a fresh context holding only the build statement and its references.
phases/verify.md— a subagent, spawned like build; read-only. It
reviews the code fresh, without this session's view of it
phases/iterate.md— youphases/debug.md— youphases/ship.md— you
When executing a phase yourself, follow that file only; skip reading files whose content is still in your context. Only when the Agent tool is unavailable, run build yourself.
References
project.md— files, build statement format, libraries, defaults, checksapi-contract.md— host behavior the types cannot expressknown-mistakes.md— bugs with symptoms, fixes, detectorssandbox-restrictions.md— what the sandbox blocks at runtimeoperations.md— dev server, connecting Metabase, reading a question,
renaming, user edits
fix-log-rules.md— format and rules of.claude/fix-log.md
State
.claude/build-statement.md— the build statement; written by refine,
kept current by iterate and debug. Missing while src/index.tsx is already a viz → reconstruct it from the code in the project.md format, confirm with the user, write it.
Start
Route:
src/index.tsxis still the scaffold's thumbs-up/down template (no
viz built yet) and the user wants a viz → Create
- Change, new setting, restyle, rename → iterate
- Misbehavior report → debug
- "ship it", "package it", "build the archive" → Ship
- Question about the viz, the API or the setup → answer from the
references and the code; no phase
Create
refine → build → iterate. Build returns open questions → ask the user, fold the answers into .claude/build-statement.md, re-run build.
Verify
Run verify. clean → back to the caller. Findings → show them to the user; never fix them unasked: the code may be the user's. Ask: fix them (debug, one finding per symptom), keep editing (iterate), or go on as is.
Ship
Run Checks (project.md). Failures → fix them first (debug). Then Verify, always: the user may have edited src/index.tsx in their editor. Fixed findings → start this Ship section over; clean → run phases/ship.md.
Phase exits
- iterate returns
misbehavior→ debug;verify→ Verify, then
iterate; done → Ship
- debug returns → iterate
