Metabase Doctor
StarrHuang/metabase-doctor
Revisar, debugar, otimizar e filtrar dashboards Metabase end-to-end
Ver no GitHubSkill para Claude Code que automatiza revisão, debug, otimização e embelezamento de dashboards Metabase. Cobre SQL semântico, testes de fumaça, beautificação de tabelas e engenharia de filtros em 3 camadas, com 23+ armadilhas documentadas de BI reais.
Instalação
npx convez-ai StarrHuang/metabase-doctor1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Revisar dashboards para bugs semânticos em SQL (double-counting, joins errados, confusão snapshot vs histórico)
- Reescrever queries SQL e publicar via API Metabase preservando formatação condicional
- Comprimir tabelas de 20+ colunas com formatação e emojis de status
- Adicionar filtros multi-camadas (SQL template-tag + parâmetros + parameter_mappings)
Veredito

Skill robusto e battle-tested para times que lidam com BI em escala. Documenta armadilhas reais (not just patterns), oferece SOPs claros e é reutilizável em qualquer agente. Excelente para data engineers e analysts que querem delegar reviews de dashboard a Claude.
README
A tradução para o português deste README ainda está na fila.
metabase-doctor
A Claude Code Skill for reviewing, debugging, optimizing, beautifying, and filtering Metabase dashboards — end-to-end.
When your teammates start saying:
- "this card's number is wrong"
- "this dashboard has too many columns, can't see what matters"
- "add a filter so we can switch by store / region / SKU"
- "review this dashboard and tell me what's broken"
...point your AI at this skill.
What it does
Covers 4 high-frequency Metabase tasks:
- Review — Find semantic bugs in SQL (double-counting, mixed aggregation rows, snapshot vs history confusion, wrong joins, etc.)
- Fix — Rewrite SQL, smoke-test, push via
PUT /api/card/:idwhile preservingvisualization_settings - Beautify — Compress 20-column tables down to 11 with emoji status, conditional formatting, and export-friendly hidden columns
- Add filters — Three-layer filter engineering (SQL template-tag + Dashboard parameter + dashcard
parameter_mappings) with dropdowns/search/multi-key resolvers
Where it came from
Real-world iteration on a multi-tab supply-chain dashboard (16+ cards, 8 tabs, hundreds of filters). The skill captures 23+ specific traps we hit:
- "predefined aggregation rows mixed with detail rows → triple-counted GMV"
- "snapshot tables with no history → trend queries return same value every day"
- "JOIN missing
marketplace_id→ US sales mis-attributed to CA parent ASIN" - "Metabase question direct link doesn't apply
defaultunlessrequired: true" - "PUT
/api/card/:idwithoutvisualization_settingswipes all conditional formatting"
These are documented in references/known-pitfalls.md as trap patterns (not company-specific tables), so they generalize.
Structure
metabase-doctor/
├── SKILL.md # Main entry (8-step workflow + triggers)
└── references/
├── sop.md # Pull SQL / PUT card / smoke test command templates
├── known-pitfalls.md # 23+ trap patterns (data modeling / SQL / Metabase API)
├── visualization-cookbook.md # visualization_settings basics (formatting/widths/chart types)
├── beautification-recipes.md # 16 table beautification recipes
└── filters-cookbook.md # 3-layer filter architecture + complete script
How to use
In Claude Code
Drop the folder into ~/.claude/skills/metabase-doctor/:
git clone https://github.com/StarrHuang/metabase-doctor.git ~/.claude/skills/metabase-doctor
Next time you say "review dashboard 197" or "add a store filter" Claude will follow the 8-step workflow automatically.
In other AI tools
SKILL.md is plain Markdown — paste it into any agent's system prompt / context.
As reference docs
You don't need an AI to benefit. known-pitfalls.md and beautification-recipes.md are high-quality engineering guides for any data engineer using Metabase.
Core principles
- SQL literal ≠ field semantics — All assumptions must be verified against the database (read comments, check distributions, validate math relations, verify cardinality)
- When the user gives a counter-example, go to the database — don't explain why your previous judgment was right
- PUT card must preserve
visualization_settings— Otherwise it wipes all conditional formatting, column widths, formats - Trigger beautification when columns ≥ 12 — Hide (don't delete) raw columns so spreadsheet exports stay complete
- All three filter layers must be present — SQL template-tag + Dashboard parameter + dashcard
parameter_mappings. Miss any one → filter doesn't fire - Sediment every iteration to
note.md— So the next agent doesn't trip on the same trap
Adapting to your warehouse
Table names in the examples (amazon_product_performance_statement, amazon_fba_stock, etc.) come from a generic Amazon ERP modeling. Schema names are placeholders (bi / oms / wms).
If your warehouse names tables differently, treat known-pitfalls.md as a library of trap patterns rather than a list of specific tables. The valuable part is the shape of the trap (aggregation row mixed with detail, field containing all time horizons, etc.) — not the specific table names.
Contributing new pitfalls
Found a new field semantic trap, new Metabase API quirk, or new "looks-right-at-first-glance" SQL pattern? PRs to known-pitfalls.md or any of the *-cookbook.md files are welcome.
License
MIT