Agent skill
data-story
Write data findings as a compelling narrative story, Malcolm Gladwell prose, NYT graphics-team visuals, engaging & memorable even for a non-technical audience.
Install this agent skill to your Project
npx add-skill https://github.com/sanand0/scripts/tree/main/agents/data-story
SKILL.md
Narrative Data Story
Write like Malcolm Gladwell. Visualize like the NYT graphics team. Think like a detective who must defend every finding under scrutiny.
The goal: a story so well-constructed that readers feel the insight before they understand it — and remember it long after.
1 — The Hook
Never open with a chart or a statistic. Open with a person, a tension, or a mystery — something that makes someone who wasn't planning to read this stop and keep reading.
- Human angle: A specific person, place, or moment that embodies the pattern you're about to reveal.
- Tension: Something that seems wrong or contradictory — that the data will resolve.
- Mystery: A question the reader didn't know they wanted answered.
A strong move is self-reference: "Imagine you're the customer who just churned" activates simulation in a way third-person never can. Cast abstract forces as agents with goals. Archetypes beat famililar/famous names (less baggage, more projection) for learning, but familiar names are memorable.
❌ "This report analyzes regional sales performance across Q3." ✅ "In September, one sales rep in Omaha quietly closed more deals than the entire West Coast team. Nobody had noticed."
2 — Story Arc
Build through discovery, not declaration. Resist the urge to front-load conclusions — the journey earns the finding. Keep your main beats to ≤4 — the brain chunks before it comprehends, and working memory holds roughly four things.
- Setup — Establish the world as everyone assumes it to be.
- Complication — Introduce the anomaly, the crack in conventional wisdom.
- Revelation — The central insight, landed with precision and room to breathe.
- Implications — What this means and what should change.
⚠️ The tale trap: a well-structured story feels like understanding even when the causal model is wrong. Sequential narrative implies causation automatically. Name the mechanism explicitly — don't let order do the work evidence should do.
3 — Integrated Visualizations
Charts and maps should be revelatory, not decorative — placed in the moment of revelation, not at the end.
- Every chart needs a headline that states the finding: "The Northeast isn't just ahead — it's in a different league" beats "Regional Performance Comparison."
- Design for the "oh" moment: annotation and highlighting matter more than completeness.
- Ask of every visual: does this make the pattern undeniable, or does it require explanation? If the latter, redesign or cut.
- Prefer focused over comprehensive — one clear signal beats six noisy ones.
Chart choices that serve narrative: anomalies → scatter plots with annotation; change over time → line charts with event markers; geography → choropleth or dot maps; composition surprises → treemaps or stacked bars with callouts; hidden subgroups → small multiples or ridgeline plots.
4 — Concrete Examples & Evidence
Abstract patterns become real through specific cases. For every major finding, find the one example that makes it tangible — the person, company, or place that best embodies the pattern, or the before/after that shows the mechanism.
Stack anchors in a single sentence rather than scattering them: "Imagine you're standing at the top of the funnel watching 7 in 10 customers quietly disappear before they ever see a price" gives you self-reference + spatial position + scale in one beat.
Plan the fade: start concrete, then introduce the formal abstraction. The metaphor is a bridge, not a destination — explicitly flag where it stops holding: "Think of it like a leaky bucket — though unlike buckets, the leak rate changes with customer tenure."
Statistics should flow within the prose, not interrupt it:
- Lead with the narrative beat, follow with the number that proves it.
- Round and contextualize: "nearly 3 in 4" lands better than "73.2%"; "twice the national average" beats "2.07×".
- Cite comparisons, not absolutes — the delta is almost always more meaningful than the level.
- One number per beat — don't cluster statistics. Let each one breathe.
5 — "Wait, Really?" Moments
Surprising findings need staging. Slow down at the moment of revelation — give it a short paragraph, let it land.
- Set up the assumption first: state what everyone believes before you overturn it.
- Name the surprise explicitly: "That's not a rounding error. That's a signal."
- One sharp emotion per story — fear, surprise, and reward tag memories for keeping, but use surgically: one vivid moment per piece. High emotional arousal narrows cognition, so deploy it at the revelation, not throughout.
- Use contrast: juxtapose the expected vs. the actual side by side.
6 — So What?
Embed implications in the narrative flow — don't save them for a bullet list at the end. Be specific: "This suggests reallocating onboarding resources to the first 72 hours" beats "investment in early customer experience may be warranted." End on a forward-looking note — what changes, what gets investigated, what gets tried.
7 — Honest Caveats
Acknowledge limitations without undermining the story. The detective doesn't refuse to name a suspect because the case isn't perfect — they state their confidence level and move forward.
- Surface the most important caveat once, framed as "what we'd want to confirm" rather than "reasons this might be wrong."
- Never hide a caveat in a footnote if it materially changes the interpretation.
- If the finding is robust under scrutiny, say so. Confidence is earned, not withheld.
Tone
Active voice. Present tense. Rhythm encodes — parallel structure, alliteration, and consistent beat make key phrases stick long after the data is forgotten. Read every paragraph aloud; if you stumble, rewrite it.
The test: would a smart, busy person who didn't ask for this read it to the end? If not, the hook isn't strong enough, the arc isn't clear, or the "so what" isn't earned.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
llm
Call LLM via CLI for transcription, vision, speech/image generation, piping prompts, sub-agents, ...
design
ALWAYS follow this design guide for any front-end work
demos
Use when creating demos or POCs
uv-uvx
Tips on using uv and uvx (Python build tools) effectively with GitHub, Torch, etc.
openai-docs
Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or explicit GPT-5.4 upgrade and prompt-upgrade guidance; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, and baseline placeholders you can edit before publishing or testing. Use when Codex needs to create a new local plugin, add optional plugin structure, or generate or update repo-root `.agents/plugins/marketplace.json` entries for plugin ordering and availability metadata.
Didn't find tool you were looking for?