Chart Generation Skill
Produce accurate, source-grounded charts from researched or computed data. This skill
has two delivery modes; choose the one that matches the tools you were given, then
follow the matching section below.
Choose your mode
- Sandbox mode (an
execute tool is available): render a PNG with Python/matplotlib,
save it as a durable artifact, and embed it by reference. Follow Sandbox Mode (PNG
artifact) below.
- Inline mode (no
execute tool / no sandbox): emit the chart as an inline fenced
chart JSON spec that the web app renders, plus a portable Markdown table. Follow
Inline Mode (chart spec) below. Do NOT attempt to run code or produce a PNG.
The two modes are mutually exclusive and are selected only by tool availability: pick exactly
one and emit only that output path. When an execute tool (sandbox) is available you must use
Sandbox mode and must not emit an inline chart spec; only when no execute tool exists do you
use Inline mode. Never produce both a PNG artifact and an inline spec for the same figure.
Both modes share the same discipline: a chart confers authority, so it must be earned.
Data sufficiency (earn the chart, both modes)
A polished chart of wrong or sparse numbers misleads more than it informs.
- Source-anchored points only: every plotted value must trace to a specific source
(the as-reported figure and its URL). Never plot a fabricated, guessed, or inferred
number as if it were reported; mark genuine estimates as estimates.
- Suppress misleading charts: if a series is mostly missing (a majority of periods
undisclosed) or mixes metric definitions (e.g. "cash capex" vs "capex including finance
leases"), do NOT produce a trend chart. Present the table (which shows the gaps) and
state the limitation in one sentence instead.
- Show gaps honestly: never interpolate or connect across missing periods. Plot only
the periods a series actually reports, and render estimates distinctly so they do not
read as reported values.
- Prefer gap-tolerant forms: grouped bars show missing periods as absent bars; favor
them over a connected line when series are uneven, since a line drawn across gaps
implies a trend the data does not support.
- Use the ACTUAL numbers from the evidence (top ~10 rows); never invent, pad, or round
away data. If you show only the top rows of a larger set, say so.
Sandbox Mode (PNG artifact)
Render with Python/matplotlib, save the chart as a durable artifact, and embed it in the
report by reference (never by pasting image data).
Required Execution Standard
- Ground the data: build the plotted rows from researched facts or
/shared/...
inputs. Keep source URLs/notes alongside the values.
- Normalize units before plotting (currencies, magnitudes, periods).
- Render with code: call
execute to run Python/matplotlib. Do not hand-draw or
fabricate charts.
- Write to the artifact directory: save the PNG and its CSV under the exact
sandbox_artifact_dir given in your instructions (a per-job path such as
/sandbox/<job_id>/aiq-artifacts). Use that value verbatim - do NOT write to a bare
/sandbox/aiq-artifacts; the runtime only harvests files under sandbox_artifact_dir.
- Write a manifest to carry the chart's title, caption, and inline flag and to checkpoint
it mid-run (see below). It is preferred, not strictly required: a chart left in
sandbox_artifact_dir is still captured by the terminal directory scan without one.
- Reference, do not embed bytes: in the report, link the chart with
. The runtime resolves this to the durable
artifact; never paste base64 image data into the report.
Execution Flow
- Assemble the normalized rows (prefer explicit records embedded in the script). If the
inputs live in
/shared/..., read_file them first and embed the values; sandbox
code cannot open /shared/....
- Use
write_file to create the chart script under the exact sandbox_workdir from your
instructions, then execute it with the exact sandbox_artifact_dir as its first argument.
For example, when your instructions provide /sandbox/JOB/ and
/sandbox/JOB/aiq-artifacts, run
python3 /sandbox/JOB/make_chart.py /sandbox/JOB/aiq-artifacts. Never execute a literal
<sandbox_workdir> or <sandbox_artifact_dir> token.
sandbox_workdir is already per-job, so scripts there cannot collide with another job's
leftovers. Only ever execute a script you wrote this session. Each execute runs in a
fresh shell, so cd does NOT persist between calls; put absolute paths in every command
(or chain in one line as cd <dir> && <cmd>). The script must:
- import pandas and matplotlib (use the non-interactive
Agg backend),
- build the DataFrame, compute any derived metrics,
- set a single
ARTIFACT_DIR to your sandbox_artifact_dir and write the chart
(<name>.png), its data (<name>.csv), and manifest.json there (see the example).
- Inspect the
execute output; if it fails, fix the script and re-run (max 2 retries).
- In the report, embed the chart with
 and cite the
original data sources in the surrounding text.
Placement and description in the report
Each figure must appear where it is discussed, not buried in a file list:
- Embed once, in context: place the
 line inside
the section that analyzes the figure (e.g. Results, Findings, or a Visualization
subsection) - immediately after the paragraph that introduces it.
- Describe it: precede the embed with one sentence stating what the chart shows and the
takeaway (e.g. "The chart below compares 2025 resident population across the top five
states; California leads at roughly 3x Pennsylvania.").
- Reference by filename, never a raw path: the way to show a figure is the
 token. Do NOT instead write the sandbox path
(e.g. <sandbox_artifact_dir>/<name>.png) as prose and expect it to render - a bare path
is not an image. Never paste the plotting code or base64 image data into the report; do
not read_file a generated PNG just to verify it (that injects base64 bytes into context).
- One embed per artifact: list supporting files (CSVs, manifests) by name in an
appendix if useful, but the chart itself must be embedded inline as above.
Manifest
Write a manifest.json in your sandbox_artifact_dir so the runtime captures the chart
with its metadata. The manifest is the preferred path, not a hard requirement: a successful
execute checkpoints the manifest-declared artifacts immediately, and the manifest carries the
title, caption, and inline flag that let the chart render inline with a caption. If no
valid manifest is written, the terminal directory scan still captures any file left in
sandbox_artifact_dir as a successful fallback, but with default metadata (no title or caption,
and not auto-inlined), so the manifest is how you get an inline, captioned chart. Manifest
path values must be absolute and inside your sandbox_artifact_dir (the per-job path from
your instructions). Construct every manifest path from the runtime argument as shown below; do
not hand-copy an angle-bracket placeholder into JSON. Set inline: true only for a raster image
intended to appear in the report.
Example Script
import json
import sys
from pathlib import Path
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import pandas as pd
if len(sys.argv) != 2:
raise SystemExit("usage: make_chart.py ABSOLUTE_SANDBOX_ARTIFACT_DIR")
ARTIFACT_DIR = Path(sys.argv[1])
if not ARTIFACT_DIR.is_absolute():
raise SystemExit("artifact directory must be an absolute path")
ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
rows = [
{"company": "ExampleCo", "revenue_usd_billions": 12.4, "source": "https://example.com/filing"},
{"company": "SampleInc", "revenue_usd_billions": 9.1, "source": "https://example.com/10k"},
]
df = pd.DataFrame(rows).sort_values("revenue_usd_billions", ascending=False)
fig, ax = plt.subplots(figsize=(8, 5))
ax.bar(df["company"], df["revenue_usd_billions"])
ax.set_ylabel("Revenue (USD billions)")
ax.set_title("2024 Revenue Comparison")
fig.tight_layout()
png_path = ARTIFACT_DIR / "revenue_chart.png"
csv_path = ARTIFACT_DIR / "revenue_chart.csv"
fig.savefig(png_path, dpi=150)
df.to_csv(csv_path, index=False)
manifest = {
"version": 1,
"artifacts": [
{
"path": str(png_path),
"kind": "image",
"title": "2024 Revenue Comparison",
"caption": "Revenue normalized to USD billions.",
"inline": True,
"source_files": [r["source"] for r in rows],
}
],
}
with (ARTIFACT_DIR / "manifest.json").open("w", encoding="utf-8") as handle:
json.dump(manifest, handle)
print(f"wrote {png_path}")
Run the script with the two exact per-job paths given in your instructions. The second argument
must be the real absolute artifact directory, not an angle-bracket placeholder. Treat the
artifact-checkpoint response after execute as authoritative: reference the exact confirmed
filename in the report and do not invent or rename it later.
Sandbox notes and limitations
- Use the
Agg backend; the sandbox has no display.
- Keep charts legible: labeled axes, a title, and a legend when multiple series are shown.
- Do not call
read_file on the generated PNG merely to verify it; binary reads return base64
and waste model context. Inspect manifest.json with read_file(file_path=...) when needed,
then rely on the artifact-checkpoint response to confirm the accepted filename and inline state.
- If matplotlib or pandas is unavailable, report that the sandbox image needs them rather
than fabricating a chart.
- Reference charts only by
artifact://<filename>; the runtime assigns the durable id and
rewrites the reference for the UI, PDF export, and the packaged skill CLI.
Inline Mode (chart spec)
When there is no execute tool, present numbers that compare multiple things (a ranking or
top-N across entities, a distribution or counts across categories, a trend over an
ordered/time axis, or gains vs losses) as an inline chart, not just prose or a table. Lead
with a one-sentence verdict, then the chart.
- Emit the chart as a fenced code block tagged
chart holding a SINGLE line of valid JSON
(no comments, no trailing commas), right after the sentence that introduces it.
- Chart to reveal the pattern and state the verdict in prose. Inline
chart blocks render
only in the web app, so ALSO place a compact markdown table of the same values immediately
after each chart, keeping PDF, Markdown, API, and CLI exports readable.
- At most 3 charts per section, and put each chart before any table.
- A single value or a one-entity yes/no result is NOT a chart: emit a KPI-only block, a
fenced
chart block whose JSON has just title and kpis.
Chart types: bar (category magnitudes), hbar (rankings with long text labels),
line/area (a trend across an ordered axis), grouped-bar (2-4 series per category),
delta (gains vs losses around zero).
Spec fields: type; title (short) and optional subtitle; x = { "key": "<field in each row>", "label": "optional" }; optional y = { "label": "optional unit", "format": "number | compact | percent | currency" }; series = [ { "key": "<numeric field>", "label": "optional", "color": "green | blue | amber | red" } ]; data = rows as objects with raw numbers (fractions
0-1 for percent); optional kpis = [ { "label": "...", "value": "preformatted", "tone": "accent | warn | alarm" } ]. A delta chart encodes exactly one series.
Example (ranking):
{"type":"hbar","title":"Top suppliers by late shipments","x":{"key":"supplier"},"y":{"format":"number"},"series":[{"key":"late","color":"amber"}],"data":[{"supplier":"Acme","late":42},{"supplier":"Globex","late":31},{"supplier":"Initech","late":19}]}
Example (single value, KPI-only):
{"title":"On-time delivery rate","kpis":[{"label":"On-time","value":"92.4%","tone":"accent"}]}
For several related trends over time, emit one fenced chart-carousel block holding a SINGLE
line of JSON with at least two line-chart specs: { "title": "...", "charts": [ <line chart spec>, ... ] }.
Example (related trends, carousel):
{"title":"Quarterly delivery trends","charts":[{"type":"line","title":"On-time delivery rate","x":{"key":"quarter"},"y":{"format":"percent"},"series":[{"key":"rate","color":"green"}],"data":[{"quarter":"Q1","rate":0.88},{"quarter":"Q2","rate":0.90},{"quarter":"Q3","rate":0.93}]},{"type":"line","title":"Late shipments","x":{"key":"quarter"},"y":{"format":"number"},"series":[{"key":"late","color":"amber"}],"data":[{"quarter":"Q1","late":52},{"quarter":"Q2","late":41},{"quarter":"Q3","late":28}]}]}
1---2name: chart-generation3description: >4 Use this skill to turn researched or computed numeric data into source-grounded5 charts. It has two delivery modes and picks one from the tools available to you.6 When an `execute` tool (sandbox) is available, render a PNG chart plus its CSV with7 Python/matplotlib and embed it as a durable `artifact://` reference. When there is8 no sandbox, emit the chart as an inline fenced `chart` (or `chart-carousel`) JSON9 spec that the web UI renders deterministically, followed by a portable Markdown table.10 Triggers: "chart", "plot", "graph", "bar chart", "line chart", "visualize",11 "trend over time", "compare visually", "figure", "ranking", "top-N", "distribution".12 Outputs: either a PNG chart artifact (plus CSV and manifest) or an inline chart spec.13metadata:14 source: https://skillmd.com/skills/nvidia-ai-blueprints-aiq/chart-generation15---1617# Chart Generation Skill1819Produce accurate, source-grounded charts from researched or computed data. This skill20has two delivery modes; choose the one that matches the tools you were given, then21follow the matching section below.2223## Choose your mode24251. **Sandbox mode (an `execute` tool is available):** render a PNG with Python/matplotlib,26 save it as a durable artifact, and embed it by reference. Follow **Sandbox Mode (PNG27 artifact)** below.282. **Inline mode (no `execute` tool / no sandbox):** emit the chart as an inline fenced29 `chart` JSON spec that the web app renders, plus a portable Markdown table. Follow30 **Inline Mode (chart spec)** below. Do NOT attempt to run code or produce a PNG.3132The two modes are mutually exclusive and are selected only by tool availability: pick exactly33one and emit only that output path. When an `execute` tool (sandbox) is available you must use34Sandbox mode and must not emit an inline `chart` spec; only when no `execute` tool exists do you35use Inline mode. Never produce both a PNG artifact and an inline spec for the same figure.3637Both modes share the same discipline: a chart confers authority, so it must be earned.3839## Data sufficiency (earn the chart, both modes)4041A polished chart of wrong or sparse numbers misleads more than it informs.42431. **Source-anchored points only:** every plotted value must trace to a specific source44 (the as-reported figure and its URL). Never plot a fabricated, guessed, or inferred45 number as if it were reported; mark genuine estimates as estimates.462. **Suppress misleading charts:** if a series is mostly missing (a majority of periods47 undisclosed) or mixes metric definitions (e.g. "cash capex" vs "capex including finance48 leases"), do NOT produce a trend chart. Present the table (which shows the gaps) and49 state the limitation in one sentence instead.503. **Show gaps honestly:** never interpolate or connect across missing periods. Plot only51 the periods a series actually reports, and render estimates distinctly so they do not52 read as reported values.534. **Prefer gap-tolerant forms:** grouped bars show missing periods as absent bars; favor54 them over a connected line when series are uneven, since a line drawn across gaps55 implies a trend the data does not support.565. **Use the ACTUAL numbers** from the evidence (top ~10 rows); never invent, pad, or round57 away data. If you show only the top rows of a larger set, say so.5859---6061# Sandbox Mode (PNG artifact)6263Render with Python/matplotlib, save the chart as a durable artifact, and embed it in the64report by reference (never by pasting image data).6566## Required Execution Standard67681. **Ground the data:** build the plotted rows from researched facts or `/shared/...`69 inputs. Keep source URLs/notes alongside the values.702. **Normalize units** before plotting (currencies, magnitudes, periods).713. **Render with code:** call `execute` to run Python/matplotlib. Do not hand-draw or72 fabricate charts.734. **Write to the artifact directory:** save the PNG and its CSV under the exact74 `sandbox_artifact_dir` given in your instructions (a per-job path such as75 `/sandbox/<job_id>/aiq-artifacts`). Use that value verbatim - do NOT write to a bare76 `/sandbox/aiq-artifacts`; the runtime only harvests files under `sandbox_artifact_dir`.775. **Write a manifest** to carry the chart's title, caption, and inline flag and to checkpoint78 it mid-run (see below). It is preferred, not strictly required: a chart left in79 `sandbox_artifact_dir` is still captured by the terminal directory scan without one.806. **Reference, do not embed bytes:** in the report, link the chart with81 ``. The runtime resolves this to the durable82 artifact; never paste base64 image data into the report.8384## Execution Flow85861. Assemble the normalized rows (prefer explicit records embedded in the script). If the87 inputs live in `/shared/...`, `read_file` them first and embed the values; sandbox88 code cannot open `/shared/...`.892. Use `write_file` to create the chart script under the exact `sandbox_workdir` from your90 instructions, then `execute` it with the exact `sandbox_artifact_dir` as its first argument.91 For example, when your instructions provide `/sandbox/JOB/` and92 `/sandbox/JOB/aiq-artifacts`, run93 `python3 /sandbox/JOB/make_chart.py /sandbox/JOB/aiq-artifacts`. Never execute a literal94 `<sandbox_workdir>` or `<sandbox_artifact_dir>` token.95 `sandbox_workdir` is already per-job, so scripts there cannot collide with another job's96 leftovers. Only ever execute a script you wrote this session. Each `execute` runs in a97 fresh shell, so `cd` does NOT persist between calls; put absolute paths in every command98 (or chain in one line as `cd <dir> && <cmd>`). The script must:99 - import pandas and matplotlib (use the non-interactive `Agg` backend),100 - build the DataFrame, compute any derived metrics,101 - set a single `ARTIFACT_DIR` to your `sandbox_artifact_dir` and write the chart102 (`<name>.png`), its data (`<name>.csv`), and `manifest.json` there (see the example).1033. Inspect the `execute` output; if it fails, fix the script and re-run (max 2 retries).1044. In the report, embed the chart with `` and cite the105 original data sources in the surrounding text.106107## Placement and description in the report108109Each figure must appear where it is discussed, not buried in a file list:1101111. **Embed once, in context:** place the `` line inside112 the section that analyzes the figure (e.g. Results, Findings, or a Visualization113 subsection) - immediately after the paragraph that introduces it.1142. **Describe it:** precede the embed with one sentence stating what the chart shows and the115 takeaway (e.g. "The chart below compares 2025 resident population across the top five116 states; California leads at roughly 3x Pennsylvania.").1173. **Reference by filename, never a raw path:** the way to show a figure is the118 `` token. Do NOT instead write the sandbox path119 (e.g. `<sandbox_artifact_dir>/<name>.png`) as prose and expect it to render - a bare path120 is not an image. Never paste the plotting code or base64 image data into the report; do121 not `read_file` a generated PNG just to verify it (that injects base64 bytes into context).1224. **One embed per artifact:** list supporting files (CSVs, manifests) by name in an123 appendix if useful, but the chart itself must be embedded inline as above.124125## Manifest126127Write a `manifest.json` in your `sandbox_artifact_dir` so the runtime captures the chart128with its metadata. The manifest is the preferred path, not a hard requirement: a successful129`execute` checkpoints the manifest-declared artifacts immediately, and the manifest carries the130`title`, `caption`, and `inline` flag that let the chart render inline with a caption. If no131valid manifest is written, the terminal directory scan still captures any file left in132`sandbox_artifact_dir` as a successful fallback, but with default metadata (no title or caption,133and not auto-inlined), so the manifest is how you get an inline, captioned chart. Manifest134`path` values must be absolute and inside your `sandbox_artifact_dir` (the per-job path from135your instructions). Construct every manifest path from the runtime argument as shown below; do136not hand-copy an angle-bracket placeholder into JSON. Set `inline: true` only for a raster image137intended to appear in the report.138139## Example Script140141```python142import json143import sys144from pathlib import Path145146import matplotlib147matplotlib.use("Agg")148import matplotlib.pyplot as plt149import pandas as pd150151if len(sys.argv) != 2:152 raise SystemExit("usage: make_chart.py ABSOLUTE_SANDBOX_ARTIFACT_DIR")153ARTIFACT_DIR = Path(sys.argv[1])154if not ARTIFACT_DIR.is_absolute():155 raise SystemExit("artifact directory must be an absolute path")156ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)157158rows = [159 {"company": "ExampleCo", "revenue_usd_billions": 12.4, "source": "https://example.com/filing"},160 {"company": "SampleInc", "revenue_usd_billions": 9.1, "source": "https://example.com/10k"},161]162df = pd.DataFrame(rows).sort_values("revenue_usd_billions", ascending=False)163164fig, ax = plt.subplots(figsize=(8, 5))165ax.bar(df["company"], df["revenue_usd_billions"])166ax.set_ylabel("Revenue (USD billions)")167ax.set_title("2024 Revenue Comparison")168fig.tight_layout()169170png_path = ARTIFACT_DIR / "revenue_chart.png"171csv_path = ARTIFACT_DIR / "revenue_chart.csv"172fig.savefig(png_path, dpi=150)173df.to_csv(csv_path, index=False)174175manifest = {176 "version": 1,177 "artifacts": [178 {179 "path": str(png_path),180 "kind": "image",181 "title": "2024 Revenue Comparison",182 "caption": "Revenue normalized to USD billions.",183 "inline": True,184 "source_files": [r["source"] for r in rows],185 }186 ],187}188with (ARTIFACT_DIR / "manifest.json").open("w", encoding="utf-8") as handle:189 json.dump(manifest, handle)190191print(f"wrote {png_path}")192```193194Run the script with the two exact per-job paths given in your instructions. The second argument195must be the real absolute artifact directory, not an angle-bracket placeholder. Treat the196artifact-checkpoint response after `execute` as authoritative: reference the exact confirmed197filename in the report and do not invent or rename it later.198199## Sandbox notes and limitations200201- Use the `Agg` backend; the sandbox has no display.202- Keep charts legible: labeled axes, a title, and a legend when multiple series are shown.203- Do not call `read_file` on the generated PNG merely to verify it; binary reads return base64204 and waste model context. Inspect `manifest.json` with `read_file(file_path=...)` when needed,205 then rely on the artifact-checkpoint response to confirm the accepted filename and inline state.206- If matplotlib or pandas is unavailable, report that the sandbox image needs them rather207 than fabricating a chart.208- Reference charts only by `artifact://<filename>`; the runtime assigns the durable id and209 rewrites the reference for the UI, PDF export, and the packaged skill CLI.210211---212213# Inline Mode (chart spec)214215When there is no `execute` tool, present numbers that compare multiple things (a ranking or216top-N across entities, a distribution or counts across categories, a trend over an217ordered/time axis, or gains vs losses) as an inline chart, not just prose or a table. Lead218with a one-sentence verdict, then the chart.219220- Emit the chart as a fenced code block tagged `chart` holding a SINGLE line of valid JSON221 (no comments, no trailing commas), right after the sentence that introduces it.222- Chart to reveal the pattern and state the verdict in prose. Inline `chart` blocks render223 only in the web app, so ALSO place a compact markdown table of the same values immediately224 after each chart, keeping PDF, Markdown, API, and CLI exports readable.225- At most 3 charts per section, and put each chart before any table.226- A single value or a one-entity yes/no result is NOT a chart: emit a KPI-only block, a227 fenced `chart` block whose JSON has just `title` and `kpis`.228229Chart types: `bar` (category magnitudes), `hbar` (rankings with long text labels),230`line`/`area` (a trend across an ordered axis), `grouped-bar` (2-4 series per category),231`delta` (gains vs losses around zero).232233Spec fields: `type`; `title` (short) and optional `subtitle`; `x` = `{ "key": "<field in each234row>", "label": "optional" }`; optional `y` = `{ "label": "optional unit", "format": "number |235compact | percent | currency" }`; `series` = `[ { "key": "<numeric field>", "label": "optional",236"color": "green | blue | amber | red" } ]`; `data` = rows as objects with raw numbers (fractions2370-1 for `percent`); optional `kpis` = `[ { "label": "...", "value": "preformatted", "tone": "accent238| warn | alarm" } ]`. A `delta` chart encodes exactly one series.239240Example (ranking):241242```chart243{"type":"hbar","title":"Top suppliers by late shipments","x":{"key":"supplier"},"y":{"format":"number"},"series":[{"key":"late","color":"amber"}],"data":[{"supplier":"Acme","late":42},{"supplier":"Globex","late":31},{"supplier":"Initech","late":19}]}244```245246Example (single value, KPI-only):247248```chart249{"title":"On-time delivery rate","kpis":[{"label":"On-time","value":"92.4%","tone":"accent"}]}250```251252For several related trends over time, emit one fenced `chart-carousel` block holding a SINGLE253line of JSON with at least two line-chart specs: `{ "title": "...", "charts": [ <line chart254spec>, ... ] }`.255256Example (related trends, carousel):257258```chart-carousel259{"title":"Quarterly delivery trends","charts":[{"type":"line","title":"On-time delivery rate","x":{"key":"quarter"},"y":{"format":"percent"},"series":[{"key":"rate","color":"green"}],"data":[{"quarter":"Q1","rate":0.88},{"quarter":"Q2","rate":0.90},{"quarter":"Q3","rate":0.93}]},{"type":"line","title":"Late shipments","x":{"key":"quarter"},"y":{"format":"number"},"series":[{"key":"late","color":"amber"}],"data":[{"quarter":"Q1","late":52},{"quarter":"Q2","late":41},{"quarter":"Q3","late":28}]}]}260```