data2story-pro

Data2Story

A data-journalist agent skill that turns any dataset into a verifiable, evidence-grounded multimodal story — a self-contained HTML article where every sentence traces back to the data or source that justifies it.

What it does

https://github.com/user-attachments/assets/7a2e2b65-3289-431d-b06a-230252df8774

• Dataset → finished article. Point it at a CSV, a folder of data, or a paper, and a fixed pipeline of seven roles produces a publishable HTML story end to end.
• Evidence-grounded. Every sentence and visual links back to its source. The pipeline emits a viewer.html inspector where you can click any claim to see the data, code, or citation behind it.
• Multimodal by default. Charts, images, video, audio, maps, and interactive elements — chosen from the data's actual properties, not a fixed checklist. Media generation routes through OpenRouter.
• Verifiable. Each run writes to its own versioned project folder and snapshots the exact skill versions used, so every result can be traced and re-checked.
• Progressive disclosure. Each role's SKILL.md holds only its instructions; bulky reference material (output schemas, field rules, lookup tables) lives in that role's references/ folder as JSON and is loaded only when needed.

Two versions. The repository ships two peer skills under skills/ — the richer, current build is data2story-pro; the paper's reproducible version is data2story.

Skill	Invoke	What it is
data2story-pro	/data2story-pro	Extended 14-agent build — verified media, interactive playgrounds, a cinematic cover, and a runnable in-page verify layer. See skills/data2story-pro/README.md.
data2story	/data2story	The paper's canonical 7-role pipeline — reproduces the article.

Updates

• [2026.6] Version 0.1.0: Optimized visual effects.
• [2026.6.9] Released the arXiv paper, GitHub repository.
• [2026.5.11] Data2Story was accepted as a Spotlight paper at the ACM Conference on AI and Agentic Systems workshop.

Installation & usage

Data2Story is an agent skill. The orchestrator lives in skills/data2story/SKILL.md — it works first-class with Claude Code, and equally with Codex, Cursor, Gemini CLI, and other agents.

1. Set your API key. Media generation routes through OpenRouter by default:

   export OPENROUTER_API_KEY=sk-or-...
   

2. Run the skill on a dataset:

   • Claude Code — make the skill available (place skills/data2story/ under ~/.claude/skills/, or run from inside this repo), then:

     /data2story data/pick_a_card
     

   • Codex / other agents — open the repo and ask the agent to follow the orchestrator:

     Read skills/data2story/SKILL.md and run the Data2Story pipeline on data/pick_a_card
     

3. Open the output: index.html (the finished article) and viewer.html (the evidence inspector).

Project structure

data2story-skill/
├── skills/
│   ├── data2story/           the paper's canonical 7-role pipeline    ·  /data2story
│   ├── data2story-pro/       the extended 14-agent build              ·  /data2story-pro
│   │                         └ self-contained: its own README, package.json, example data/
│   ├── frontend-design/      visual design system used by data2story
│   ├── frontend-design-pro/  extended design system used by data2story-pro
│   ├── dataviz-craft/        chart-craft recipes               ·  data2story-pro helper
│   ├── find-data/            dataset discovery & validation    ·  data2story-pro helper
│   └── sparring-partner/     idea-to-topic ideation            ·  data2story-pro helper
├── .claude-plugin/           marketplace.json  ·  installs either skill
└── assets/                   shared images

Inside each orchestrator, a role is a SKILL.md + a references/ folder (JSON schemas & lookup tables) + any scripts/ it runs — e.g. designer/scripts/ (OpenRouter media tools), inspector/scripts/ (the verify.py / generate_viewer.py verifier), detective/scripts/ (media fetch helpers).

The virtual newsroom

Think of it as a small newsroom in a box. Each role reads what the previous one produced, then adds its own artifact — a fixed pipeline that runs once, end to end.