| name | tell-data-story |
| description | Picks 2-3 narrative design patterns suited to the user's data and goal, then generates a standalone HTML page demonstrating them on that data. Use when the user shares a dataset (CSV, PDF, table, JSON, text), screenshot of numbers, or describes data and asks how to present it, communicate it, make it memorable, persuasive, or emotionally resonant. Pass a pattern name or number as the argument to apply a specific pattern directly instead of auto-picking. |
| argument-hint | [pattern-name-or-number] |
| allowed-tools | Read Write Bash(python3 *) Bash(head *) Bash(wc *) Bash(file *) |
Tell Data Story
Turn raw data plus a goal into a one-page interactive story built from 2-3 narrative design patterns. The output is a single self-contained HTML file the user can open in a browser, send to a colleague, or paste into a CMS.
Inputs
The user provides:
- Data — file path to CSV/PDF/JSON/Markdown table, a pasted table, or a verbal description of numbers.
- Goal and audience — what they want the reader to take away, and who that reader is. If missing, ask in Step 2.
Optional $ARGUMENTS: a pattern name (compare, concretise) or pattern number (13, 08). Empty argument means auto-pick mode.
Workflow
Copy this checklist into your response and tick boxes as you go:
- [ ] Step 1: Read the data and note its shape
- [ ] Step 2: Clarify takeaway, audience, format (skip questions already answered)
- [ ] Step 3: Confirm the goal back to the user before going further
- [ ] Step 4: Propose patterns (direct from $ARGUMENTS, or auto-pick 2-3) and get sign-off
- [ ] Step 5: Generate narrative-output.html from template.html
- [ ] Step 6: Report picks, rationale, and output path
Step 1 — Read the data
- CSV, JSON, Markdown, plain text: read directly with the Read tool. Note row count, column names, key dimension (time, category, geography), magnitude range, and any obvious outliers.
- PDF: try
python3 -c "import pdfplumber, sys; print(pdfplumber.open(sys.argv[1]).pages[0].extract_text())" <path>. If pdfplumber is not installed or extraction fails, ask the user to paste the key rows.
- Pasted table or verbal description: work from what they gave you; ask for a sample if it is too abstract to choose patterns from.
State the shape back in one sentence so the user can correct you before pattern selection.
Step 2 — Clarify intent
If the user has not already said, ask up to three questions in a single message. Do not ask more than three. Skip any that are already answered:
- Takeaway — In one sentence, what should the reader walk away thinking?
- Audience — General public, technical/expert, internal decision-makers, or something else?
- Format — Where does this live? Slide, blog post, social share, internal report, exhibit panel?
Step 3 — Confirm the goal
Before picking patterns, mirror the brief back to the user in 2 to 4 short lines, then stop and wait for confirmation. Do not move on until they reply.
Use this shape:
Data: one line restating the shape (rows, dimension, range).
Takeaway: the one-sentence message you'll build the story around.
Audience and format: who it's for, where it lives.
Sound right, or want to adjust before I pick patterns?
If the user corrects anything, update your understanding and re-confirm only if the change is material (different takeaway, different audience). Small wording tweaks do not need a second round.
Step 4 — Propose patterns and get sign-off
If $ARGUMENTS is non-empty (direct mode):
- Match against the list in Available patterns below. Accept the id (
13-compare), the short name (compare), or the number (13).
- If no match, stop and list the 18 valid names so the user can retry.
- Apply that single pattern. Skip auto-pick heuristics. Still walk the user through it (one or two sentences on why it fits their data) and ask for the green light before generating.
Otherwise (auto-pick mode), choose 2 to 3 patterns. Use these heuristics, then read patterns.md for the candidates' full why and how before finalising:
- Persuade / argue a point → Argumentation:
01-repetition, 02-silent-data, 13-compare
- Make scale or magnitude land → Emotion:
08-concretise, 05-humans-behind-the-dots
- Pull the reader in, let them play → Engagement:
03-exploration, 04-users-find-themselves, 16-make-a-guess
- Sequence complex material → Flow:
06-gradual-reveal, 07-speed-up-slow-down
- Shift perspective, reframe → Framing:
09-familiarisation, 15-defamiliarisation, 14-convention-breaking, 17-physical-metaphor
- Move the reader to act → Engagement:
18-call-to-action
- Empathy / personal stake → Emotion + Framing:
11-breaking-the-4th-wall, 12-addressing-the-audience
Selection rules:
- Prefer patterns whose
categories (in patterns.md) align with the stated goal.
- Diversify: when two patterns serve the same purpose, prefer the pair that covers different categories so the story has both head and heart.
- Match data shape: small-multiples-able data favours
01-repetition; two-entity comparisons favour 13-compare; sequential or time-series data favours 06-gradual-reveal; large counts of people or events favour 05-humans-behind-the-dots or 08-concretise.
For each pick, write one sentence of rationale that names the user's specific data and goal, not a generic restatement of the pattern. Bad: "Use Compare to show the difference." Good: "Use Compare so the 3 % marketing spend sits next to the 47 % salary line at the same scale, and the gap becomes the chart."
Then present the proposal to the user as a short bulleted list (pattern name, one-sentence rationale each) and ask:
Happy with these, or want to swap one out? I'll generate the page once you say go.
Wait for a green light before Step 5. If they swap a pattern, update the list and re-confirm. If they say go, proceed.
Step 5 — Generate output
- Read template.html.
- Fill placeholders:
{{TITLE}} — short headline derived from the user's takeaway.{{TAKEAWAY}} — the takeaway sentence verbatim.{{PATTERN_BLOCKS}} — one <section class="pattern-demo"> per selected pattern, in the order the story should be read. Each block contains:
- Category pill (use the primary category from patterns.md)
- Pattern title and number
- Why this pattern — one or two sentences pulled and tightened from the pattern's
why
- Applied here — one or two sentences naming the user's data and the specific move
- A working demo built from the user's actual data: inline SVG, HTML, and JS. No frameworks, no external CSS, no build step. Match the visual language defined in design-system.html: Fraunces headings, monospace labels for axes/captions, the paper/ink/category tokens already inlined in
template.html, yellow .hl only as a background behind text, soft .demo-frame panels for chart areas.
- Write the filled-in file to
narrative-output.html in the current working directory. Overwrite if it exists.
Critical: the demo must use the user's numbers, not the example data from the pattern's catalog entry. The catalog's example field is a reference to existing work, not data to copy.
Step 6 — Report
In your final response, give the user:
- A bulleted list of the 1-3 patterns picked, each with the one-sentence rationale from Step 3.
- The output path (
./narrative-output.html).
- One line telling them to open it in a browser.
Keep the report short. The HTML is the deliverable.
Available patterns
Use these ids (or the bare number / short name) for $ARGUMENTS matching. Full why and how for each in patterns.md.
01-repetition — Repeat one motif across small multiples until the pattern feels inescapable.02-silent-data — Ghost a data point, then reveal it for shock.03-exploration — Let the reader filter and drill in.04-users-find-themselves — Reader locates their own dot in the population.05-humans-behind-the-dots — Hover a dot, meet the person.06-gradual-reveal — Layer complexity one beat at a time.07-speed-up-slow-down — Control playback tempo to spotlight dense moments.08-concretise — Translate abstract magnitude into a familiar physical equivalent.09-familiarisation — Re-label the chart around the reader's own reference point.10-rhetorical-question — Open with a question, deliver the answer in the chart.11-breaking-the-4th-wall — A subject inside the chart turns and addresses the reader.12-addressing-the-audience — Rewrite copy in the second person.13-compare — Two things at the same scale; the disparity is the chart.14-convention-breaking — Set up a chart convention, then break it.15-defamiliarisation — Re-draw something familiar strangely.16-make-a-guess — Reader draws their prediction; reveal the truth over it.17-physical-metaphor — Direction carries feeling: up is good, down is bad.18-call-to-action — End with one specific, low-friction next step.
References
- Full pattern catalog with
why, how, and a real-world example for each: patterns.md
- Output scaffold with the design tokens inlined: template.html
- Visual language reference (colors, type, components, motion). Edit this file to retheme the skill; keep token names stable so
template.html stays in sync: design-system.html
