| name | data-storytelling |
| description | End-to-end data narrative construction -- three-act structure, Knaflic/Duarte methodology, audience-first framing, and orchestration across analysis, visualization, and dashboard skills |
| tier | standard |
| applyTo | **/*story*,**/*narrative*,**/*datastory* |
Data Storytelling
| Property | Value |
|---|
| Domain | Data Analytics |
| Category | Narrative & Orchestration |
| Trifecta | SKILL.md + data-storytelling.instructions.md + datastory.prompt.md |
| Depends | data-analysis (findings), data-visualization (charts), dashboard-design (layout) |
Overview
This is the orchestrator skill. It transforms raw data into a complete, coherent narrative by activating analysis, visualization, and dashboard skills in sequence. The output is a self-contained artifact -- typically an HTML dashboard or scrollable report -- where every chart, annotation, and KPI serves the story.
The cardinal rule: data stories have arguments, not just observations. A collection of charts with captions is a report. A data story says "here's what happened, here's why it matters, and here's what we should do."
Module 1: Three-Act Data Structure
Every data story follows this arc:
| Act | Purpose | Content |
|---|
| Setup | Establish context and baseline | Who, what, when, where + "here's how things were" |
| Conflict | Reveal the surprise, problem, or gap | "But then this happened" / "X is not what we expected" |
| Resolution | Deliver insight and recommendation | "This means X, and we should do Y" |
Act Mapping to Dashboard Components
| Act | Dashboard Element |
|---|
| Setup | KPI cards showing baseline stats |
| Conflict | Hero chart revealing the anomaly |
| Resolution | Supporting charts + annotated insight |
Module 2: Audience-First Framing
Before choosing a single chart, identify who will read this and what decision it supports.
| Audience | Time Budget | What They Need | Artifact Style |
|---|
| Executive | 30 seconds | Headline + action recommendation | KPI dashboard, 5-Visual |
| Manager | 2 minutes | Context + options + trade-offs | Dashboard with filters |
| Analyst | Unlimited | Full data + methodology + caveats | Detailed report with drill |
| General | 1 minute | Simple story, familiar visuals | Scroll narrative, annotated |
Module 3: Knaflic Method ("Storytelling with Data")
The 5-step framework from Cole Nussbaumer Knaflic:
| Step | Action |
|---|
| 1. Understand context | Who is the audience? What do they need to do? |
| 2. Choose an effective visual | Story intent → chart type (SKILL cross-ref) |
| 3. Eliminate clutter | Remove everything that isn't data or supporting story |
| 4. Focus attention | Use color, size, position to direct the eye |
| 5. Tell a story | Connect visuals with narrative text |
Module 4: Duarte Contrast ("What Is" vs. "What Could Be")
Nancy Duarte's tension pattern drives engagement:
What Is: "Today, we process 500 support tickets per day"
What Could Be: "With the new model, we could process 2000 with the same team"
What Is: "Current SLA breach rate is 12%"
What Could Be: "Top performers achieve 3% -- the gap is process, not people"
Use this pattern when the story needs to motivate action, not just inform.
Module 5: Big Idea Worksheet
Force the story into one sentence before building anything:
[Subject/audience] should [action/decision]
because [evidence from data].
Examples:
- "The exec team should double Q4 marketing spend because every $1 of email marketing generates $3.20 in pipeline"
- "Engineering should prioritize Region B support because resolution time is 2.5x the company average"
If you can't write the Big Idea sentence, the analysis isn't done yet.
Module 6: Explanatory vs. Exploratory
| Mode | You Know the Story? | Goal | Output |
|---|
| Explanatory | Yes | Guide viewer to a conclusion | Annotated dashboard/report |
| Exploratory | No (yet) | Let viewer discover patterns | Interactive dashboard |
Default to explanatory for executives and general audiences. Use exploratory for analysts.
Module 7: Annotation as Narration
Annotations carry the argument. The chart is evidence; the annotation is the lawyer.
| Annotation Type | Purpose | Example |
|---|
| Title | State the insight (not the metric) | "Revenue grew 34% but growth is slowing" |
| Subtitle | Provide context | "Quarterly actuals, FY2024-FY2025" |
| Callout | Highlight the key data point | Arrow + "Q3 peak: $4.2M" |
| Caption | Add nuance below the chart | "Note: Q1 2025 includes one-time adjustment" |
| Footnote | Source, methodology, caveats | "Source: Internal CRM, excludes returns" |
Module 8: Orchestration Protocol
When /datastory is invoked, execute these phases in order:
Phase 0: Ingest
- Activate
data-ingest.cjs (or inline parse)
- Output: clean columnar data + metadata
Phase 1: Discover
- Activate
data-analysis skill
- Output: 3-5 insight statements with story intents
Phase 2: Visualize
- Activate
data-visualization skill for each insight
- Match story intent → chart type
- Output: chart specs with titles-as-insights
Phase 3: Arrange
- Activate
dashboard-design skill
- Choose layout by audience
- Place KPIs, hero, supporting, table, drill-down
- Output: dashboard scaffold
Phase 4: Narrate
- Apply three-act structure
- Write Big Idea sentence
- Add annotations as narration
- Validate: top-to-bottom read tells the story
- Output: self-contained HTML with narrative
Module 9: Quality Checks
Before delivering the final output:
| Check | Pass Criteria |
|---|
| Big Idea exists | One sentence captures the entire story |
| Three-act present | Setup → Conflict → Resolution identifiable |
| Titles are insights | No chart titled "Revenue by Quarter" (must be a sentence) |
| Color consistency | Same category = same color across all visuals |
| Source attribution | Every chart cites its data source |
| Audience match | Executive gets 5 visuals, analyst gets drill-down |
| 3-second test | Each chart conveys its point in 3 seconds |
| Annotation coverage | Hero chart has at least 1 callout annotation |
| Data freshness | Date range stated; "as of" timestamp included |
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| Chart collection | Charts exist but don't connect | Apply three-act structure |
| Data dump | Every metric shown "just in case" | Write Big Idea first, cut everything else |
| Insight-free annotations | "This is a bar chart showing revenue" | State what the data means, not what it is |
| Wrong audience depth | Analyst-level detail for C-suite | Match artifact to audience time budget |
| No recommendation | Story ends at "here's what happened" | Always include "so here's what we should do" |
| Over-designed | Fancy visuals, weak argument | Substance over aesthetics |
