Agent Skills › mckinsey/vizro › writing-vizro-yaml

writing-vizro-yaml

GitHub

提供Vizro YAML仪表盘配置的编写与调试指南，涵盖组件语法、数据注册、自定义函数及AG Grid表格等核心模式与常见错误规避。

vizro-e2e-flow/skills/writing-vizro-yaml/SKILL.md mckinsey/vizro

Trigger Scenarios

构建Vizro应用排查YAML或运行时错误询问Vizro组件配置模式

Install

npx skills add mckinsey/vizro --skill writing-vizro-yaml -g -y

More Options

Non-standard path

npx skills add https://github.com/mckinsey/vizro/tree/main/vizro-e2e-flow/skills/writing-vizro-yaml -g -y

Use without installing

npx skills use mckinsey/vizro@writing-vizro-yaml

指定 Agent (Claude Code)

npx skills add mckinsey/vizro --skill writing-vizro-yaml -a claude-code -g -y

安装 repo 全部 skill

npx skills add mckinsey/vizro --all -g -y

预览 repo 内 skill

npx skills add mckinsey/vizro --list

SKILL.md

Frontmatter

{
    "name": "writing-vizro-yaml",
    "description": "Use this skill when writing or debugging Vizro YAML dashboard configurations — component syntax, data_manager registration, custom function wiring, filter\/parameter setup, or AG Grid tables. Activate when the user is building a Vizro app, encountering YAML or runtime errors, or asking about Vizro component patterns."
}

Vizro YAML & Component Reference

Critical Mistakes to Avoid

Each mistake below is expanded with code examples and fixes in yaml-reference.md.

@capture("graph") receives a DataFrame — use data_frame directly; never re-lookup via data_manager[data_frame] (causes blank charts).
data_manager is not subscriptable — pre-process on raw DataFrame, then register.
Custom _target_ needs module prefix — _target_: custom_charts.my_chart, not _target_: my_chart.
type: figure has no title field — KPI titles go in _target_: kpi_card args.
type: ag_grid requires _target_: dash_ag_grid.
Parameter targets — format: "component_id.argument_name", not "component_id.figure".
Quote YAML special chars in column names — column: "Version #" (unquoted # starts a comment).
Filter targets: — omit when you want to apply it to all components on the page whose data source includes defined filter column.
Grid must be rectangular — same component index must span same columns in every row.
Column type consistency — filter column must have same dtype across all targeted datasets.

Quick Patterns

# Standard chart (scatter — no aggregation needed, each row is one point)
- figure:
    _target_: scatter
    data_frame: sales_data
    x: units
    y: revenue
  type: graph
  title: Revenue vs Units

# KPI card (title inside figure args, NOT on component)
- figure:
    _target_: kpi_card
    data_frame: kpi_data
    value_column: Revenue
    title: Total Revenue
    value_format: "${value:,.0f}"
  type: figure

# AG Grid table
- figure:
    _target_: dash_ag_grid
    data_frame: sales_data
  type: ag_grid
  title: Sales Data

# Filter with targets
controls:
  - column: region
    targets: [chart_1, chart_2]
    type: filter

Key Imports

import vizro.models as vm
from vizro import Vizro
import vizro.plotly.express as px
from vizro.tables import dash_ag_grid
from vizro.figures import kpi_card, kpi_card_reference
from vizro.models.types import capture
from vizro.managers import data_manager
from vizro.themes import palettes, colors

Deep Dive

Load yaml-reference.md when you need expanded guidance. Key sections to search for:

Need	Search for
App structure	`## End-to-End Data Flow`
Data registration	`## Data Registration`
Custom charts	`## Custom Charts`
AG Grid (heatmap, inline bars)	`## AG Grid Tables`
Containers / Tabs	`## Containers` or `## Tabs`
Expanded mistake fixes	`## Critical Mistakes`