/chart-visualization

name: chart-visualization
description: Use this skill whenever the user wants a chart, graph, plot, dashboard visual, or asks to visualize structured numbers, trends, comparisons, proportions, distributions, correlations, rankings, or flows. This skill must also trigger when the user describes a reporting need in natural language without explicitly saying "chart". It converts the request into a validated chart specification, checks that the chosen chart type actually matches the data story, and only then generates the visual.
dependency:
  nodejs: ">=18.0.0"

Chart Visualization Skill

This skill provides a comprehensive workflow for transforming data into visual charts. It handles chart selection, parameter extraction, and image generation.

Workflow

To visualize data, follow these steps:

1. Normalize the Request Into a Chart Brief

Before choosing any chart, reduce the user's request into a brief with these fields:

{
  "goal": "What decision or comparison the chart should support",
  "audience": "executive | analytical | operational | academic | unknown",
  "data_story": "trend | comparison | composition | distribution | relationship | flow | geography | hierarchy",
  "source_data_state": "explicit data provided | partially described | no data",
  "must_show": ["metrics or categories that must appear"],
  "constraints": ["units, time grain, brand colors, report context, etc."]
}

If any of these are ambiguous enough to affect chart correctness, call `ask_clarification` before generating.

2. Ground the Data Before Chart Selection

• If the user uploaded CSV/XLSX or described tabular data, use `data-analysis` first to inspect schema and derive the exact rows/columns for charting.
• If the request contains only prose and no reliable numbers, do **not** invent plausible values just to make a chart. Ask for the missing data or clearly state that you can only produce a conceptual mock chart.
• Always produce a clean `data` array before generation. The final chart spec must be reproducible from that array alone.

3. Intelligent Chart Selection

Analyze the grounded data and the chart brief to determine the most appropriate chart type. Use the following guidelines (and consult `references/` for detailed specs):

• **Time Series**: Use `generate_line_chart` (trends) or `generate_area_chart` (accumulated trends). Use `generate_dual_axes_chart` for two different scales.
• **Comparisons**: Use `generate_bar_chart` (categorical) or `generate_column_chart`. Use `generate_histogram_chart` for frequency distributions.
• **Part-to-Whole**: Use `generate_pie_chart` or `generate_treemap_chart` (hierarchical).
• **Relationships & Flow**: Use `generate_scatter_chart` (correlation), `generate_sankey_chart` (flow), or `generate_venn_chart` (overlap).
• **Maps**: Use `generate_district_map` (regions), `generate_pin_map` (points), or `generate_path_map` (routes).
• **Hierarchies & Trees**: Use `generate_organization_chart` or `generate_mind_map`.
• **Specialized**:
• `generate_radar_chart`: Multi-dimensional comparison.
• `generate_funnel_chart`: Process stages.
• `generate_liquid_chart`: Percentage/Progress.
• `generate_word_cloud_chart`: Text frequency.
• `generate_boxplot_chart` or `generate_violin_chart`: Statistical distribution.
• `generate_network_graph`: Complex node-edge relationships.
• `generate_fishbone_diagram`: Cause-effect analysis.
• `generate_flow_diagram`: Process flow.
• `generate_spreadsheet`: Tabular data or pivot tables for structured data display and cross-tabulation.

4. Parameter Extraction

Once a chart type is selected, read the corresponding file in the `references/` directory (e.g., `references/generate_line_chart.md`) to identify the required and optional fields. Extract the data from the user's input and map it to the expected `args` format.

5. Build a Validated Chart Spec

Before running the generator, create a chart spec with this structure:

{
  "tool": "generate_chart_type_name",
  "args": {
    "data": [],
    "title": "",
    "theme": "default",
    "style": {},
    "axisXTitle": "",
    "axisYTitle": ""
  },
  "intent": {
    "data_story": "trend",
    "reason_for_choice": "Line chart fits sequential time-based change.",
    "source_summary": "Derived from monthly revenue totals grouped from Orders table.",
    "validation_notes": [
      "x field is temporal",
      "y field is numeric",
      "title matches metric and grain"
    ]
  }
}

Rules:

• `intent.data_story` must agree with the selected chart type.
• `intent.reason_for_choice` must explain why this chart is a better fit than obvious alternatives.
• `intent.source_summary` must say where the plotted data came from.
• `intent.validation_notes` must explicitly mention the key field checks you performed.

6. Validate Before Generation

Do not call `generate.js` until these checks are true:

• The selected chart type matches the requested story.
• Required fields for that chart type exist in every row.
• Numeric fields are actually numeric.
• Axis titles or labels are present for charts that use axes.
• Pie charts use 6 slices or fewer, or you aggregated a remainder bucket.
• Bar/column charts do not imply a misleading truncated scale.
• Titles describe the takeaway or exact metric, not a vague topic label.

If any check fails, revise the spec or ask for clarification instead of generating a wrong chart.

7. Chart Generation

Invoke the `scripts/generate.js` script with a JSON payload.

**Payload Format:**

{
  "tool": "generate_chart_type_name",
  "args": {
    "data": [...],
    "title": "...",
    "theme": "...",
    "style": { ... }
  }
}

**Execution Command:**

node ./scripts/generate.js '<payload_json>'

8. Result Return

The script will output the URL of the generated chart image. Return the following to the user:

• The image URL.
• The complete validated spec used for generation.
• A on