Cómo usar
- Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
- Consulta las herramientas, credenciales y entornos necesarios en el documento original.
- Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/metabase/agent-skills --skill metabase-custom-vizAntes de empezar
- La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
- Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
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
