Generate beautiful static reports for ad hoc analysis. A Claude skill that turns compact JSON specs into professional HTML visualizations.

The highest-value analysis in any company is point-in-time, highly contextual, and not reused once the decision is made.

Traditional BI tools optimize for reusability instead of usefulness. Useful analysis, the kind that drives critical decisions, needs something more:

• Fast iteration: Query data → visualize → refine → share
• AI-native workflow: Works seamlessly with Claude for data exploration
• Static output: Beautiful HTML/PDF reports, no infrastructure required
• Minimal tokens: Compact specs instead of verbose chart code

Instead of writing 50-100 lines of chart boilerplate, write a compact JSON spec that gets expanded into a full HTML artifact with ECharts.

Connect Claude to your data using an MCP server:

• MotherDuck MCP - Cloud data warehouse with DuckDB compatibility
• Local DuckDB MCP - Query local .duckdb files, Parquet, CSV, or S3 data

If you do not have a database available, you can also load CSV files directly, although the amount of data you can fit in context can be quite limiting.

Claude Web or Desktop: Download mviz.skill and add it to your project knowledge.

Claude Code: Run npx add-skill matsonj/mviz or clone this repo and work from the directory.

The best analysis follows four steps:

1. Build context — Get the data right. Query, filter, and explore until you understand what you're looking at.
2. Develop narrative — What's the story? What question are you answering? What pattern matters?
3. First pass on viz — Create an initial visualization. Don't overthink it.
4. Refine based on what doesn't work — Iterate. Change chart types, adjust formatting, add context.

Start by exploring your data with natural questions. Claude writes SQL queries behind the scenes and brings the results into context:

"Show me revenue by region for Q4"

"What are our top 10 customers by lifetime value?"

"Are there any anomalies in last month's sales data?"

Once you've built up context and are ready to visualize, tell Claude to "use mviz to report on this analysis". Claude generates a polished HTML report from the data you've explored.

Refine your analysis by asking follow-up questions:

"Change that bar chart to a line chart"

"Drill into the APAC region—what's driving that spike?"

"Add a table showing the top 5 products by growth rate"

mviz uses a 16-column grid.

"Make the bar chart wider"

"Show two charts side by side at size=[8,6] each"

"Make the KPIs smaller: size=[3,2] so 5 fit in a row"

By default, it will use size=auto to let mviz calculate appropriate dimensions based on your data.

Each iteration builds on your existing context. When you're done, save the HTML or print to PDF.

Reference external files instead of embedding large JSON specs:

```bar file=data/monthly-sales.json
```

CSV files work great for data exploration with DuckDB:

# Export query results
duckdb -csv -c "SELECT month, revenue FROM sales GROUP BY 1" > data/monthly.csv

```bar file=data/monthly.csv
{"title": "Monthly Revenue", "x": "month", "y": "revenue"}
```

CSV provides data, inline JSON provides chart options. Auto-detects x/y from first two columns if no options given.

---
theme: light
title: My Report
---

# Page Title

## Section Name

```big_value size=[4,2]
{"value": 125000, "label": "Revenue", "format": "usd0m"}
```
```delta size=[4,2]
{"value": 0.15, "label": "vs Last Month", "format": "pct0"}
```

```bar size=[8,6] file=data/sales.json
```
```line size=[8,6] file=data/trend.json
```

• # Title creates a new section (first one also sets page title)
• ## Section creates a subsection with divider
• --- creates a section break (untitled)
• size=[cols,rows] controls 16-column grid layout
• size=auto auto-calculates size based on data
• file=path references external JSON
• Multiple blocks on same line = same row
• Empty lines = new rows

Tables support inline sparkline columns for trend visualization:

{
  "type": "table",
  "columns": [
    {"id": "product", "title": "Product"},
    {"id": "sales", "title": "Sales", "fmt": "usd"},
    {"id": "trend", "title": "Trend", "type": "sparkline", "sparkType": "line"},
    {"id": "progress", "title": "Goal", "type": "sparkline", "sparkType": "pct_bar", "width": 100}
  ],
  "data": [
    {"product": "Widget", "sales": 125000, "trend": [85, 92, 88, 95, 102, 110, 125], "progress": 0.85}
  ]
}

Sparkline types: line, bar, area, pct_bar (progress bar), dumbbell (before/after)

Smart formatting automatically picks the right suffix (k, m, b) based on magnitude and shows 4 significant digits. Negative values display in parentheses: (1.000m).

Chart axes automatically detect the appropriate format based on field names:

Override with an explicit format field in the chart spec.

Reports include a theme toggle button (top right) that switches between light and dark modes. All charts dynamically update when the theme changes.

Set the default theme in frontmatter:

---
theme: dark
title: My Report
---

Charts are optimized for printing to PDF:

• High-Quality Rendering: Uses SVG renderer for crisp vector graphics at any zoom level
• No Page Breaks in Charts: CSS prevents charts and tables from being split across pages
• All Labels Visible: Category labels are always shown (with 45° rotation to fit)

When printing reports to PDF, all content stays intact without visual elements being cut off.

Clean, data-focused styling:

• Font: Helvetica Neue (system sans-serif)
• Signature: Orange accent line at top of reports
• Background: Paper (#f8f8f8) for light, dark (#231f20) for dark

chart-skill/
├── ts-src/                  # TypeScript implementation
│   ├── cli.ts              # CLI entry point
│   ├── index.ts            # Library exports
│   ├── types.ts            # TypeScript type definitions
│   ├── core/               # Shared utilities
│   │   ├── themes.ts       # Colors, palettes, theme config
│   │   ├── formatting.ts   # Number formatting
│   │   └── css.ts          # CSS generation
│   ├── charts/             # 17 chart type modules
│   │   ├── bar.ts, line.ts, area.ts, pie.ts, scatter.ts, bubble.ts
│   │   ├── boxplot.ts, histogram.ts, waterfall.ts, xmr.ts
│   │   ├── sankey.ts, funnel.ts, heatmap.ts, calendar.ts
│   │   └── sparkline.ts, combo.ts, dumbbell.ts
│   ├── components/         # 8 UI component modules
│   │   ├── big_value.ts, delta.ts, alert.ts, note.ts
│   │   ├── text.ts, textarea.ts, empty_space.ts, table.ts
│   └── layout/             # Report parser
│       ├── parser.ts       # Markdown layout parsing
│       └── templates.ts    # HTML templates
├── build_skill.py           # Builds .skill package for distribution
├── tests/
│   ├── harness/            # Visual test harness markdown
│   ├── dashboard-inline/    # Test dashboard with inline JSON
│   └── dashboard-with-refs/ # Test dashboard with file references
├── docs/
│   ├── MD-CHARTS-PROJECT.md # Original project specification
│   └── agents.md            # Skill authoring reference
└── skill-bundle/            # Source files for the skill
    ├── SKILL.md             # Skill instructions (with YAML frontmatter)
    ├── reference/
    │   └── chart-types.md   # Complete API reference
    └── examples/            # JSON and markdown examples

The chart generator outputs helpful warnings to stderr when issues are detected:

Warnings include context like content previews, suggestions for similar types, and section/row information to help locate issues.

cd ts-src
npm test                    # TypeScript tests (vitest)
npm run build               # Build TypeScript
npm run typecheck           # Type checking only

The skill bundle (skill-bundle-compact/) is optimized for Claude for Web with minimal token usage (~750 tokens). Supports essential types:

• Charts: bar, line, scatter
• Components: table (with sparklines), note, textarea, empty_space

For additional chart types (pie, area, heatmap, sankey, etc.), Claude can reference the TypeScript source code in this repository. See Best_practices.md for layout guidance and visualization principles.

The skill is automatically available when working in this project directory.

1. Create a new Claude project
2. Upload the .skill file or all files from skill-bundle/ to the project knowledge base
3. Claude will have access to the skill, examples, and generator

• Node.js 20+

Data visualization best practices:

• Maximize data-ink ratio (minimal non-data elements)
• Tight, dense layouts for reports
• No gratuitous animations or visual clutter
• Clean, minimal axes (no domain lines, subtle grid)
• Linear interpolation for accurate data representation
• Focus on data clarity over decoration

MIT