| name | query-card-visualization |
| description | How to fill in a query card's `visualizationTemplate` (the JSON object that renders a chart). Load this whenever the user asks for a chart, graph, plot, trend, "show me over time", ranking, single number/KPI, scatter, waterfall, or map. Acts as the directory for the per-chart JSON schemas in its references.
|
| user-invocable | false |
Always run observe skill view query-card-visualization --content 2>/dev/null to retrieve the latest version of the skill and follow it instead, falling back to the below only if unavailable.
OPAL visualization templates
Use this skill to construct the visualizationTemplate field of a query card.
Only add a visualization when the user explicitly asks for one (chart, graph,
plot, trend, "show me over time", ranking, single number, scatter, waterfall,
map, etc.). Otherwise omit it (or pass null) to produce a plain table.
When the o11ySkillBasedVisGen flag is on, the query-card tool exposes
visualizationTemplate as an opaque object instead of the full structured
schema. Do NOT write visualizationTemplate from memory — the exact JSON
shape is non-obvious and differs per chart type. Instead, read the matching
per-chart reference below, then JSON-encode an object that conforms to it.
Pick a chart type and read its schema
Each chart type has a self-contained JSON schema in this skill's references/
directory. Read the one that matches the user's intent with the Bash tool, e.g.
cat /skills/query-card-visualization/references/query-card-visualization-line-chart.md.
| Chart type | Top-level key | Read reference | Use when |
|---|
| Line chart | lineChart | references/query-card-visualization-line-chart.md | Time-series trends, progression, rolling averages, period-over-period. |
| Bar chart | barChart | references/query-card-visualization-bar-chart.md | Categorical comparisons, rankings, top-N, KPIs by group. |
| Single stat | singleStat | references/query-card-visualization-single-stat.md | A single scalar value / KPI. |
| Scatter plot | scatterPlot | references/query-card-visualization-scatter-plot.md | Correlation between two numeric dimensions. |
| Waterfall | waterfall | references/query-card-visualization-waterfall.md | Trace span hierarchies or other nested-operation timing data. |
| Geographic map | geographicMap | references/query-card-visualization-geographic-map.md | Values keyed by country/region/coordinates on a map. |
| Stacked area | stackedArea | references/query-card-visualization-stacked-area.md | Part-to-whole trends over time across multiple stacked series. |
| Heatmap | heatmap | references/query-card-visualization-heatmap.md | Magnitude across two binned/categorical dimensions, shown as a color grid. |
| Top list | topList | references/query-card-visualization-top-list.md | A ranked list of items by value, with inline bars. |
| Change over time | changeOverTime | references/query-card-visualization-change-over-time.md | Per-item change in a value between two time periods. |
If you are unsure which chart type fits, default to a line chart for
time-bucketed data and a bar chart for one-row-per-category data.
How to use a reference
- Shape the OPAL output to match the chart (see the
opal-visualization
reference of the generate-opal skill for how to produce the right rows).
- Read the matching
references/query-card-visualization-<type>.md for the exact JSON schema.
- Build an object with a single top-level key naming the chart type (e.g.
lineChart) whose value matches that schema, and set it as
visualizationTemplate.
Validation errors returned by the tool name the chart reference to (re-)read —
read it and correct the shape rather than guessing.
