convez.ai
SkillDados & AnalyticsAvançado
StarrHuang

Metabase Doctor

StarrHuang/metabase-doctor

Revisar, debugar, otimizar e filtrar dashboards Metabase end-to-end

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-doctor

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

  1. Review — Find semantic bugs in SQL (double-counting, mixed aggregation rows, snapshot vs history confusion, wrong joins, etc.)
  2. Fix — Rewrite SQL, smoke-test, push via PUT /api/card/:id while preserving visualization_settings
  3. Beautify — Compress 20-column tables down to 11 with emoji status, conditional formatting, and export-friendly hidden columns
  4. 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 default unless required: true"
  • "PUT /api/card/:id without visualization_settings wipes 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

  1. SQL literal ≠ field semantics — All assumptions must be verified against the database (read comments, check distributions, validate math relations, verify cardinality)
  2. When the user gives a counter-example, go to the database — don't explain why your previous judgment was right
  3. PUT card must preserve visualization_settings — Otherwise it wipes all conditional formatting, column widths, formats
  4. Trigger beautification when columns ≥ 12 — Hide (don't delete) raw columns so spreadsheet exports stay complete
  5. All three filter layers must be present — SQL template-tag + Dashboard parameter + dashcard parameter_mappings. Miss any one → filter doesn't fire
  6. 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

Ver o original no GitHub

Bom para

Relacionados